Tigr-m2/tvision-m2/API.md

tvision-m2 - API reference

All names are in module tv. Import it qualified (IMPORT tv;) or with FROM tv IMPORT .... Every drawing call draws into an off-screen cell buffer; nothing reaches the terminal until Present (or Finish).

Lifecycle

procedure	description
Init() : BOOLEAN	enter raw mode + alternate screen, install SIGWINCH handler, create the desktop. FALSE if stdin is not a tty.
Done	leave the alternate screen and restore the terminal.
Cols() / Rows() : INTEGER	current screen size.
Resized() : BOOLEAN	TRUE if the terminal size changed or SIGWINCH fired since the last call (also re-clears the screen). Call it in your loop.
Finish	DrawTree + Present (redraw everything and flush).
DrawTree	draw the desktop, all views and the menu bar into the cell buffer.
Present	flush the diff to the terminal.

Colours and attributes

16 colours: Black Blue Green Cyan Red Magenta Brown LightGray DarkGray LightBlue LightGreen LightCyan LightRed LightMagenta Yellow White. A(fg, bg : INTEGER; blink : BOOLEAN) : Attr builds an attribute. Frame styles: SingleFrame, DoubleFrame.

Low-level screen

Clear(attr), Fill(x,y,w,h, cp, attr), DrawCh(x,y,cp,attr), DrawText(x,y, s, attr), DrawBox(r, style, attr), DrawShadow(r, attr), SetCursor(x,y), HideCursor. cp is a Unicode code point (CARDINAL); ASCII text can use VAL(CARDINAL, ORD(ch)).

Text helpers

TextLen(s) : INTEGER, CopyText(dest, s), AppendText(dest, s), PadText(dest, s, width), IntToText(dest, n, width).

Events

TYPE Event = RECORD
       kind : EventKind;        (* evNone evKey evMouse *)
       key  : INTEGER;          (* kChar kUp kDown kLeft kRight kHome kEnd
                                   kPgUp kPgDn kIns kDel kEnter kEsc kTab
                                   kBack kSpace kF1..kF12 kCtrlC kNone *)
       ch   : CARDINAL;         (* code point for kChar *)
       ctrl : BOOLEAN;          (* e.g. Shift-Tab gives kTab with ctrl=TRUE *)
       mx, my : INTEGER;        (* mouse position, 0-based *)
       mbtn : INTEGER;          (* 1 left, 2 middle, 3 right; held button during motion *)
       mpressed, mreleased : BOOLEAN;
       mwheel : INTEGER;        (* -1 up, +1 down *)
     END;

ReadEvent(e) : BOOLEAN waits up to ~0.1 s and returns FALSE on timeout.

HandleEvent(e) : INTEGER dispatches one event to the menu bar, the modal dialog (if any) or the desktop, and returns a command: cmNone, cmClose, or the tag of the activated control/menu item. Sender() : ViewPtr returns the view that produced it (NIL for menus).

Built-in commands: cmNone cmClose cmOK cmCancel cmYes cmNo.

View tree

TYPE VKind = (VGroup, VWindow, VText, VFrame, VInput, VButton,
              VCheck, VRadio, VList, VScroll);
     View = RECORD ... END;  ViewPtr = POINTER TO View;

procedure	description
NewView(kind, x,y,w,h) : ViewPtr	allocate a view (absolute screen coordinates).
AddView(parent, child)	append a child to a group/window.
DelView(v)	remove a view and its children.
SetText(v, s) / SetTag(v, n)	set text / command tag.
Desk() : ViewPtr	the desktop group; add top-level windows here.
BringToFront(v)	raise within its parent (z-order).
FocusView(v) / FocusNext(backwards)	set/advance keyboard focus.
MoveViewBy(v, dx, dy)	move a view and its descendants.

Fields are public: v^.rect, v^.text, v^.flags, v^.value, v^.minv, v^.maxv, v^.tag, v^.list, v^.focus. Flags: vfDisabled, vfSelected, vfFramed.

Widget kinds: VText (label), VFrame (box), VInput, VButton, VCheck, VRadio, VList (needs v^.list : ListDataPtr), VScroll (v^.value/minv/maxv), VWindow, VGroup.

TYPE ListData = RECORD
         items : ARRAY [0..255] OF ARRAY [0..63] OF CHAR;
         count : INTEGER;
     END;  ListDataPtr = POINTER TO ListData;

Editor

TYPE EditorData = RECORD ... END; EditorDataPtr = POINTER TO EditorData;

Declare one EditorData (a few tens of KB) per editor, attach it to a VEditor view, and it becomes a full multi-line editor with its own frame and a Ln/Col/Insert/Modified status row.

VAR ed : tv.EditorData; edp : tv.EditorDataPtr;
...
edp := CAST(tv.EditorDataPtr, ADR(ed));
tv.EditorInit(edp);                    (* empty; or EditorLoad below *)
tv.EditorAddLine(edp, "MODULE hello;");  (* build sample text *)
ev := tv.NewView(tv.VEditor, 2, 2, 60, 20);
tv.EditorAttach(ev, edp);
tv.AddView(win, ev);
tv.FocusView(ev);

procedure	description
EditorAttach(v, data)	tie an editor buffer to a VEditor view
EditorInit(data)	clear to a single empty line
EditorAddLine(data, s)	append a line (for building text)
EditorGetLine(data, i, VAR s)	read a line back
EditorLoad(data, path) : BOOLEAN	load a text file into the buffer
EditorSave(data, path) : BOOLEAN	save the buffer to a text file
EditorDirty(data) : BOOLEAN	TRUE if modified since load/save
EditorSetLanguage(data, lang)	enable highlighting for a language
EditorSetIndent(data, n)	auto-indent step in spaces (default 2; 0 = off)

Language constants: langNone, langModula2, langPascal, langOberon. With a language set the editor highlights keywords (white), strings (red), comments (grey; (* ... *) nestable, plus { ... } for Pascal and // for Pascal/Modula-2) and numbers (red). For Modula-2 and Oberon, finishing a word with a delimiter (space, Tab, Enter or punctuation) automatically upper-cases it if it is a keyword (begin -> BEGIN).

Auto-indentation (when a language is set): Enter copies the current line's leading spaces and adds one indent step after an open keyword (BEGIN, THEN, ELSE, ELSIF, DO, LOOP, REPEAT, RECORD, CASE, OF); a line whose first word is a close keyword (END, UNTIL, ELSE, ELSIF) is dedented one step. Configure the step with EditorSetIndent.

Keys: printable text, Enter, Backspace, Delete, arrows, Home/End, PgUp/PgDn, Tab (indent to a 4-column stop), Ins (insert/overwrite). The mouse places the cursor and the wheel scrolls.

Menus

MenuBarInit, MenuAdd(title), MenuItemAdd(text, tag), MenuSep, MenuBar(show : BOOLEAN). The menu bar is drawn on row 0; selecting an item makes HandleEvent return its tag. Mouse: click a title, click an item. Keyboard: F10, arrows, Enter/Space, Esc.

Dialogs

Build a centred modal window, add controls, then run it:

tv.Dialog("Options", 44, 12);
iName := tv.DlgInput("Name:", "Modula-2");   (* -> field index *)
cOn   := tv.DlgCheck("Enabled", TRUE);
rFast := tv.DlgRadio("Fast", TRUE);          (* radios auto-exclusive *)
rSafe := tv.DlgRadio("Safe", FALSE);
tv.DlgButton("OK", tv.cmOK);
tv.DlgButton("Cancel", tv.cmCancel);
cmd := tv.DlgRun;                             (* blocks; returns the tag *)
tv.DlgTextAt(iName, s);                       (* read an input *)
n := tv.DlgValue(cOn);                        (* 1 if selected *)

DlgRun returns the pressed button's tag, cmCancel on Esc, cmClose from the close box.

Message boxes

MessageBox(title, text, kind) : INTEGER where kind is mbOK, mbOKCancel or mbYesNo; returns cmOK, cmCancel, cmYes or cmNo. Message(title, text) is shorthand for MessageBox(..., mbOK).

Graphics backend (tvg)

tvg renders the same view tree into a tigr window instead of a terminal. Terminal programs do not link tigr.

IMPORT tv, tvg;
...
tvg.InitGfx("my app", 90, 30);   (* title, grid cols x rows *)
... build views with tv as usual ...
tvg.Finish;
WHILE ... DO
    IF tvg.ReadEvent(e) THEN cmd := tv.HandleEvent(e); ...; tvg.Finish END;
    IF tvg.Closed() THEN quit := TRUE END
END;
tvg.Done

Use tv.InitVirtual(cols, rows) (not tv.Init) when driving tv from a non-terminal backend; it sets the virtual screen size without touching the tty. tvg maps tigr keys and mouse to the same tv.Event; the cell grid is tv.Cols() x tv.Rows(), each cell CellW() x CellH() pixels. Text is drawn from tvfont (a bundled 8x16 monospaced VGA font, so no system font is required); box-drawing cells are rendered as line segments.

Building against the library

gm2 -fiso -c tvtty.def
gm2 -fiso -I. -c tv.mod
gm2 -fiso -I. tv.o myapp.mod -o myapp

For the graphics backend also build tvg.o (needs the tigr binding):

gm2 -fiso -I. -c tvfont.mod
gm2 -fiso -I. -I../modula2 -c tvg.mod
gm2 -fiso -I. -I../modula2 tv.o tvg.o tvfont.o \
     ../modula2/tigr.o ../modula2/helper.o myapp.mod -o myapp -lGL -lX11