AppCUI::Application

namespace Application

Application lifetime: initialization (Init, InitializationData), the event loop (Run), desktop windows (AddWindow, ArrangeWindows), menus, themes, settings (<executable>.ini) and custom frontends.

Classes

Enumerations

enum class AppCUI::Application::InitializationFlags : uint32

Options of Application::Init (they can be combined with |).

Values:

enumerator None = 0
enumerator CommandBar = 0x0001

a command bar (shortcut keys) is shown on the last line

enumerator Menu = 0x0002

a menu bar is shown on the first line (see Application::AddMenu)

enumerator Maximized = 0x0004

the terminal window is maximized (frontend dependent)

enumerator Fullscreen = 0x0008

the terminal window is full screen (frontend dependent)

enumerator FixedSize = 0x0010

the terminal window can not be resized (frontend dependent)

enumerator LoadSettingsFile = 0x0020

loads <executable>.ini; its [AppCUI] section configures the application

enumerator AutoHotKeyForWindow = 0x0040

every new window receives a free Alt+1 .. Alt+9 hot key

enumerator EnableFPSMode = 0x0080

Control::OnFrameUpdate is called ~30 times per second.

enumerator SingleWindowApp = 0x0100

single application mode: start with Application::RunSingleApp

enumerator DisableAutoCloseDesktop = 0x0200

the application keeps running after its last window was closed

enum class AppCUI::Application::CharacterSize : uint32

Size of a character (SDL and Windows console frontends).

Values:

enumerator Default = 0
enumerator Tiny
enumerator Small
enumerator Normal
enumerator Large
enumerator Huge
enum class AppCUI::Application::FrontendType : uint32

The frontend (terminal implementation) that displays the application.

Values:

enumerator Default = 0
enumerator SDL = 1
enumerator Terminal = 2
enumerator WindowsConsole = 3
enumerator Tests = 4
enumerator Custom = 5
enumerator Browser = 6

HTML5 canvas inside a web page (wasm32-emscripten builds only).

enum class AppCUI::Application::ThemeType : uint32

Built-in color themes.

Values:

enumerator Default = 0
enumerator Dark = 1
enumerator Light = 2
enum class AppCUI::Application::SpecialCharacterSetType : uint32

Characters used to draw lines, borders, arrows and other special characters.

Values:

enumerator Auto = 0
enumerator Unicode = 1
enumerator LinuxTerminal = 2
enumerator Ascii = 3
enum class AppCUI::Application::FrontendEventType : uint32

Type of a FrontendEvent produced by a CustomFrontendInterface.

Values:

enumerator None = 0
enumerator KeyPressed
enumerator ShiftStateChanged
enumerator MouseDown
enumerator MouseUp
enumerator MouseMove
enumerator MouseWheel
enumerator Resized
enumerator Closed
enumerator RedrawRequested
enum class AppCUI::Application::ArrangeWindowsMethod

How Application::ArrangeWindows places the desktop windows.

Values:

enumerator MaximizedAll
enumerator Cascade
enumerator Vertical
enumerator Horizontal
enumerator Grid

Functions

Config *AppCUI::Application::GetAppConfig()

Colors of the current theme (nullptr if the application is not initialized).

Utils::IniObject *AppCUI::Application::GetAppSettings()

Settings read from <executable>.ini (InitializationFlags::LoadSettingsFile); nullptr if the application is not initialized.

bool AppCUI::Application::SaveAppSettings()

Writes the settings (GetAppSettings) back to GetAppSettingsFile().

void AppCUI::Application::UpdateAppCUISettings(Utils::IniObject &ini, bool clearExistingSettings = false)

Adds the default [AppCUI] keys that are missing from ini (rewrites all of them when clearExistingSettings is true).

bool AppCUI::Application::UpdateAppCUISettings(bool clearExistingSettings = false)

Same as above, applied to the settings of the running application.

std::filesystem::path AppCUI::Application::GetAppSettingsFile()

Path of the settings file: the path of the executable with the .ini extension.

const Input::ModifierMap &AppCUI::Application::GetModifierMap()

Keyboard modifier profile ([AppCUI] Keyboard.Ctrl / Keyboard.Alt).

void AppCUI::Application::SetModifierMap(const Input::ModifierMap &map)

Applies a keyboard modifier profile immediately and updates the in-memory settings (call SaveAppSettings to persist it).

bool AppCUI::Application::Init(Application::InitializationFlags flags = Application::InitializationFlags::None)

Initializes AppCUI with the default parameters and the given flags. Returns false on failure.

bool AppCUI::Application::Init(InitializationData &initData)

Initializes AppCUI with the parameters described by initData (the settings file, if loaded, may change them).

bool AppCUI::Application::InitForTests(uint32 width, uint32 height, Application::InitializationFlags flags = Application::InitializationFlags::None, bool asciiMode = false)

Initializes AppCUI on the in-memory test frontend (FrontendType::Tests); see RunTestScript.

bool AppCUI::Application::Run()

Runs the event loop until Close() is called (or, by default, until the last window is closed), then un-initializes AppCUI.

bool AppCUI::Application::RunTestScript(std::string_view script)

Runs a test script (key presses, mouse events, screen hash checks) on an application started with InitForTests.

Returns false if a check of the script failed.

bool AppCUI::Application::RunSingleApp(unique_ptr<Controls::SingleApp> singleApp)

Runs an application initialized with InitializationFlags::SingleWindowApp: singleApp replaces the desktop.

Controls::ItemHandle AppCUI::Application::AddWindow(unique_ptr<Controls::Window> wnd, Controls::ItemHandle referal = Controls::InvalidItemHandle, const ConstString& = "")

Adds a top level window to the desktop.

referal is the window that opened it (the windows manager shows the windows as a tree) and the last parameter describes how it was created. Returns the handle of the new window.

Controls::ItemHandle AppCUI::Application::AddWindow(unique_ptr<Controls::Window> wnd, Controls::Window *referalWindow, const ConstString& = "")

Adds a top level window opened from referalWindow.

Controls::ItemHandle AppCUI::Application::AddWindow(unique_ptr<Controls::Window> wnd, Utils::Reference<Controls::Window> referalWindow, const ConstString& = "")

Adds a top level window opened from referalWindow.

Controls::Menu *AppCUI::Application::AddMenu(const ConstString &name)

Adds a menu to the menu bar (requires InitializationFlags::Menu). Returns nullptr on failure.

bool AppCUI::Application::GetApplicationSize(Graphics::Size &size)

Size of the whole application (terminal) in characters.

bool AppCUI::Application::GetDesktopSize(Graphics::Size &size)

Size of the desktop client area (without the menu bar and the command bar).

Utils::Reference<Controls::Window> AppCUI::Application::GetCurrentWindow()

The focused desktop window (or nullptr).

void AppCUI::Application::ArrangeWindows(ArrangeWindowsMethod method)

Re-arranges every desktop window.

void AppCUI::Application::RaiseEvent(Utils::Reference<Controls::Control> control, Utils::Reference<Controls::Control> sourceControl, Controls::Event eventType, int controlID)

Sends an event to control as if sourceControl had raised it (only valid after Init).

Utils::Reference<Controls::Desktop> AppCUI::Application::GetDesktop()

The desktop (only valid after Init).

void AppCUI::Application::Close()

Stops the event loop (the application closes).

void AppCUI::Application::SetTheme(ThemeType themeType)

Switches to a built-in theme.

bool AppCUI::Application::SetSpecialCharacterSet(SpecialCharacterSetType characterSetType)

Changes the characters used to draw lines, borders and other special characters.

Utils::PropertiesInterface *AppCUI::Application::GetAppPropertiesObject()

AppCUI settings exposed as properties (for a PropertyList).