Window Management¶
termforge organizes panes through a Workspace containing a recursive split tree, managed at the top level by tabs and a global command line. Each workspace pane shows a per-pane status line at its bottom edge when focused.
Companion docs: UI_ARCHITECTURE.md · INPUT.md · RENDERING.md
Table of contents¶
- Top-level layout
- Workspace concept
- Split tree architecture
- Horizontal and vertical splits
- Splitting at runtime
- Tab is a generic Layout container
- Tab management
- Command line
- Per-pane status line
- Global application state
- Planned window operations
Top-level layout¶
The root UI is a workspace that fills the screen, with the command line pinned to its bottom edge inside the split tree:
Root
├── TabBar (fixed height)
└── Workspace (split tree)
├── panes (ratio sized)
└── CmdLine (pinned leaf, exactly 1 row)
+--------------------------------------------------+
| Tab1 | Tab2 | Tab3 |
+--------------------------------------------------+
| |
| Workspace |
| |
+--------------------------------------------------+
| : command line |
+--------------------------------------------------+
graph TB
Root["Root"]
TabBar["TabBar<br/>(fixed height)"]
Workspace["Workspace<br/>(split tree, fills the screen)"]
Panes["panes<br/>(ratio sized)"]
CmdLine["CmdLine<br/>(pinned leaf, 1 row)"]
Root --> TabBar
Root --> Workspace
Workspace --> Panes
Workspace --> CmdLine
Source: diagrams/top_level_ui.mermaid
Design decision: the command line is a pinned leaf at the bottom of the tree (WidgetTree.PinBottom(cmdWidget, 1)), not a chrome band:
- The line above it is that split's own separator, so no layout draws a border outside its own rect.
- It is still a stable anchor:
FixedSecondholds it to exactly one row at the bottom edge, whatever the pane ratios do, andCollectLeaveshides it so focus movement,:close,:onlyand separator drags behave as if it were not in the tree. - Transient chrome (wildmenu, help, future message bars) is not in the tree. It goes in the App's floating tier, which reserves no space — no popup compositor.
Note: the command line is global, but it lives in a per-tab layout, so every tree has to be given it (PinBottom at setup, again after a :layout remount, and once per tab). Sharing one CmdWidget across tabs works because only the active tab is laid out and painted, so the widget is drawn once per frame wherever the user is. If that ever stops holding, the alternative is an App-level root compositor owning a fixed-height bottom region for every tab at once.
App chrome is a WidgetsList — the flat Layout at App level, the counterpart of WidgetTree inside the workspace. Apps declare the placement once at setup time and never compute rects on resize:
a.AddRowWidget(a.tabBar, 1) // TabBarWidget: fixed row, top of the screen
a.AddWidget(a.tab) // TabWidget: fills what the rows leave
a.SetCmdline(a.cmdWidget) // paste target in command mode
tree.PinBottom(a.cmdWidget, 1) // CmdWidget (: line), bottom of each tab's tree
a.AddFloatingWidget(a.completionPopup, popupRect) // rect recomputed per frame
a.AddFloatingWidget(a.help, helpRect)
WidgetsList.BuildLayout stacks any rows top to bottom in registration order and gives the fill widget everything left over; floating widgets are placed by their callback and contribute nothing to the row math. TabWidget.Draw uses its full assigned rect, so with a tab bar on row 0 the workspace spans rows 1..H-1, with the cmdline on H-1 and its separator on H-2. App.Draw paints in registration order, so anything floating registered after the tab covers it.
Geometry is rebuilt on every frame and on every UpdateCanvas, so a resize needs no application hook at all — AppApi has none. App.WidgetRect(w) returns the rect a widget was given, for mouse routing; the cmdline is the exception, since it lives in the tree — use WidgetTree.PinnedBottomRect().
Extending chrome (no popup layer)¶
Three placements, and the choice is about lifetime, not looks:
| Chrome | Placement | Example |
|---|---|---|
| Transient window | AddFloatingWidget at App level |
wildmenu (CompletionPopupWidget), help overlay |
| Permanent full-width edge | pinned tree leaf via PinBottom |
the : command line |
| Permanent band outside the workspace | AddRowWidget |
the tab bar (TabBarWidget) |
For an overlay:
- Register it with
AddFloatingWidget, last, so it paints over the workspace. - Gate on your own visibility flag in both
DrawandHandleEvent—WidgetsList.HandleEventbroadcasts to every registered widget. - Own keys with a
platform.Mode(likeModeCompletion), not with tree position. - Paint the frame with
SetContent, neverDrawHorizontalLocal/DrawVerticalLocal: those run border composition and would fuse the window frame into the pane separators underneath.
Do not introduce a separate popup/z-order system. Registration order is the z-order, and a floating widget already costs no layout space.
Workspace concept¶
The Workspace is everything below the TabBar, cmdline row included. It is the only place where recursive splits exist. Applications commonly add their own shell type above the layout to own pane policy (which pane may host which view, placement rules, marks); termforge deliberately has no opinion there.
Workspace panes are widgets — views bound to application models owned by the application's controllers. A typical mapping:
| Model | Widget (view) | Purpose |
|---|---|---|
| Text buffer (per document) | Viewport pane |
Scrollable text, gutters, row markers |
| Row/column collection | TableWidget pane |
Sortable, selectable list |
| Child process on a PTY | CompositeTerminal pane |
Live process output + input |
| Line-based REPL | ConsolePane |
Scrollback + walking prompt |
| Logger sink | LoggerWidget |
Application log |
Application (composition root)
├── domain services → own models
├── controllers → model lifetime, not pane lifetime
├── view registry → widgets created on demand
└── Workspace → TabWidget (geometry + focus)
Each pane is a leaf widget in the split tree. The Workspace band does not draw content itself — it delegates geometry to WidgetTree.BuildLayout. Models exist whether or not a widget is currently displaying them.
Split tree architecture¶
The split tree is a full binary tree where internal nodes are splits and leaves are widgets.
graph TB
WS["Workspace"]
VS["VerticalSplit"]
MAIN["Main pane"]
HS["HorizontalSplit"]
LIST["List pane"]
CON["Console"]
WS --> VS
VS --> MAIN
VS --> HS
HS --> LIST
HS --> CON
Source: diagrams/split_tree.mermaid
Example ASCII layout matching the diagram above:
Node types¶
Design decision: binary splits (not n-way splits) simplify ratio math and border drawing. An n-way toolbar layout can be built by composing binary nodes — the same approach used by Emacs window management and many IDE dock systems.
A separator is a node¶
The most important property of this tree, and the easiest one to miss: it is not a tree of panes. Internal nodes and leaves mean two completely different things.
Every visible separator on screen originates from an internal split node. Every actual pane/widget is a leaf node.
| Node kind | Marked as | What it is | Holds a widget? |
|---|---|---|---|
| Split | \| vertical — divides into left / right- horizontal — divides into top / bottom |
the division itself, i.e. the separator line you see | No — Split sets node.Widget = nil |
| Leaf | the widget name (MAIN, LOG, LIST, …) |
one pane | Yes |
A split node owns a direction, a Ratio, and two children. It takes the rectangle handed to it, keeps 1 cell for the separator it draws, and gives what remains to First and Second. So counting the split nodes in a tree tells you exactly how many separator lines appear on screen.
The two cases below build this up: one separator, then a nested separator. For a
six-pane tree built from five splits, see how gdbforge composes its
shipped default layout.
Case 1 — simple split¶
One split node, two leaves. The split node is the vertical line between the panes.
TREE SCREEN
| <- SPLIT NODE +----------+----------+
/ \ (vertical separator) | | |
/ \ | MAIN | LOG |
MAIN LOG ==> | | |
^ ^ +----------+----------+
LEAF LEAF ^
this separator *is*
the "|" split node
Hexagons are split nodes (the separators); rectangles are leaf panes.
graph TB
S1{{"SPLIT (vertical)<br/>ratio 1/2<br/>draws the separator"}}
L1["LEAF: MAIN"]
L2["LEAF: LOG"]
S1 -->|First / left| L1
S1 -->|Second / right| L2
Case 2 — nested split¶
Replacing a leaf with a split node is what creates nesting. Here the root's Second child is no longer a pane but another separator, so the right half of the screen gets divided again — this time top/bottom.
| <- SPLIT NODE / separator (vertical: left / right)
/ \
/ \
MAIN - <- SPLIT NODE / separator (horizontal: top / bottom)
/ \
LOG STATS
^ ^
LEAF LEAF
TREE SCREEN
| +---------+--------+
/ \ | | LOG |
MAIN - ==> | MAIN |--------| <- the "-" split node
/ \ | | STATS |
LOG STATS +---------+--------+
^
the "|" split node
Two split nodes, so two separators. Note the - separator spans only the right column: a split node divides the rectangle it was given, not the whole screen.
graph TB
S1{{"SPLIT (vertical)<br/>ratio 1/2"}}
C["LEAF: MAIN"]
S2{{"SPLIT (horizontal)<br/>ratio 1/2"}}
G["LEAF: LOG"]
K["LEAF: STATS"]
S1 -->|First / left| C
S1 -->|Second / right| S2
S2 -->|First / top| G
S2 -->|Second / bottom| K
Horizontal and vertical splits¶
SplitDir |
Orientation | First child position | Separator |
|---|---|---|---|
Vertical |
Left | Right | Left | Vertical line (│) |
Horizontal |
Top / Bottom | Top | Horizontal line (─) |
Layout algorithm (widget_tree.go):
- Compute first-child size from the split node's
Ratio, clamped tominPaneCells. - Reserve 1 cell for the separator.
- Assign remaining space to second child.
- Recurse into both children with child
Canvasvalues (WithRect).
Ratio is input only. BuildLayout reads Ratio (in verticalSplitRects / horizontalSplitRects) and never writes it back, so geometry is a pure function of the ratios and the canvas: resizing the console scales panes and a shrink-then-grow restores them exactly. Ratio changes only on Split / DeleteFocus (via Units()-weighted ComputeRatios, when equalalways is on), on a separator drag, and when a named layout is applied.
Border drawing: separators are written into the shared Grid during BuildLayout, not by individual widgets. This ensures corners align when splits nest.
Splitting at runtime¶
What happens:
- The focused leaf becomes a split node.
Firstretains the original widget;Secondgets the new widget.- Focus moves to
First(original pane). Ratiois set to0.5.
Design rationale: splitting at focus matches Vim and Emacs user expectations. Alternative designs (split always right, pick target pane first) may be added as commands later.
NewTabTwoHozSplitWins builds a tree with an initial horizontal split of two widgets. Applications define named layouts — builder functions that assemble a whole tree — and apply them with a command such as :layout <name>:
A builder returns a *WidgetTree; the application mounts it with TabWidget.SetLayout and then re-applies any startup wiring (status clipboard, resize hook, equalalways, leaf marks) that a freshly built tree does not carry.
Register layout names through AppState.RegisterLayout so completion and :layout validation see them. Per-layout key policy is application state, not something Tab tracks.
Tab is a generic Layout container¶
A Tab hosts any termforge.Layout — the split tree today, and any future layout (a form, a text viewer, a different window arrangement, a whole embedded app):
A Layout draws no status line of its own — in the tiling tree each pane paints its own status row — which is why Widget carries only HandleEvent and Draw, and DrawStatusLine lives on the separate NodeWidget interface that leaves implement.
Two consumers reach the same WidgetTree, by two deliberately separate routes:
- Rendering and lifecycle — the top path.
App → TabWidget → Tab → Layout interface → WidgetTree. Everything on this path is generic:TabWidgetandTabsee only the interface methods above, so neither can acquire a dependency on split-tree behaviour and a tab can host a completely differentLayoutwith no changes. - Application logic — the left path. Code that genuinely needs split-specific operations (focus navigation, pane placement, splitting, leaf marks) takes the concrete
*WidgetTreefrom the application's own accessor. Those operations are intentionally absent from the interface.
Splitting the routes this way is what let the 28 forwarding methods Tab used to carry disappear: application code no longer hops through the container to reach the tree, while Tab stays small enough to host a future layout that has no panes at all. The application's accessor is the single place the interface is narrowed to a concrete type.
flowchart TD
App["App frame loop"]
TabW["TabWidget"]
Tab["Tab<br/>Title + Content Layout"]
Iface(["Layout interface<br/>Widget + BuildLayout"])
WT["WidgetTree<br/>topology, geometry, focus, marks"]
FutureA["future layout"]
FutureB["future layout"]
Shell["application shell .Layout()<br/>the one type assertion"]
AppCode[["many application call sites<br/>focus, placement, splits, marks<br/>(not a type)"]]
App -->|"calls Draw"| TabW
TabW -->|"active tab"| Tab
Tab -->|"Content field"| Iface
Iface -.->|"implemented by"| WT
Iface -.->|"implemented by"| FutureA
Iface -.->|"implemented by"| FutureB
AppCode -->|"calls"| Shell
Shell -->|"returns concrete type"| WT
Solid arrows are runtime use (a call, a field); dotted arrows are the implements relationship. Every box is a Go type except the double-barred one, whose shape marks it as a set of scattered call sites — lay := a.Layout() appears in about a dozen files such as workspace_policy.go, workspace_place.go and actions.go.
Source: diagrams/tab_layout.mermaid
WidgetTree is the tiling implementation and is handed to the tab as its content directly. There is no wrapper type between the interface and the tree, so every pane, focus and mark operation is reachable on the layout with no forwarding code:
lay := app.Layout() // *termforge.WidgetTree
lay.FocusLeft()
lay.Split(termforge.Vertical, pane)
lay.SetLeafMark("code", leaf)
Do not add Tab or TabWidget methods that forward into a Layout. Code needing arrangement-specific behaviour takes the layout and drives it directly. The accessor returns nil when the tab hosts a non-split layout, which is the signal that mark and slot APIs do not apply.
A layout can also sit inside a leaf, giving two independent trees in one tab — it must implement StatusLineDrawer as well, since a leaf holds a NodeWidget. WidgetTree.buildLayout hands a nested layout its canvas. Focus arbitration between two trees is separate policy and is not implemented.
Tab management¶
Tab is chrome: a title plus a Layout. For the tiling layout, focus and named leaf marks live on the WidgetTree itself. Mark names and focus policy are application-private; termforge stays free of application roles so unrelated apps can reuse it.
flowchart LR
TabBar["TabBar"]
T1["Tab 1 · content"]
T2["Tab 2 · content"]
T3["Tab 3 · content"]
TabBar --> T1
TabBar --> T2
TabBar --> T3
Current TabWidget implementation:
Its surface is the two constructors, AddTab, the selection calls (Count, ActiveIndex, Titles, SetActive, NextTab, PrevTab), Layout() / SetLayout(), and Draw / HandleEvent. Nothing on it reaches into a Layout.
Only the active tab is laid out and painted, so an inactive tab costs nothing per frame and keeps the focus, ratios and drags it had when it was last on screen. Switching is therefore just an index move — SetActive reports whether the index actually changed, so a host can skip the repaint when it did not.
| Feature | Status |
|---|---|
| Several tabs in one container | Implemented (AddTab) |
| Hand events/draw to active tab's Layout | Implemented |
| Tab switching | Implemented (SetActive / NextTab / PrevTab) |
| Tab header rendering | Implemented (TabBarWidget, a chrome row) |
| Named leaf marks on WidgetTree | Implemented |
| Generic non-tree tab content | Implemented (Layout interface); no second implementation yet |
| Nested layout inside a leaf | Structurally supported; focus arbitration not implemented |
| Tab close | Not implemented |
| Persist layout per tab | Not implemented |
Design decision: a tab is a workspace preset, not a separate session. One tab might hold "document + console" while another holds "charts + log". Binding a distinct session per tab is left to the application.
The tab bar¶
TabBarWidget paints the titles on one full-width chrome row, registered with AddRowWidget before the workspace widget so it takes the top line:
a.tab.AddTab("columns", secondTree) // built at startup, active tab unchanged
a.tabBar = termforge.NewTabBarWidget(a.tab)
a.AddRowWidget(a.tabBar, 1)
a.AddWidget(a.tab)
It reads the titles and the active index off the TabWidget on every paint, so adding a tab or switching one in needs nothing kept in sync. Like other chrome it does not route its own input — WidgetsList.HandleEvent broadcasts without geometry — so the host hit-tests it:
if r := a.WidgetRect(a.tabBar); r.Contains(x, y) {
if i := a.tabBar.TabAt(x - r.X()); a.tab.SetActive(i) {
a.RequestFrame()
}
return
}
TabAt returns -1 for the empty run past the last label, and SetActive ignores it, so a click on the bare part of the bar does nothing instead of falling through to a pane.
Since the split tree is per tab, an application holding a *WidgetTree in a field would go stale the moment a tab is switched in. Take the active tree from the one accessor that narrows the interface instead:
func (a *App) Layout() *termforge.WidgetTree {
tree, _ := a.tab.Layout().(*termforge.WidgetTree)
return tree
}
Anything a host wants to reach across tabs — "focus the pane named log" — needs its own map from the name to the tab that holds it, because a tree only knows its own leaves. cmd/demo does this for :b.
Command line¶
The CmdLine is a top-level band for Vim-style : commands, distinct from any prompt belonging to a process running inside a console pane.
+--------------------------------------------------+
| : break main |
+--------------------------------------------------+
CmdWidget (cmd_widget.go) provides:
- Vim-style
:activation and drawing on the bottom line (rowH-1of the terminal). - Command history (
termforge.History) — Up/Down navigation. - Tab completion (
termforge.AutoCompleter) — command name only. SubmitMsgon the event bus — resolvedCommandID+ args; app dispatches inHandleCoreEvents.
Command mode is entered by the application (: → ModeCommand, CmdWidget.Activate()), not by CmdWidget alone. Esc returns to normal mode at the app layer.
Current state: :quit / :q exits the debug session (same as Ctrl-D). :close removes the focused pane/split. Split commands (:vs, :split) partially wired. Unknown commands emit termforge.CmdUnknown.
Design decision: keep the CmdLine separate from any in-pane console because:
- A console pane speaks whatever dialect its child process speaks; the CmdLine speaks UI commands (
:split,:focus,:close,:quit). - Users can run UI operations without sending spurious input to the child process.
- The two have different completion vocabularies.
Planned flow details: see INPUT.md and COMMAND_SYSTEM.md.
Per-pane status line¶
Each leaf pane in the split tree has a one-row status band at local y = c.H() — immediately below the widget content area (0..H-1). This row is owned by the layout system, not by individual widget Draw methods.
| State | Appearance |
|---|---|
| Focused | Styled bar: ▎ {PaneName} (green insert / blue normal) |
| Unfocused | Grid row unchanged; gray {PaneName} starting at the 4th character |
Draw order (after BuildLayout):
- Widget content (
Draw) - Clear all pane status rows (
ClearStatusLine) - Redraw split separators (
redrawGrid) — restores border glyphs and default style - Paint status on every leaf (
DrawStatusLine) — focused bar vs inactive name overlay (no dash fill)
Panes set a display name via BaseWidget.PaneName (e.g. "Code", "Log") or override DrawStatusLine. Chrome that never occupies a pane (TabWidget, overlays) implements no status method at all — it is a plain Widget, not a NodeWidget. The pinned cmdline leaf is a NodeWidget via BaseWidget, but leaves PaneName empty, so its status paint is a no-op. Prefer StatusLabel() when the copyable text differs from PaneName (Code uses the full source path).
Mouse on the status band (row at Bottom() of the leaf, outside content):
| Gesture | Action |
|---|---|
| Double-click on the name text | Copy the full status label (path for Code); brief white highlight |
| Click or drag anywhere on the status row | Unchanged: split resize / focus — same as before status-copy |
Implementation: status_line.go, status_sel.go, base_widget.go, widget_tree.go (drawWidgets, clearStatusRows, redrawGrid, drawStatusLines).
Global application state¶
App.State() returns *platform.AppState — process-global UI state for the running session:
| Field | Purpose |
|---|---|
Mode |
Input mode: Normal / Insert / Command / Search / Completion |
EqualAlways |
Vim-like: when true, split ratios rebalance to equal after Split / close (not on every paint). :set equalalways also rebalances immediately. |
Layouts / RegisterLayout / HasLayout |
Names of layouts the application has registered, for :layout completion and validation |
CurrentLayout |
Name of the layout currently mounted |
MarkColor |
Focused list selection background (:set markcolor; default blue) |
MarkDimColor |
Unfocused list selection background (:set markdimcolor; default gray) |
SearchColor |
/search match highlight |
MutedColor |
Empty-list / dim text (:set mutedcolor; default gray) |
st := app.State()
st.SetEqualAlways(true) // :set equalalways
st.RegisterLayout("default") // so :layout default completes and validates
st.Mode() // routing decisions in HandleKey
Application state — the domain model, selections, and colors specific to what the application displays — belongs in the application's own session type, not here.
Members pending relocation
AppState still carries a few members that describe a consuming application
rather than the framework: PTYOwner (with SetPTYOwnerHook / WithPTYOwner),
DefaultLayoutRatios, LayoutLeftRatio, and CodeSelColor and EscToCode.
platform/theme.go likewise still defines breakpoint and program-counter default
colors. These are carry-over from the extraction and are expected to move out to
the application; do not build new framework features on them.
Planned window operations¶
| Command | Action | Status |
|---|---|---|
:split / :vsplit |
Split focused pane horizontally / vertically | Done (:vs / :split) |
:close |
Close focused pane (collapse split) | Partial |
:focus left/right/up/down |
Move focus | Done (:window / Ctrl-W) |
:tabn / :tabp |
Switch tabs | Done (TabWidget.NextTab / PrevTab; :tab next\|prev in the demo) |
:tabnew / :tabclose |
Create / close a tab at runtime | Planned (AddTab exists; there is no close) |
:only |
Collapse to single pane | Done (:only / Ctrl-W o) |
:resize +N/-N |
Adjust split ratio | Planned |
Remaining items call into WidgetTree / TabWidget APIs from the command router (INPUT.md).
Related documentation¶
- UI_ARCHITECTURE.md — layout engine internals
- INPUT.md — focus and command mode
- RENDERING.md — split border drawing