| Did you know ... | Search Documentation: |
| Pack tui -- prolog/tui.pl |
A TUI framework for SWI-Prolog, inspired by TEA (The Elm Architecture): app/4 runs an app from its state, a view that draws the state, and an update that turns events into a new state. Components are defined via the multifile hooks alias_drawable/2 and at_event_is/3.
This module gives the event loop and the core drawables. Ready-made,
styled components are opt-in: load library(tui/components).
A view is a drawable: a term saying what to draw on the grid of terminal cells. Positions are X-Y, column and row, from 0-0 at the top-left of where a drawable is drawn. Drawables are drawn in order, and where two draw the same cell, the one drawn last wins.
column(Drawables).format("~q", [Term]).translate(X-Y, Drawable).port(Size, Drawable), with Extent unified with the furthest
cell Drawable draws, MaxX-MaxY, clipped or not.up_left, up, up_right, left,
center, right, down_left, down or down_right. Elsewhere,
just Drawable.Drawables are placed next to each other with four operators, exported by this module. Each pair has the same layout, and differs only in which side is drawn last, so is in front where they overlap (when one is translated, or draws beyond its extent):
A .> B: A, then B to its right, B drawn lastB .< A: the same layout, A then B to its right, A drawn lastA .\/ B: A, then B below it, B drawn lastB ./\ A: the same layout, A then B below it, A drawn last
Any other term is an alias, expanded by alias_drawable/2: the core
aliases, such as row(Drawables) and unit(Drawable), and those of
opt-in libraries, such as button(Label). They are all documented
there.
bold, faint, italic, underline, negative, crossed_outfg(C) and bg(C), and the bright hfg(C) and hbg(C):
C is black, red, green, yellow, blue, magenta, cyan,
white, default, or an index 0..255; and fg(R, G, B),
bg(R, G, B)char(C): each character drawn shows as C, a character one column
widecursor_hidden: the cursor is not shown on what is drawn (it keeps
its position)
DrawableTerm must be compound: atoms, strings and numbers always draw
as text, so a clause for one is never used. Write a component without
arguments with empty parentheses, e.g. logo().
scroll(Id) : scroll(20-15, Offset, Content)
update receives scroll(Id)-(0-5) where the scroll produced scroll-(0-5).
box_chars(Horizontal, Vertical, TopLeft, TopRight,
BottomLeft, BottomRight), or one of the standard sets thin, thick,
double..\/.hover(Style, Term), in the hover group Group: an unbound variable
that hovers sharing it turn on together, when the cursor is over any of
them. For example, a button whose end caps change shape on focus:
tui:alias_drawable(button(Text), hover([negative], Content, G)) :-
Content = hover([char('▌')], '┃', G) .> Text
.> hover([char('▐')], '┃', G).
png(Bytes): a PNG file's contentsrgba(PW-PH, Bytes): PW×PH pixels, 4 bytes eachrgb(PW-PH, Bytes): PW×PH pixels, 3 bytes eachfile(Path): a file the terminal reads itself (PNG); only when the
terminal runs on the same machineBytes is a string or code list of octets (0..255), as read from a binary stream. Text decoded on reading (e.g. as UTF-8) gives a corrupted image; this cannot be detected.
Only terminals supporting the Kitty graphics protocol show images; see
graphics(Bool) in the terminal_properties(Properties) event.
Elsewhere its cells show as unknown characters.
.>.empty (cells abut), space (a blank between cells), or thin,
thick or double (a border around and between cells).hover(Style, Term, Group): Style applies while
Group is off, and is dropped when the cursor turns it on. For example, a
field underlined except when focused, where it is negative:
hover([negative], unhovered([underline], Field, G), G)
library(tui/components)┃Label┃, highlighted when focused. A unit (see
unit(Drawable)).
' ', return or mouse(press, left) become button-pressed[x] Title, [ ] Title or [-] Title for
Bool true, false or partial, highlighted when focused. A unit (see
unit(Drawable)).
' ', return or mouse(press, left) become check_box-NewBool:
true becomes false, the others trueframe(Size, Contents), with Extent unified with the furthest cell
Contents draws, MaxX-MaxY.scroll(Size, Offset, Content); not meant to be drawn directly.> and an underlined
field holding Value, or <Placeholder> while Value is unbound (nothing
if Placeholder is ''). Highlighted when focused, with the cursor shown
in it; the cursor stays within the text.
backspace deletes before the cursor, delete at itpaste(Text) inserts Text, its line breaks as spaces
Each edit becomes input-NewValue, NewValue a string.
frame(Size, Contents)), scrolled by Offset,
X-Y (each 0 or negative), with a scrollbar on each axis where it does
not fit. A scrollbar is highlighted when focused, and is a unit (see
unit(Drawable)).
shift+up, shift+down, shift+left and shift+right drag what
is under the cursor: the content a row or column, or on a scrollbar
its thumbpage_up and page_down scroll a pagemouse(scroll, Dir) scrolls a row or column
Each becomes scroll-NewOffset; at the limits, nothing.
scroll(Size, Offset, Content); not meant to be drawn directly.frame(Size, Contents)) with Title, any drawable, at the
start of its top rule.titled_frame(Size, Title, Contents), with Extent as in
frame(Size, Contents, Extent).scroll(Size, Offset, Content); not meant to be drawn directly.
A cursor movement bubbles as moved(Direction) from where the cursor
was, and, for an arrow key no component claimed, as arrived(Direction)
where it lands. The cursor moves regardless; what they are rewritten
to is handled with the cursor moved. A mouse event bubbles where it
happened (see app/5).
Besides events for update, a component may produce a direction, which
moves the cursor one cell, or cursor_by(DX-DY), which moves it by an
offset; e.g. to keep the cursor after an edit, or, answering
arrived(Direction), on a cell where it belongs. noop takes the event
to do nothing: it bubbles no further, and update never sees it.
The following predicates are exported, but not or incorrectly documented.