| Did you know ... | Search Documentation: |
| Pack tui -- QUIET_GRID.md |
This spec defines the visual design for the ready-made components of library(tui/components). It uses five SGR attributes and a small set of Unicode glyphs. Frames have no side walls, and color is optional. Because the design is monochrome, it works in any terminal theme.
Scope: visual design only. Behaviour such as scroll math and key handling is defined elsewhere.
v3 amendments fit v2 to the framework:
negative (inverse) and faint (dim).negative. A non-interactive component may draw negative where that is unambiguous, such as a progress fill, but never toggles it. Weight is otherwise bold > normal.[x] and [ ]), never by an attribute.| Attribute | SGR | Used for |
|---|---|---|
bold | 1 | emphasis, headers, active tab, key names, status markers |
faint | 2 | Faint standing alone means disabled. Faint in conjunction with non-faint is used to indicate secondary importance. |
italic | 3 | input placeholders, always with their angle brackets (which carry the state) |
underline | 4 | rules (on spaces), frame borders, active tab, table header, input field |
negative | 7 | focus: the interactive component under the cursor, as hover([negative], …), the only toggled use; also fixed data fills where unambiguous (progress), never toggled |
crossed_out (9) is available, for example for removed lines in diffs. Other SGR extras, such as curly underlines, underline color and overline, are not supported by the framework.
Hard rules
22, and terminals render the combination inconsistently. A disabled component draws itself faint, without bold. Note that blocked content, such as a modal backdrop, is rendered faint as a whole, and in such specific cases its bold becomes faint bold.negative, when it gains or loses focus. Focus is the component under the cursor. A non-interactive component may draw negative where its shape makes that unambiguous, such as a progress fill, but its negative never changes with its state.char(C) in a hover style draws C in place of each character drawn while the component has focus. Hovers sharing a group variable switch together, so parts of a component (a button's end caps) can change shape with its focus. C must be one column wide.negative to a cell, or removes it from a cell that has it. A negative space without underline on the default background would then be blank, so it is underlined instead. A cell is highlighted once, however many highlights (and the cursor) apply.
Mockup notation used below: {i:…} negative, {b:…} bold, {d:…} faint, {u:…} underline, {t:…} italic. Flags combine, so {bu:…} is bold and underlined.
Focus. A component you activate (button, check box, list row, text input, scrollbar) shows focus as solid reverse video: what it draws becomes solid. That is not the same as negative. Usually negative does it, as hover([negative], …) over the whole component. But where a glyph is already half solid, as a scrollbar's thumb is, negating it only swaps which half is solid; such a component fills its glyphs instead, by glyph swap (section 3). In a component that shows the cursor (a text input), the cursor is the one normal-video cell (section 3). A focused component may also change glyphs for its shape, as a button's caps do.
Some interactive components are units (the framework's unit/1): though they cover many cells of the grid, the user experiences them as a single location. Any arrow key moves the cursor out of one in that direction, in one keypress. The cursor is hidden on a unit, because showing a position within it would contradict that experience; it still keeps its position, so that moves through units are consistent. Buttons, check boxes (the box with its label) and scrollbars are units. Text inputs are not, because the cursor marks the insertion point.
A frame keeps the size W×H given to it, and its content area stays (W−2)×(H−2), starting at 1-1.
{u:Title }
▐
content ... ▐
content ...
{u: ▄▄▄▄▄▖ }
To be iterated on. The active tab is bold and underlined, and inactive tabs are plain. Separate tabs with 2 spaces and put a rule on the next row.
{b:deploy} {bu:files} git logs
{u: }
Signs. + marks a collapsed node and - an expanded one. Leaves leave the 2-column sign slot blank.
Indentation. Names align in a column. Each depth level moves the name 4 columns right, and the sign hangs 2 columns to the left of the name.
No connector lines. Indentation alone shows the structure.
Sticky ancestor path. When ancestor rows have scrolled off the top of the pane, pin them at the top, one line per ancestor, outermost first, each laid out as its row. The last pinned line is underlined across the pane's width, a rule between the pinned lines and the rows scrolling beneath. For now the pinned lines are drawn only, not interactive. This calls for a header scroll component, a scroll area with pinned header lines (phase 2).
- notes/
abc.txt
xyz.txt
+ data/
- images/
123.gif
456.bmp
+ thumbnails/
[ ] unselected, [x] selected, [-] partial, all in normal video: no attribute marks the state. A checkbox counts as part of the name column. check_box(Title, Bool) gains a third value, partial, which toggles to true. With focus, `[x] Title` is negative as a whole.
The brackets keep - and x from being read as a tree sign or a status marker. The state is carried by shape, so it stays readable when the row is negative.
- [-] images/
[x] 123.gif
[ ] 456.bmp
+ [ ] thumbnails/
Right-align status markers in a fixed-width column.
| Marker | Meaning | Attribute |
|---|---|---|
ok | success | bold |
x | failure | bold |
! | warning (optionally with a count: `! 2`) | bold |
- | idle or not applicable | faint |
~ | pending | faint |
A button keeps the same width whether or not it is focused. Space, Return and a left click activate it, as now. The default action is whichever button has focus initially. The cursor is hidden (see Focus).
[ ] + -.▌ and ▐ (glyph swap, section 3). In negative, each cap fills its inner half, so the button reads as a pill with half-cell padding.
tui:alias_drawable(button(Label), hover([negative], Content, G)) :-
Content = hover([char('▌')], '┃', G) .> Label .> hover([char('▐')], '┃', G).
{i:▌Delete▐} ┃Cancel┃ focus on Delete
A progress bar is not interactive: its fill is negative but never toggled (section 2).
62%) starts 1 cell inside the bar. Label cells over the fill are negative. Label cells over the track are underlined, so the track is unbroken.
build {i: 62% }{u: }
>, then a space.negative from its cell, and a space left blank is underlined, so the cursor is one normal-video underlined cell.
{b:>} {tu:<file name>}{u: } unfocused, no value
{b:>} {u:deploy --env pr } unfocused
{bi:>}{i: deploy --env pr}{u: }{i: } focused, cursor after the text
{bi:>}{i: }{u: }{i: } focused, no value
modal(Dialog, Obstructed) draws Obstructed dimmed, and Dialog over it in a frame. A modal obstructs only what it is given, so one subview can have a modal while another stays usable.
faint is appended to every command's attributes, bold or not: the one place bold and faint combine (section 2). Cells drawn by highlight/1 stay highlighted.
{d:api/ ok 3 web/ -}
{d: }{u: }
{d: } {b:Delete 3 files?}
{d: } This can't be undone.
{d: }
{d: } {i:▌Delete▐} ┃Cancel┃
{d: }{u: }
{d:main.tf ok vars.tf ! 2}
There is no track; draw only the thumb, in normal video, at half-cell resolution: in each cell, the glyph depends on which halves the thumb covers.
| Halves covered | Vertical | Horizontal | Vertical, focused | Horizontal, focused |
|---|---|---|---|---|
| both | ▐ | ▄ | █ | █ |
| leading only (top or left) | ▝ | ▖ | ▀ | ▌ |
| trailing only (bottom or right) | ▗ | ▗ | ▄ | ▐ |
| none | space | space | space | space |
Focus. With the cursor anywhere on a scrollbar, its thumb is solid (Focus, section 5): the half-width glyphs of the vertical thumb fill the column's width, and the half-height glyphs of the horizontal thumb fill the row's height, as in the focused columns above. The thumb's length and position do not change. A scrollbar is a unit (Focus, section 5): the cursor is hidden, and an arrow moves it out in one keypress.
A focused row's negative stays inside the content area, so it never reaches the scrollbar's column.
row ... ▗ horizontal: ▗▄▄▄▖ row ... ▐ row ... ▝
↵ and ⇥. Every other key is a word: q, esc, `^C`.▁ is the floor, so the baseline is always visible.▄.
Unicode only. An ASCII fallback is listed in ROADMAP.md.
| Element | Glyph |
|---|---|
| Enter key | ↵ |
| Tab key | ⇥ |
| Truncation | … (only when truncating) |
| Spinner | `⠁⠂⠄⡀⢀⠠⠐⠈` |
| Sparkline | `▁▂▃▄▅▆▇█` |
| Buttons | `┃label┃`, focused `▌label▐` |
| Scrollbar thumb | `▐▝▗ / ▄▖▗`, focused `█▀▄ / █▌▐` |
Ambiguous width. …, ↵, ⇥ and `▄▌▐` have ambiguous East Asian width. A terminal set to draw them double width (common in CJK locales) will misplace what follows them. The framework takes every character to be one cell wide (see ROADMAP.md). Braille and the quadrants `▖▗▘▝` are always one column.
Do not use:
┃ in buttons is the only heavy line.
{b:deploy} {bu:files} git logs
{u: }
{u: - [-] images/ }
[x] 120.gif {b:ok} ▗
[x] 121.gif {b:ok} ▐
[ ] 123.gif {b:x} ▝
{i: [ ] 456.bmp ~ }
+ [-] thumbnails/ {d:-}
+ [ ] logs/ {d:-}
{bu: name cpu mem trend }
api 41% 212M {d:▁▂▃▅▇▆▄▃▂▁▂▃▅▆▇█▆▄▃}
web 12% 88M {d:▂▂▁▁▂▃▂▁▁▁▂▂▃▂▁▁▂▂▁▁}
{u: }
build {i: 62% }{u: }
{b:>} {u:deploy --env pr }
{b:⠂} {d:syncing} {b:↵} {d:open} {b:⇥} {d:next} {b:q} {d:quit}
check_box, button, input, scroll, frame, titled_frame, a rule/1) and the gallery. Phase 2 adds the new components (tabs, list, tree with a header scroll, table header, status markers, progress bar, modal, key hints, spinner, sparkline).cursor_hidden. Hiding is not the absence of a cursor: the cursor still has its position, it is only not drawn. The cursor is drawn last, and its cell is not highlighted if its attributes include cursor_hidden. Leaving in one keypress is unit/1, which also hides the cursor: it answers arrows with cursor_by.