UIHost class
#include <Runtime/UI/Public/UIHost.h>

The documents the engine shows, one per window, and the libraries, styles, strings, and services they share. See the file description for which thread does what.

Public types

struct DockWindowSink: Opens, places, and closes the windows panels float in, and sets window ownership for keep-above.
struct PopupWindowSink: Opens, places, and closes the windows popups ask for (GGUI::PopupProps::bOwnWindow).
struct TextSink: Text input and clipboard.
struct Surface: A window drawn this frame and its target size in pixels.
using CursorFn = void(*)(void*context, PlatformWindowID window, PlatformCursor cursor): Called on Encoder when the cursor a window should show changes.

Public static variables

static uint32_t DockTagBase constexpr: The first tag of dock window requests; each request's tag is above it.
static uint32_t PasteTagBase constexpr: The first tag of clipboard requests; each request's tag is above it.
static uint32_t PopupTagBase constexpr: The first tag of popup window requests; each request's tag is above it.

Public static functions

static auto IsDockTag(uint32_t tag) -> bool constexpr: Whether tag is a dock window request's.
static auto IsPasteTag(uint32_t tag) -> bool constexpr: Whether tag is a clipboard request's.
static auto IsPopupTag(uint32_t tag) -> bool constexpr: Whether tag is a popup window request's.
static auto LoadDefaultFonts(GGUI::TextEngine& text) -> bool: Load the engine's fonts into text and set the styles that use them: the default UI font, "heading", and "mono". False if the default font is missing.

Constructors, destructors, conversion operators

UIHost(): A host with no documents, the built-in styles, and the engine's English.
~UIHost(): Waits for documents still updating, then destroys them.
UIHost(const UIHost&) deleted

Public functions

auto operator=(const UIHost&) -> UIHost& deleted
auto Mount(PlatformWindowID window, GGUI::ComponentFn root, const GGUI::StyleTable* styles = nullptr, PlatformWindowID follows = 0, const GGUI::BindingReader* reader = nullptr) -> bool: Mount a document in window, built by root. Replaces whatever the window showed.
auto Unmount(PlatformWindowID window) -> bool: Unmount the document in window. False if the request queue is full.
auto SetScale(PlatformWindowID window, float scale) -> bool: The window's UI scale changed (physical pixels per UI unit). False if the request queue is full.
void SetStyles(const GGUI::StyleTable* styles): The style table for documents mounted from now on.
auto Editors() -> GGUI::EditorRegistry&: Which widget edits which field type, for every document: the built-in editors plus any a game or plugin registers. Register before documents are mounted.
auto Actions() -> GGUI::GGActionMap&: Input actions and their chords, for every document (see UIActions.h).
void KeepFromGame(const GGUI::GGInputAction& action): While the game has the keyboard, a key bound to action still goes to the documents (the editor's Stop, say). Up to eight actions; call before the engine runs.
auto IsKeptFromGame(const PlatformEvent& event) const -> bool: True if event is a press of a chord bound to an action kept from the game. Sentinel.
auto Notices() -> GGUI::GGNotices&: Notices and the platform file dialog (see UINotices.h): one of each, shared by every document and by non-UI code. Any thread.
auto Files() -> GGUI::GGFiles&: The platform file dialog, shared the same way.
void SetNoticeWindow(PlatformWindowID window): The window notices show in. 0 (the default): every window's document shows them.
auto Dock() -> GGUI::GGDockSpace&: The dock space: panels and their layout (see UIDock.h). A document shows it with ui.Dock(host.Dock()).
void SetDockWindow(PlatformWindowID window, const GGUI::BindingReader* reader = nullptr): The window whose document shows the dock space's main window (it calls ui.Dock(host.Dock())).
void SetDockWindowSink(const DockWindowSink& sink): Set before the engine runs.
auto AttachDockWindow(uint32_t tag, PlatformWindowID window) -> bool: The dock window requested with tag opened as window. Any thread.
void DockWindowFailed(uint32_t tag): The dock window requested with tag couldn't be opened. It is requested again while the dock space still has it. Any thread.
auto DockWindowCloseRequested(PlatformWindowID window) -> bool: The platform is closing window. True if it was a dock window: every panel in it is closed. Any thread.
void SetWindowPlace(PlatformWindowID window, float x, float y, float pixelDensity): A window's screen position in window coordinates, and its physical pixels per coordinate.
void FloatPanel(uint64_t panel): Float a panel in a window of its own. Any thread; applied at the main dock document's next update (the dock space is only touched where its documents update).
void ClosePanel(uint64_t panel): Close a panel. Any thread; applied at the main dock document's next update.
auto DockWindowCount() -> uint32_t: The number of open floating dock windows. Any thread.
auto DockWindowAt(uint32_t index) -> PlatformWindowID: A floating dock window, by index below DockWindowCount; 0 if there is none. Any thread.
void KeepAbove(PlatformWindowID window, PlatformWindowID above): Keep window above above (0: no owner), through the dock window sink: an inspector above the editor, except while picking under it. Any thread.
void SetLayoutFile(std::string path, PlatformWindowID shows): The file layouts are saved in, as hand-editable text (GGDockSpace::Save).
void SetKeyBindingsFile(std::string path): The file non-default chords are saved in, as hand-editable text (GGActionMap::Save).
auto DescribeHints() const -> std::string: Every field hint some editor reads, one per line.
void SetStrings(const GGUI::GGStringTable* strings): The active language for every document (see UIStrings.h); null for default text.
auto StringFiles() -> TnxStringTable&: The engine's string files (TnxStringTable.h): shown in every document unless SetStrings replaced them. Add a project's folder here; it is read at the next update.
void UseLanguage(std::string_view language): Show language from the next update on. Any thread.
auto Language() const -> std::string: The language shown. Any thread.
void SetReducedMotion(bool bReduced): Reduced motion: style transitions complete instantly in every document.
auto ReducedMotion() const -> bool: Whether reduced motion is on.
auto ReducedMotionSetting() -> std::atomic<bool>&: The setting itself, for anything that shows or edits it (the console's ui.reduced_motion).
void AddSheetFile(GGUI::StyleTable& table, std::string_view name, std::string_view path): Register the file at path as sheet name of table (GGUI::StyleTable::SetSheet).
void RemoveSheetFiles(const GGUI::StyleTable& table): Stop reading files into table. Call before the table is destroyed. Any thread.
auto WatchSheetsSetting() -> std::atomic<bool>&: Whether saved sheets and widget files are read again (the console's ui.watch_sheets). On by default.
auto Sheets() const -> const UISheetFiles&: The sheet files, for their counts and last error.
void AddWidgetFiles(std::string_view path, bool bStarters = false): Read widget assets (.tnxwidget), tables (.tnxtable), and the sheets they name (.ggss) from path, a file or a folder, into the library every document's ui.Use builds from.
auto Widgets() const -> const GGUI::GGWidgetLibrary&: The widget library documents build from.
auto WidgetFileStats() const -> const UIWidgetFiles&: The widget files, for their counts.
void SetItemSources(const GGUI::GGItemSources& sources, void(*)() pump): Where asset lists find their items, and what brings them up to date while no document is updating. TnxUI sets both at startup.
void EnablePreviewWidgets(): Read widget files into the preview library too. The editor calls it at startup.
auto PreviewWidgets() const -> const GGUI::GGWidgetLibrary&: The preview library: what the files hold, with the texts SetPreviewText gave over it.
auto SetPreviewText(TnxName asset, std::string file, std::string text) -> uint64_t: Build asset from text in the preview library from the next pump, until ForgetPreview.
void ForgetPreview(TnxName asset): Build asset from its file again. Any thread.
auto PreviewProblems(TnxName asset, std::vector<GGUI::GGWidgetProblem>& out) const -> uint64_t: The problems the last text given for asset loaded with, into out, and its serial; 0 until it is in. Any thread.
void SetWidgetActions(GGUI::UIContext::WidgetActionFn fn, void* context): Where what asset elements do goes, for every document mounted after (TnxUI sets it at startup). Not set: each document reports them as unhandled.
void ChangeStyles(const GGUI::StyleTable& table, std::function<void()> change): Change a style table that is in use: change is called on Encoder, before an update, once none of the documents using table is updating (those about to start wait for it).
auto UpdateBudgetSetting() -> std::atomic<float>&: How long UpdateAll waits for documents, in milliseconds from when it is called (the console's ui.update_budget_ms).
auto BuildBudgetSetting() -> std::atomic<float>&: How long one document update spends building deferred content (BoxProps::Priority), in milliseconds (the console's ui.build_budget_ms); the rest is built in later frames.
void SetReader(const GGUI::BindingReader& reader): The binding reader documents read their bindings with, unless mounted with their own.
auto GetReader() const -> const GGUI::BindingReader&: The binding reader set with SetReader.
void SetCursorSink(CursorFn sink, void* context): Where cursor changes go. Without one the cursor is left alone.
void SetPopupWindowSink(const PopupWindowSink& sink): Where popup window requests go.
void SetTextSink(const TextSink& sink): Where text input and clipboard requests go.
auto AttachPopupWindow(uint32_t tag, PlatformWindowID window) -> bool: The popup window requested with tag opened as window. False if the request queue is full.
auto PopupWindowFailed(uint32_t tag) -> bool: The popup window requested with tag failed to open: the popup is drawn as a layer in its owner's window. False if the request queue is full.
auto ClosePopups() -> bool: Close every document's popups, as a press outside would: the application lost focus. False if the request queue is full.
void SetScreenRoom(PlatformWindowID window, int32_t x, int32_t y, int32_t width, int32_t height): The screen area around window available to its popup windows, in physical pixels relative to the window. Popups in their own windows are kept inside it.
auto PopupWindowCount() const -> uint32_t: Popups with their own window, open or still opening.
auto PopupWindowsShown() const -> uint32_t: Of those, how many have their window and are showing in it.
auto RouteInput(const PlatformEvent& event) -> bool: Route a pointer event (move, button, wheel, leave), key event, or gamepad button for a window.
void SetKeysToDocuments(bool bAll): Every key typed in a window goes to its document, focused or not: for an editor, which has no game behind its documents. Off by default.
auto RoutePaste(uint32_t tag, std::string_view text) -> bool: The clipboard text requested with tag: pasted into the document that asked. False if its window has no document.
void ReleasePointer(PlatformWindowID window): The pointer was taken from the UI (the game hid it): clear hover and press in window's document.
void SetImageSource(const GGUI::ImageSource* images): The image source for every document, mounted now or later: the renderer's, backed by the texture table. Not owned.
void ApplyRequests(): Apply requests made since the last call (mounts, unmounts, scales).
void UpdateAll(std::span<const Surface> surfaces): Update the documents of surfaces and publish each one that changed.
void Update(PlatformWindowID window, uint32_t widthPixels, uint32_t heightPixels): Update one window's document.
auto Read(PlatformWindowID window) const -> GGUI::SnapshotRead: The snapshot of window's document to draw this frame; empty if there is no document or nothing is published.
auto HasDocument(PlatformWindowID window) const -> bool: Whether a document is mounted in window.
auto Document(PlatformWindowID window) -> GGUI::UIContext*: The document itself, for tests and tools on Encoder. nullptr if there is none, or if it is updating: it can't be read or changed until that is done.
auto IsBusy(PlatformWindowID window) const -> bool: True while window's document is updating on a job that outlived its UpdateAll, or is blocked because a related document is.
void WaitForDocuments(): Wait for every document still updating. For tests, and before destroying anything documents use.
auto GetText() -> GGUI::TextEngine&: The text engine every document measures and draws with. The renderer uploads its glyph atlas. Encoder thread.
auto UpdateCount() const -> uint64_t: Document updates so far.
auto PublishCount() const -> uint64_t: Of those, how many published a new snapshot.
auto DispatchCount() const -> uint64_t: Inputs delivered to documents so far (moves arriving between two updates count as one).
auto LastUpdateGroups() const -> uint32_t: How many independent groups of documents the last UpdateAll had.
auto UpdateJobCount() const -> uint64_t: Jobs dispatched for document updates so far.
auto LastUpdateLate() const -> uint32_t: Documents the last UpdateAll returned without: still updating, from that call or an earlier one.
auto LateCount() const -> uint64_t: How many documents UpdateAll has returned without, in total.

Function documentation

bool UIHost::Mount(PlatformWindowID window, GGUI::ComponentFn root, const GGUI::StyleTable* styles = nullptr, PlatformWindowID follows = 0, const GGUI::BindingReader* reader = nullptr)

Mount a document in window, built by root. Replaces whatever the window showed.

Parameters
window	The window to show it in.
root	Stored, and run again when something it watches changes: capture handles and values.
styles	The document's own style table, for a tool that must look the same in every game (it must outlive the document); nullptr for the host's.
follows	The window of a document this one reads or changes while building or handling input (a tool showing another document): the two never update at the same time. 0: none.
reader	The document's own binding reader, for a tool showing its own data (copied); nullptr for the host's.
Returns	False if the request queue is full.

void UIHost::SetStyles(const GGUI::StyleTable* styles)

The style table for documents mounted from now on.

Not owned; must outlive the host. Until one is set, documents get the built-in widget defaults (GGUI::StyleTable::AddDefaults); nullptr goes back to that.

GGUI::GGNotices& UIHost::Notices()

Notices and the platform file dialog (see UINotices.h): one of each, shared by every document and by non-UI code. Any thread.

host.Notices().Show("Build finished", { .Kind = GGUI::GGNotice::Success }); A handler in a document reaches the same services with ui.Notices() and ui.Files(). File dialog results for non-document callers are delivered on Encoder, before an update.

void UIHost::SetDockWindow(PlatformWindowID window, const GGUI::BindingReader* reader = nullptr)

The window whose document shows the dock space's main window (it calls ui.Dock(host.Dock())).

The space's other windows are opened as panels are floated (SetDockWindowSink) and their documents are mounted by the host, with reader (copied) or the host's. Call before the engine runs.

void UIHost::SetWindowPlace(PlatformWindowID window, float x, float y, float pixelDensity)

A window's screen position in window coordinates, and its physical pixels per coordinate.

Needed to drag a tab between windows and to drop one outside them all. Any thread. Never called where the platform doesn't report positions (Wayland).

void UIHost::SetLayoutFile(std::string path, PlatformWindowID shows)

The file layouts are saved in, as hand-editable text (GGDockSpace::Save).

Loaded now if it exists, and written once a layout has changed and settled. shows: the window whose document shows the dock space; the file is written at the end of that document's update. Call before the engine runs, after panels and the default layout are declared.

void UIHost::SetKeyBindingsFile(std::string path)

The file non-default chords are saved in, as hand-editable text (GGActionMap::Save).

Loaded now if it exists, and written whenever a chord changes. Empty: not saved. Call before the engine runs.

void UIHost::SetStrings(const GGUI::GGStringTable* strings)

The active language for every document (see UIStrings.h); null for default text.

Not owned, must outlive its use, and must not change while set: switch languages by setting another table. Any thread; applied at each document's next update.

void UIHost::SetReducedMotion(bool bReduced)

Reduced motion: style transitions complete instantly in every document.

The engine sets it from the OS preference; a game's own setting can too. Any thread; applied at each document's next update.

void UIHost::AddSheetFile(GGUI::StyleTable& table, std::string_view name, std::string_view path)

It is read before the next UI update and, while watching, again on every save, so a running document restyles as its sheet is edited. An unreadable file is logged with its line and the table keeps what it had. The table must outlive the host or be removed with RemoveSheetFiles. Any thread.

void UIHost::AddWidgetFiles(std::string_view path, bool bStarters = false)

Read widget assets (.tnxwidget), tables (.tnxtable), and the sheets they name (.ggss) from path, a file or a folder, into the library every document's ui.Use builds from.

Read before the next UI update and, while sheets are watched, again on every save; the documents using a changed asset build again. With bStarters its widget assets are starters, which a project asset of the same name replaces. Any thread.

void UIHost::EnablePreviewWidgets()

Read widget files into the preview library too. The editor calls it at startup.

The preview library is a second library over the same files, in which an editor (the widget designer) can give an asset's text before it is saved. Nothing builds from it unless told to (DocumentProps::Widgets), so a running game never sees unsaved work. Off until enabled, so a game doesn't read its files twice.

uint64_t UIHost::SetPreviewText(TnxName asset, std::string file, std::string text)

Build asset from text in the preview library from the next pump, until ForgetPreview.

file is where it is, if the library hasn't read it. Any thread. Returns the serial that PreviewProblems reports once this text is in.

void UIHost::ChangeStyles(const GGUI::StyleTable& table, std::function<void()> change)

Change a style table that is in use: change is called on Encoder, before an update, once none of the documents using table is updating (those about to start wait for it).

Any thread. Whatever change captures must still be alive when it runs.

std::atomic<float>& UIHost::UpdateBudgetSetting()

How long UpdateAll waits for documents, in milliseconds from when it is called (the console's ui.update_budget_ms).

A document not done by then finishes on its job. 0 or less: wait for every document.

std::atomic<float>& UIHost::BuildBudgetSetting()

How long one document update spends building deferred content (BoxProps::Priority), in milliseconds (the console's ui.build_budget_ms); the rest is built in later frames.

0 or less: build everything in the update that built its box.

bool UIHost::RouteInput(const PlatformEvent& event)

Route a pointer event (move, button, wheel, leave), key event, or gamepad button for a window.

True if the UI takes it, in which case it must not also go to the game. Pointer: it is over something in the document that blocks it, or the document has captured the pointer from an earlier press. Key: the document has keyboard focus, or the key is Tab and something is focusable. Any other event, or a window with no document, isn't taken.

void UIHost::UpdateAll(std::span<const Surface> surfaces)

Update the documents of surfaces and publish each one that changed.

Unrelated documents update in parallel (see Threads, above); related ones in the order given. Returns when all are done or the budget runs out: a document still updating is drawn from its last snapshot. Windows without a document, and documents still updating from an earlier call, are skipped.

GGUI::SnapshotRead UIHost::Read(PlatformWindowID window) const

The snapshot of window's document to draw this frame; empty if there is no document or nothing is published.

For a document still updating when UpdateAll returned, this is the snapshot it had published by then, even if it publishes again before the frame is drawn: the glyphs a newer one needs may not be on the GPU yet.

UIHost class #include <Runtime/UI/Public/UIHost.h>