Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rikitav/Terminality/llms.txt

Use this file to discover all available pages before exploring further.

Terminality is a C++23 terminal UI framework that replaces manual cursor positioning with a proper widget hierarchy. Instead of calculating coordinates by hand, you compose a tree of controls — containers like Grid, StackPanel, and Border, plus interactive widgets like Button, TextBox, and CheckBox — and Terminality handles sizing, alignment, focus navigation, and efficient redrawing automatically. This page explains what Terminality is, why it was built, and how its architecture fits together.

​
Why Terminality exists

Writing terminal UIs without a framework means managing cursor positions by hand, tracking which screen regions need redrawing, and wiring up input handling for every widget yourself. The result is brittle code that couples business logic tightly to rendering details. Terminality was built to solve this by applying the same layout model that made WPF and XAML productive for desktop UIs. You describe your interface declaratively — what controls exist, how they should be aligned, and what they do when interacted with — and the framework translates that description into terminal output.

​
WPF-style layout in the terminal

Terminality’s layout system mirrors XAML concepts directly:
  • HorizontalAlignment and VerticalAlignment — Stretch, Center, Left, Right, Top, Bottom work on every control.
  • Margin and Thickness — spacing between controls uses the same four-sided margin model.
  • Grid with row and column definitions — GridLength::Star(), GridLength::Auto(), and GridLength::Cell(n) distribute space the same way *, Auto, and fixed pixel values do in XAML.
  • StackPanel — stacks children vertically or horizontally and stretches to fill available space.
Controls are configured through init-lambdas and composed with AddChild, producing a self-contained widget tree that Terminality owns and renders.

​
C++23 modules

Terminality ships entirely as a C++23 named module. There are no headers to include — you write import terminality; and the full public API is available. The module re-exports sub-modules organised by category:
CategorySub-modules
CoreColor, Focus, Geometry, InputEvent, Layout, TextHelper
Layout controlsGrid, StackPanel, ItemsControl, ScrollViewer
Visual controlsLabel, Border, Spinner, ProgressBar
Interactive controlsCheckBox, Button, TextBox
DialogsContextMenu, MessageBox, OpenFileDialog
EngineDispatchTimer, FocusManager, Navigator, RenderBuffer, RenderContext
FrameworkVisualTree, ControlBase, Event, Property, ObservableCollection
This requires a compiler with C++23 module support. MSVC and the latest GCC releases are the tested targets.

​
Architecture overview

A Terminality application is structured around three components: HostApplication — a singleton that owns the terminal lifecycle. It calls EnterTerminal() to configure raw input mode and take over the output buffer, runs the render-input loop via RunUILoop(), and restores the terminal on ExitTerminal(). On Windows and Linux, a platform-specific backend (HostBackend) handles the low-level I/O. Widget tree — every visible element is a VisualTreeNode. Containers hold children, measure and arrange them recursively, and propagate invalidation up to the root when state changes. Render pipeline — RenderBuffer tracks per-cell state. On each frame, only dirty cells are written to the terminal output, which keeps redraws fast even on large layouts.

​
Extension points

You can write custom controls by subclassing ControlBase and overriding three virtual methods:
  • MeasureOverride(availableSize) — return the size your control needs.
  • ArrangeOverride(finalRect) — position children within the allocated rectangle.
  • RenderOverride(context) — write characters and colors to the RenderContext.
The test application in the repository implements MessageBubble, a custom control that renders a timestamped chat message, as a concrete example of this pattern.

​
Key features

Get started quickly

Build a working Terminality app with a complete code walkthrough.

Build and integrate

Clone, build with CMake, and link Terminality into your own project.

Widget hierarchy

Grid, StackPanel, Border, and ScrollViewer containers with full child management and automatic layout.

Events and properties

Type-safe Event<Args...> and reactive Property<T> with automatic invalidation and hotkey binding.

Build docs developers (and LLMs) love

Get started for freeTalk to us