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 manages multiple pages through a layered visual tree. The Navigator singleton provides a page stack you can push to and pop from at any time. HostApplication::NestUILoop offers a lower-level mechanism for running a blocking sub-loop on a separate UILayer, which is how the built-in dialogs are implemented internally. Navigator::Current() returns the single, globally shared navigator. It does not need to be constructed or passed around — call it from anywhere after RunUILoop has started. 
import terminality;
using namespace terminality;

// from inside any control or hotkey handler:
Navigator& nav = Navigator::Current();

​
Pushing a page

Navigate takes ownership of a new root node and pushes it onto the navigation stack. The previous page is suspended but not destroyed. 
void Navigator::Navigate(std::unique_ptr<VisualTreeNode> page);

OnHotkey(InputModifier::None, InputKey::F2, [](ControlBase* self)
{
    Navigator::Current().Navigate(std::make_unique<SettingsPage>());
});
The new page immediately becomes the active layer and receives input focus.

​
Going back

bool Navigator::CanGoBack() const;
bool Navigator::GoBack();
void Navigator::GoHome();
MethodDescription
CanGoBack()Returns true if there is at least one page beneath the current one.
GoBack()Pops the current page and resumes the previous one. Returns true on success.
GoHome()Pops all pages and returns to the root page that was passed to RunUILoop.
OnHotkey(InputModifier::None, InputKey::ESCAPE, [](ControlBase* self)
{
    auto& nav = Navigator::Current();
    if (nav.CanGoBack())
        nav.GoBack();
    else
        HostApplication::Current().RequestStop();
});

​
Relationship with HostApplication

HostApplication provides two related entry points: 
void HostApplication::RunUILoop(std::unique_ptr<VisualTreeNode> root);
void HostApplication::NestUILoop(UILayer& layer);
RunUILoop starts the main event loop with a root page and does not return until RequestStop() is called. The Navigator operates on top of the visual tree managed by this loop. NestUILoop runs a second, nested event loop on a pre-built UILayer. It blocks the calling thread until the layer’s Running flag is set to false. The built-in dialogs (MessageBox, ContextMenu, OpenFileDialog) use this mechanism to implement their blocking behaviour.

​
Multi-layered UI

The visual tree is a stack of UILayer objects. Each layer has its own root node and FocusManager. Layers are rendered back-to-front, so the topmost layer always appears in front. Input is routed only to the active (topmost) layer.

Navigator.Navigate

Use for application-level page transitions — settings screens, detail views, wizard steps. The previous page is kept alive on the stack and restored when you go back.

NestUILoop

Use for modal overlays that must block the rest of the UI — confirmation dialogs, context menus, file pickers. The current layer is still visible underneath, but receives no input.

​
Typical navigation setup

1

Start the application

Call EnterTerminal to prepare the console, then RunUILoop with your initial page.
int main()
{
    HostApplication& app = HostApplication::Current();
    app.EnterTerminal();
    app.RunUILoop(std::make_unique<HomePage>());
    app.ExitTerminal();
    return 0;
}
2

Navigate to a new page

From inside any control, call Navigator::Current().Navigate(...).
Navigator::Current().Navigate(std::make_unique<DetailPage>());
3

Return to the previous page

Call GoBack() or bind GoHome() to a reset hotkey.
if (Navigator::Current().CanGoBack())
    Navigator::Current().GoBack();
Bind GoBack to a consistent key (such as Escape) across all pages so users always have a predictable way to go back. Check CanGoBack() first and fall through to RequestStop() when on the root page.

Build docs developers (and LLMs) love

Get started for freeTalk to us