Skip to content

TUI

Jump to bottom
Bjorn Stahl edited this page Sep 30, 2020 · 7 revisions

TUI

TUI is a developer facing API built on the SHMIF IPC system in order to provide a stable interface for creating text-oriented applications such as command-line shells, terminal emulators, file manager, configuration tools and so on.

Its purpose is to provide a middle ground between the high level UI toolkits and frameworks like HTML5, GTK, QT - and that of text-based ones like NCurses/Turbo-vision.

Its goal is to completely decouple command line workflows from old terminal protocols like VT100. This will make them faster, safer and more reliable, with better integration with outer window management and display systems.

The idea and status thus far is covered in two blog posts (2016-2017):

  1. Dreaming of a terminal-free CLI
  2. Dawn of a new Command Line Interface

The core of the argument is that the high-level UI frameworks are:

  1. Massive codebases that are hard to review and extend.
  2. Exorbitant amount of system dependencies, directly through libraries for parsing and rendering, and indirectly through reliance on other IPC systems, Display Server and so on.
  3. Expensive to develop for (time, effort) and, for small textual-UIs, prohibitively so.

At the same time, Curses- like text user interfaces (limiting it to 10 reasons):

  1. Lack system integration (window resizing, popups, window borders, clipboard, ...)
  2. Cannot be composed - piping multiple curses UIs together will fail to work, breaking your terminal emulator state or output garbage.
  3. Consumes STDIN/STDOUT, preventing their position in 'pipes and filters' chains and making large cut/paste operations blocking.
  4. Broken internationalization - 'locales' are static due to environment variables, text rendering facilities are strictly grid-bound.
  5. Missing synchronization - terminal emulators are forced to 'guess' if it is safe to draw based on timing and buffer states, with subtle race condition effects to follow.
  6. Mixes contents and meta-data in the input/output chain.
  7. Limited input model - even basic mouse controls are unreliable. Escape keys gets confused with escape character for parsing.
  8. Colors are unpredictable and unreliable - mapping is defined as 'red is now green' from a context dependent palette (termcap+emulator).
  9. Cannot embed other types of media, only fake the appearance embedding through unscalable hacks such as Sixel.
  10. Are awful to code for (ncurses in particular).

Arcan-TUI combats all of these, in a legacy friendly way.

Use

A normal Arcan installation is currently required, as well as a window manager. The built-in 'console' should work just fine.

arcan console

Is enough to get the Arcan terminal emulator running. It is written using TUI. This also has an experimental command-line shell, that can be activated by setting the argument to afsrv_terminal to cli (ARCAN_ARG=cli environment variable).

Language Bindings

These are kept in a separate repository, tui-bindings

Widgets

To provide a shared interface for some key primitives, a basic set of widgets are planned and being implemented.

Current:

  • Buffer Window for Hex, ascii, ... view (arcan_tui_bufferwnd)
  • List Window, presenting a list of options (arcan_tui_listwnd)
  • Readline (arcan_tui_readline)

Planned:

  • Line Window, providing a line-oriented view, scrollback buffers etc.

Help Wanted

Here is a short list of suggested pieces that would improve the current state, but are secondary to other development in the Arcan ecosystem.

  • Language Bindings - Contribute to the separate bindings repository.

  • Curses implementation - decoupling dispatch/input from shmif, and provide a 'simple' curses fallback that renders with TPACK.

  • Debugger Frontend -

  • NeoVIM and Kakoune UI - These two text editors have good decoupling between core logic and UI logic, making them good targets for advanced TUIs that can make good use of most of the feature set. An early version of NeoVIM integration can be found in this repository.

  • Document Reader - A viewer for simple formats like man-pages and markdown would also greatly help showcasing some of the potential.

Text Rendering Subproject

A number of things should be done to get the best possible text rendering:

  1. DONE: Server side packing format (TPACK)
  2. Glyph atlas and atlas-aware renderer (GPU friendlier drawing)
  3. Caching / sharing of atlases between clients with the same font, DPI and pt (memory footprint reduction, reduced initial rampup storm)
  4. Fullscreen 'direct rendering' with cursor overlay (less redraw)
  5. Simplified substitution table format to TUI clients (can drop freetype dependency, reduce initial font transfer cost)
  6. MSDF substitutions into glyph atlas (3D / infinite zoom)
  7. Text_surface (lua level) (re-use same infrastructure for wm side drawing)
  8. Re-add shaping with kerning feedback buffer
  9. Unlock / client processing thread (faster client-server synch)
  10. Respect scrolling regions (configurable smooth scrolling)
  11. Complex internationalization (RTL lines)
  12. Mouse motion binning and offsetting (reduce event transfers further)

Development

There are a few key applications that drive the development forward and to help finding rough edges in the API itself. The biggest, and most useful one, at the moment is the built-in terminal emulator. See the source-code in:

src/frameservers/terminal/default/arcterm.c

While not a particularly complex application, it shows how to get the basic loop and event handlers going.

With documentation still pending, so far, please refer to the headers in shmif/arcan_tui* for the C library headers. When all components have matured sufficiently, TUI and the related projects will move out of the main Arcan source repository into one of its own.

Clone this wiki locally