Skip to content

Demo application

cmd/demo is a complete termforge application with no domain in it. It exists to answer one question: what does an app have to write, and what does the framework already do? Everything visible — split geometry, separator drag, wheel scrolling, text selection, command parsing, Tab completion, key sequences — comes from termforge. The demo supplies two tabs of panes (a third, with an embedded Lua console, when built with -tags lua), eleven commands, and a help window.

Companion docs: UI_ARCHITECTURE.md · WINDOW_MANAGEMENT.md · INPUT.md · COMMAND_SYSTEM.md


Table of contents


Run it

go run ./cmd/demo

No flags and no configuration; -version prints the build version and exits. Press ? or type :help for the reference window, and Ctrl-D to leave.


What you see

Two tabs, listed in a one-row bar across the top. gt / gT, :tab next|prev, or a click on a title switches between them; each tab owns a whole split tree, so switching swaps the geometry, the focused pane and the ratios in one move. Built with -tags lua (task run:lua), a third tab, lua, shows a pixel matrix over an embedded Lua console; see Embedded Lua.

 1 panes  2 columns             <- TabBarWidget, one chrome row

┌──────────────┬──────────────┐  ┌─────────────────────────────┐
│              │ table        │  │ notes                       │
│ main         ├──────────────┤  ├───────┬──────────┬──────────┤
│              │ side         │  │ keys  │ mouse    │ about    │
├──────────────┴──────────────┤  │       │          │          │
│ log                         │  │       │          │          │
└─────────────────────────────┘  └───────┴──────────┴──────────┘
        tab 1 — panes                   tab 2 — columns
Pane Widget Why it is there
main demo.ScrollPane over ScrollDocument Read-only text: scrolling, search, selection
table termforge.TableWidget Columnar list with row selection; its rows are a cheat sheet of the widgets termforge ships
side demo.ScrollPane Second text pane, so focus movement has somewhere to go
log termforge.LoggerWidget Leveled log pane fed by ctx.Log; warnings from :close and unknown :b names land here

The shape is deliberately nested rather than a single row of panes:

Horizontal( Vertical( main, Horizontal(table, side) ), log )

Hexagons are split nodes (the separators); rectangles are leaf panes.

graph TB
    S1{{"SPLIT (horizontal)<br/>ratio 0.70<br/>workspace over log"}}
    S2{{"SPLIT (vertical)<br/>ratio 0.62<br/>main beside the right column"}}
    S3{{"SPLIT (horizontal)<br/>ratio 0.5<br/>table over side"}}
    L1["LEAF: main"]
    L2["LEAF: table"]
    L3["LEAF: side"]
    L4["LEAF: log"]
    S1 -->|First / top| S2
    S1 -->|Second / bottom| L4
    S2 -->|First / left| L1
    S2 -->|Second / right| S3
    S3 -->|First / top| L2
    S3 -->|Second / bottom| L3

Three split nodes, so three separators on screen, and the innermost one spans only the right column: a split node divides the rectangle it was given, not the whole screen.

That gives drag-resize something real to act on — dragging the inner table/side bar must not move the outer main/log one. demo.BuildDefault splits evenly first and sets the ratios once the shape is final: 0.70 for the workspace band over the log, 0.62 for main against the right column, 0.5 between table and side.

The second tab is there to be a different shape rather than a second copy of the first. demo.BuildColumns nests its vertical splits inside each other:

Horizontal( notes, Vertical( keys, Vertical(mouse, about) ) )

Three columns under a banner, so Ctrl-W l crosses two separators in a row and the banner's separator meets all three — paths the first tab's tree never exercises. Its panes are static text: the key list, the mouse gestures, and a note on what the demo does and does not supply.


Commands

Registered in ExapData with the command DSL; :window is a group with four children, :b and :help are rest-arg leaves with completion callbacks.

Command Does
:window left\|right\|up\|down Move focus to the adjacent pane
:tab next\|prev Switch tabs, wrapping at either end
:b main\|side\|keys\|about\|… Focus a pane by name, switching tabs to reach it (Tab completes)
:vs / :split Split the focused pane side by side / stacked
:close Delete the focused pane; refuses the last one and logs a warning
:only Collapse the tree to the focused pane
:equal Reset every split to an even ratio
:clear Clear the focused pane, when it implements Clearable
:help [command] Open the floating window, for one command or for everything
:quit Close the focused pane; exit once it was the last. :quit! (:q!) exits at once

:quit follows Vim and peels off one pane at a time, while :q! and Ctrl-D exit immediately however many panes are open (Ctrl-D works in insert mode too, so it never reaches a Lua console as end-of-file). Closing the last pane of a tab exits too: TabWidget has no close operation yet, so the demo never has a tab to fall back to.

:b is the one command that reaches across tabs. Each pane is registered under a name with the tab that holds it, so naming a pane in the other tab switches to it first.


Keys and mouse

Key Action
? Open the help window
gt / gT Next / previous tab
: Command mode
Tab Complete a command or pane name (wildmenu bar)
i / Esc Insert mode / back to normal, and close the help window
Ctrl-W h/j/k/l, Ctrl-W <arrows> Move focus
j / k Scroll the focused pane
Ctrl-D Exit, in normal and insert mode
Pointer Action
Click a tab title Switch to that tab (TabBarWidget.TabAt)
Click a pane Focus it (WidgetTree.FocusAt)
Drag a separator Resize the two adjacent panes only
Wheel Scroll the pane under the pointer, focused or not
Drag inside a pane Select text; middle-click pastes (PRIMARY)
Double-click a status label Copy the pane name
Click the command line Focus it and place the caret at that column

The demo's own mouse code decides only which surface gets the event. Focus, drag, scroll, selection, and the status-label copy are all framework behavior reached through WidgetTree.FocusAt and TabWidget.HandleEvent.


Source map

cmd/demo is the application; internal/demo holds its panes and layout. Neither is part of the library, and scripts/check_imports.sh enforces that no termforge package imports them.

File Contents
cmd/demo/main.go main, -version, construct and run
cmd/demo/app.go DemoApp struct — embeds *termforge.App, sets App.Api = a
cmd/demo/setup.go Init: builds the two tabs' panes and trees, chrome, mode handlers
cmd/demo/lua_tab.go The optional third tab (-tags lua): matrix over the Lua console; lua_tab_off.go is the no-op stub without the tag
cmd/demo/actions.go The command tree and every command handler
cmd/demo/keybindings.go Normal and insert key registries, mode transitions
cmd/demo/input.go Mouse routing, resize band math, per-mode key handlers
cmd/demo/help.go Help text as app data, plus the :help pages
internal/demo/scroll_pane.go ScrollPane — read-only text pane
internal/demo/layout.go BuildDefault / BuildColumns — one tree per tab, with their ratios
internal/demo/help_overlay.go HelpOverlay — floating, scrollable window
internal/demo/matrix.go, effects.go Matrix pixel grid, its half-block widget, and the fire/plasma effects
internal/demo/lua_pane.go, matrix_lua.go -tags lua only: the Lua console pane and the mat.* Go functions exposed to it

How it is wired

Init registers the top-level widgets, and the App draws them in registration order into one grid:

a.AddRowWidget(a.tabBar, 1)            // tab titles: a fixed row at the top
a.AddWidget(a.tab)                     // workspace: tabs + split tree, fills what is left
a.SetCmdline(a.cmdWidget)              // paste target in command mode
tree.PinBottom(a.cmdWidget, 1)         // ':' command line — a pinned leaf, not a band
a.AddFloatingWidget(a.help, helpRect)  // floating window, painted last

How a widget is registered is also how it is placed. The tab bar is a fixed row and comes first, so it takes the top line; the workspace fills the rest. The cmdline is a 1-row leaf pinned to the bottom of the split tree, so the line above it is that split's own separator. The help overlay owns no layout space at all — helpRect positions it per frame. Order is the whole trick behind the floating window: added last, it paints over the workspace. Nothing recomputes rects on resize; the App's WidgetsList rebuilds them from the new canvas.

The cmdline is one widget shared by both trees, because it is global and the tree it is pinned into is per tab: wireTree pins it, and applies the rest of the wiring a freshly built tree does not carry — status clipboard, resize hook, equalalways. Only the active tab is laid out and painted, so the shared widget is only ever drawn once per frame.

helpRect caps the window at 78×24, keeps a margin of panes visible around it so it reads as floating, and returns the zero Rect when the terminal is too small to frame a window — the overlay's Draw returns early without geometry, so a tiny terminal simply shows no window instead of crashing.

Input is split by interaction mode, each registered with RegisterModeHandler:

Mode Handler Behavior
Normal handleNormalKey Help window first if open, then key bindings, then the focused widget's HandleFocusKey
Insert handleInsertKey Esc only, everything else goes to the focused widget
Command handleCommandKey Everything to CmdWidget; Enter deactivates and returns to normal

Patterns worth copying

Ratios survive splits. The demo turns equalalways off in both AppState and the layout, so the default ratios and any separator drag persist. The cost is that Split turns a leaf into a split node while leaving that node's Ratio at the leaf's old value — usually 1, which would give the new pane a one-column sliver. equalalways normally hides this by rebalancing everything; splitWith instead evens out just the split it created, and :equal rebalances on demand.

Help lives in the app, not the framework. CommandNode carries no description field, so help.go keeps a demoCommand table of its own rather than pushing documentation into the command tree. :help <command> and its Tab completion both read that table.

A floating window is a widget, not a compositor. HelpOverlay paints its frame cell by cell rather than through Canvas.DrawVerticalLocal, because those helpers run border composition and would join the window frame into the pane separators underneath. While it is visible it takes the keyboard and the pointer, and a click outside closes it and falls through to the pane below.

Deleting the last pane is the caller's policy. WidgetTree.DeleteFocus reports true when it declined, which :close turns into a logged warning and :quit turns into exiting the app.

One accessor narrows the Layout. With two tabs there is no single tree to keep in a field, so DemoApp.Layout() type-asserts the active tab's Layout to *WidgetTree and every command goes through it. Nothing has to be updated when a tab is switched in, and a tab hosting some other Layout later would show up as a nil return rather than a stale pointer to the tree it replaced.