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 provides three ready-to-use dialog types that handle their own rendering and event loops so your application code stays simple. MessageBox blocks until the user dismisses it and returns a typed result. ContextMenu attaches to any control and opens at an arbitrary screen position. OpenFileDialog presents a file-picker and returns an optional<filesystem::path> you can test before using.

​
MessageBox

MessageBox::Show is a static method that renders a blocking modal dialog and returns which button the user pressed. 
#include <Windows.h>
#undef MessageBox   // prevent the Win32 macro from shadowing terminality::MessageBox

import terminality;
using namespace terminality;
On Windows, <Windows.h> defines a MessageBox macro that will shadow terminality::MessageBox. Always #undef MessageBox immediately after including the header, before importing the module.

​
Signature

static MessageBoxResult MessageBox::Show(
    const std::wstring& title,
    const std::wstring& message,
    MessageBoxButton buttons = MessageBoxButton::Ok
);

​
Button sets

MessageBoxButton::Ok

Displays a single Ok button. The default when no argument is passed.

MessageBoxButton::OkCancel

Displays Ok and Cancel.

MessageBoxButton::YesNo

Displays Yes and No.

MessageBoxButton::YesNoCancel

Displays Yes, No, and Cancel.

​
Return values

MessageBoxResultMeaning
NoneDialog was closed without a selection.
OkUser pressed Ok.
CancelUser pressed Cancel.
YesUser pressed Yes.
NoUser pressed No.

​
Example from TespApp

The messenger demo calls MessageBox::Show both from a button’s Clicked event and from a hotkey that opens a help overlay: 
// Button in the status bar
statusBar->Clicked += []()
{
    MessageBox::Show(
        L"Status",
        L"Button was pressed",
        MessageBoxButton::YesNoCancel
    );
};

// Hotkey: * key opens a help dialog
OnHotkey(InputModifier::None, InputKey::MULTIPLY, [](ControlBase* self)
{
    MessageBox::Show(L"Help", L"Help screen", MessageBoxButton::YesNoCancel);
});
To act on the result, capture the return value: 
MessageBoxResult result = MessageBox::Show(
    L"Confirm delete",
    L"Are you sure?",
    MessageBoxButton::YesNo
);

if (result == MessageBoxResult::Yes)
{
    // proceed
}

​
ContextMenu

A ContextMenu is a popup list of labelled actions. You create one, populate it with AddItem, assign it to a control’s CtxMenu property, and call OpenContextMenu() or Open(position) to show it.

​
ContextMenuItem

Each entry in the menu is a plain struct: 
struct ContextMenuItem
{
    std::wstring          Text;    // label shown in the menu
    std::function<void()> Action;  // called when the item is selected
};

​
ContextMenu class

class ContextMenu
{
public:
    void AddItem(const std::wstring& text, std::function<void()> action);
    void Clear();
    void Open(Point position);
};
MethodDescription
AddItem(text, action)Appends a new item with the given label and callback.
Clear()Removes all items.
Open(position)Opens the menu at the given screen Point.

​
Attaching a menu to a control

ControlBase exposes a typed CtxMenu property and a convenience method: 
Property<ControlBase, std::unique_ptr<ContextMenu>> CtxMenu;

void OpenContextMenu();   // opens CtxMenu at the control's current position
Assign a unique_ptr<ContextMenu> to CtxMenu, then call OpenContextMenu() from a hotkey or event handler.

​
Example from TespApp

The MessageBubble item template attaches a context menu and binds the D key to open it: 
bubble->CtxMenu = init<ContextMenu>([](ContextMenu* menu)
{
    menu->AddItem(L"Test2", []()
    {
        MessageBox::Show(L"ContextMenu.Test2", L"ContextMenu.Test2");
    });

#ifdef _WIN32
    menu->AddItem(L"Test1", []()
    {
        AlertAsync(L"ContextMenu.Test1", L"");
    });
#endif
});

bubble->OnHotkey(InputModifier::None, InputKey::D, [](ControlBase* self)
{
    self->OpenContextMenu();
});
AlertAsync is a Windows-only helper declared in the terminality:Windows module. Guard any call to it with #ifdef _WIN32.

​
OpenFileDialog

OpenFileDialog::Show presents a file-picker dialog and returns an optional<filesystem::path>. The optional is empty if the user cancels.

​
Signature

static std::optional<std::filesystem::path> OpenFileDialog::Show(
    const std::wstring&          title            = L"Open File",
    const std::filesystem::path& initialDirectory = std::filesystem::current_path()
);

​
Checking the result

Always test has_value() before accessing the path: 
auto selected = OpenFileDialog::Show();
if (!selected.has_value())
{
    // user cancelled — nothing was selected
}
else
{
    // use selected.value()
    doSomethingWith(selected.value());
}

​
Example from TespApp

The minus key on the numpad opens a file picker and shows the result (or a “returned nothing” message) in a MessageBox: 
OnHotkey(InputModifier::None, InputKey::SUBTRACT, [](ControlBase* self)
{
    auto selectedFile = OpenFileDialog::Show();
    if (!selectedFile.has_value())
    {
        MessageBox::Show(
            L"OpenFileDialog test",
            L"returned nothing",
            MessageBoxButton::Ok
        );
    }
    else
    {
        MessageBox::Show(
            L"OpenFileDialog test",
            selectedFile.value().wstring(),
            MessageBoxButton::Ok
        );
    }
});

Build docs developers (and LLMs) love

Get started for freeTalk to us