GGUI::UIContext class

#include <GGUI/Public/UIContext.h>

Public types

struct Clipboard

System clipboard access. Set on the root document; called on the UI update. Fetched text arrives later as InputKind::Paste.

struct PopupWindows

Host support for popups in their own OS window. Set on the root document; called on the UI update.

struct SourceSite

Source location an element was built at.

struct DebugTotals

Lifetime counters. An idle document's don't move.

struct MemoryUse

Memory held by one part of the document.

enum ScopeKind: uint8_t { ScopeOwn, ScopeUse, ScopeSite, ScopeAsset }

Which of a node's scopes: its own ui.Tokens; on a used asset's instance, the tokens code gave it, those written on the use, and the asset's own that are formulas.

enum DebugOverlay: uint8_t { OverlayRepaints = 1 << 0, OverlayLayout = 1 << 1, OverlayFocus = 1 << 2, OverlayBlocks = 1 << 3, OverlayMoving = 1 << 4 }

Debug overlays a tool can enable.

using DiagnosticFn = void(*)(void*context, std::string_view message)

Receives authoring warnings, in addition to the log (UI channel). For tools that show them in place, and for tests. Called on the UI update.

using WidgetActionFn = void(*)(void*context, const GGWidgetAction&action)

Receives what asset elements do when used (a command, a call, show, ...).

Public static variables

static size_t LiveTokens constexpr

Live tokens one scope of a node can have (ScopeSite and ScopeAsset each).

Public static functions

static void VerifyEveryPublish(bool bOn)

For tests: verify every snapshot as it is published, in every document. Differences are logged and counted (VerifyFailures).

static auto VerifiesEveryPublish() -> bool

Whether every publish is verified.

static auto VerifyFailures() -> uint32_t

Publishes that differed from a rebuild, since the program started.

Constructors, destructors, conversion operators

UIContext()

An empty document, laid out on a 0 by 0 surface until SetSurface.

~UIContext()

Destroys the tree; a popup's document leaves its owner.

UIContext(const UIContext&) deleted

Public functions

auto operator=(const UIContext&) -> UIContext& deleted

template<typename TFn>

auto Build(TFn&& component) -> BuildStats

Build or update the tree by running component(UI&). Returns what changed. The function runs now and isn't stored, so it may capture by reference.

template<typename TFn>

auto BuildTemplate(TFn&& widget) -> BuildStats

Build this context as a template: widget(UI&, TemplateEntity) runs once and the result is drawn for many entities, with per-entity data coming only through bindings made from the TemplateEntity.

auto IsTemplate() const -> bool

Whether it was built as a template.

auto IsTemplateValid() const -> bool

True if built as a template with nothing rejected.

auto TemplateErrors() const -> std::span<const TemplateError>

What a template build rejected.

void SetEditors(const EditorRegistry* editors)

Editor registry for ui.Editor (Fields.h). Not owned; must outlive the context.

auto IsDragging() const -> bool

True while a drag is in progress (UIDragDrop.h).

void SetNotices(GGNotices* notices, bool bShows)

Notice service for this document's handlers, and whether this document displays them (one window of several does). Not owned. Null: the document keeps and shows its own.

auto Notices() -> GGNotices&

The notice service its handlers use.

void SetFiles(GGFiles* files)

File dialog service for this document's handlers. Not owned. Null: no file dialog.

void SetDragBridge(const DragBridge& bridge)

Lets a host route drags started here to other documents (see DragBridge).

void CarryOver(uint64_t type, const void* bytes, float x, float y)

A drag from another document is over this one at (x, y): this document's targets for that type become live.

auto CarryEnd(float x, float y, bool bDrop) -> bool

See CarryOver.

void SetActions(GGActionMap* actions)

Action map. Not owned; must outlive the context. Null: the context keeps its own.

auto Actions() -> GGActionMap&

The action map in use.

auto Actions() const -> const GGActionMap&

The action map in use.

auto KeyName(GGKey key) const -> std::string

Localised display text for a key ("O").

auto ChordText(GGChord chord) const -> std::string

Localised display text for a chord ("Ctrl+O").

void SetInputDevice(const GGInputDevice& device)

What the player is using (a gamepad, or keyboard and mouse): action prompts show its keys or buttons. Dispatch sets it from the input it is given; a host may set it for every document.

auto InputDevice() const -> const GGInputDevice&

What the player is using.

auto HasCommand(const GGInputAction& action, NodeHandle from) const -> bool

Whether a command for action exists from from outward (null: from the root). A popup's search continues from the element it belongs to.

auto RunCommand(const GGInputAction& action, NodeHandle from) -> bool

Run the command for action nearest from. False if there is none.

auto RunChord(GGChord chord, NodeHandle from) -> bool

Run the command bound to chord, from from outward. False if there is none.

void SetStyles(const StyleTable* styles)

Style table (Paint.h). Not owned; must outlive the context. Null: only text is drawn.

void SetStrings(const GGStringTable* strings)

String table for the active language (UIStrings.h).

auto Lookup(std::string_view key) const -> std::string_view

Localised text for key, or the key itself.

auto FindString(std::string_view key) const -> const std::string*

The active table's text for key, else the default table's; null if neither has it.

void Mount(ComponentFn root)

Store root as the root function so Update can re-run it. It runs on the next Update.

auto Update() -> BuildStats

The per-frame step: re-run every component whose watched data or local state changed, parents before children. With nothing changed, no function runs. Returns what changed.

void SetBuildBudget(float seconds)

Time budget, in seconds from the start of an update, for building deferred content (BoxProps:: Priority).

auto WaitingCount() const -> uint32_t

Boxes with content still to build.

auto UpdateBindings(const BindingReader& reader) -> BindingStats

Evaluate bindings against reader and apply changed values. Paint-only properties mark the node for repaint, layout-affecting ones for layout. No function runs.

auto BindingCount() const -> uint32_t

How many bindings are declared.

auto Apply(MutationQueue& queue) -> uint32_t

Apply requests queued by other threads (MutationQueue.h). Call at the start of the UI update. The changes are tracked like any others.

void SetDiagnostics(DiagnosticFn fn, void* context)

Where authoring warnings go besides the log; null: the log only.

void SetWidgets(const GGWidgetLibrary* widgets)

The assets ui.Use builds. Not owned; must outlive the context. A Load into it re-runs the components using its assets.

auto GetWidgets() const -> const GGWidgetLibrary*

The library set.

void SetWidgetActions(WidgetActionFn fn, void* context)

Where asset actions go. Without one, each is reported as unhandled.

void RunWidgetAction(const GGWidgetAction& action)

Run action: play and stop here, on the nearest element with the clip; everything else through SetWidgetActions.

void ReportWidgetProblem(const GGWidgetProblem& problem) const

A problem found building an asset: logged and passed to the diagnostics callback.

void SetSurface(float width, float height, float scale = 1.0f)

The surface to lay out on: size in UI units, and physical pixels per UI unit. A surface is a size and a scale, not a window.

void SetSafeArea(const GGEdges& insets)

Insets from the surface's edges that the platform keeps content out of (a notch, rounded corners, a TV's overscan), in UI units. ui.SafeArea keeps its content inside them.

auto SafeArea() const -> const GGEdges&

The insets set.

auto SafeAreaChanged() const -> const GGRevision&

Bumped when the insets change.

void SetTextMeasurer(const TextMeasurer& measurer)

Text measurement backend. Null: the fixed-metric measurer.

void SetLayoutNumeric(LayoutNumeric numeric)

Numeric type for layout. Changing it re-lays-out everything.

auto LayoutChecksum() const -> uint64_t

A hash of every node's computed layout in tree order. Equal hashes mean bit-identical layouts; used to compare runs and machines.

auto UpdateLayout() -> LayoutStats

Lay out whatever changed since the last call (new nodes, changed layout props or text, layout-affecting bindings) and what depends on it. With nothing changed, does nothing.

auto RectOf(NodeHandle node) const -> GGRect

The node's pixel-snapped rect in document space, with enclosing scroll offsets and zooms applied. As of the last UpdateLayout.

auto ClipOf(NodeHandle node) const -> GGRect

The region the node may draw in: the surface clipped by every clipping or scrolling ancestor.

void ContentSize(NodeHandle node, float& width, float& height) const

Size of the node's content including padding: the scrollable extent.

void SetScroll(NodeHandle node, float x, float y)

Set a scrolling box's offset, clamped to its range. Paint-only: no layout.

void SetPan(NodeHandle node, float x, float y, float zoom)

Set an Overflow::Pan box's view: content point (x, y) at its top left, drawn zoom times bigger. No limits. Paint-only: no layout.

auto ScaleOf(NodeHandle node) const -> float

How much bigger than its own units the node is drawn: the zooms of the Pan boxes around it.

auto BaselineOf(NodeHandle node) const -> float

Distance from the node's top to its first text baseline.

auto TextRunOf(NodeHandle node) const -> uint64_t

The node's shaped text run (TextMetrics::Run); 0 = none.

auto PublishSnapshot() -> uint64_t

Publish the document: every node's position, clip, and paint inputs, for the hit-testing and render threads.

void SetGlyphSource(const GlyphSource* glyphs)

Glyph placement backend (Paint.h): the text engine the measurer comes from. Not owned; must outlive the context. Null: text draws as blocks.

void SetImageSource(const ImageSource* images)

Image backend (Paint.h). Not owned; must outlive the context. Null: images have no size and draw nothing.

auto Viewports() const -> std::span<const ViewportSize>

Every viewport's pixel size, as of the last UpdateLayout.

auto ViewportSizeOf(ImageID target, uint32_t& width, uint32_t& height) const -> bool

Pixel size of the viewport showing target. False if none does.

auto ImageOf(NodeHandle node) const -> ImageID

The image of an image or viewport node; ImageID::None otherwise.

auto NeedsPublish() const -> bool

True if anything a snapshot holds has changed since the last publish, including the styles it is drawn with.

auto StyleRevision() const -> uint64_t

Changes whenever a style may have: the table, an asset's styles, tokens set by an element.

auto PublishIfChanged() -> uint64_t

Publish only if something changed. Returns the new sequence number, or 0 if there was nothing to publish.

auto ReadSnapshot() const -> SnapshotRead

The latest published snapshot. Any thread; never blocks. Empty until the first publish.

auto VerifySnapshot(std::string& why) const -> bool

For tests: rebuild every row of the latest snapshot from scratch and compare with what was published.

auto Snapshots() const -> const SnapshotChain&

The published snapshots.

auto RootNeedsBuild() const -> bool

True if something the root watches changed and the root was built with Build (which stores no function to re-run). Call Build again.

auto StateCount() const -> uint32_t

How many ui.State values are kept.

void AdvanceFrame()

End of a UI frame: advances the storage's recycle window.

auto Root() const -> NodeHandle

The root node.

auto Nodes() const -> const NodeStorage&

The tree.

auto Type(NodeHandle node) const -> WidgetType

What kind of element the node is.

auto Layout(NodeHandle node) const -> LayoutInput

The node's layout inputs; default-made if the node is stale.

auto Text(NodeHandle node) const -> std::string_view

Text of a Text or Button node; empty otherwise.

auto ClassID(NodeHandle node) const -> uint64_t

Hash of the node's style class; 0 = none.

auto Paint(NodeHandle node) const -> PaintInput

The node's paint inputs; default-made if the node is stale.

auto Access(NodeHandle node) const -> AccessInfo

Accessibility role and state.

auto AccessName(NodeHandle node) const -> std::string_view

Accessible name: the one its content set, else its text.

auto AccessDescription(NodeHandle node) const -> std::string_view

Accessible description; empty if none was set.

auto Dirty(NodeHandle node) const -> uint8_t

NodeDirty flags set since they were last cleared.

void ClearDirty(NodeHandle node)

Clear the node's NodeDirty flags.

auto Click(NodeHandle node) const -> bool

Run the node's click handler as if it were clicked. False if it has none.

auto Dispatch(const InputEvent& event) -> DispatchStats

Process one input: update hover and pressed state and run the resulting handlers.

auto State(NodeHandle node) const -> uint8_t

NodeState bits.

void ForceState(NodeHandle node, uint8_t state)

For tools: show node as if it were also in state (NodeState bits: hovered, pressed, focused, disabled), whatever the pointer and focus do, until forced to 0.

auto ForcedState(NodeHandle node) const -> uint8_t

The state forced on node; 0 if none.

auto Hovered() const -> NodeHandle

Topmost pointer-blocking node under the pointer; null if none.

auto Pressed() const -> NodeHandle

The node that has captured the pointer; null if none.

auto Focused() const -> NodeHandle

The focused node; null if none.

auto IsFocusVisible() const -> bool

True if focus is being driven by keys, so the focus ring shows and keys belong to the UI.

void SetFocus(NodeHandle node, bool bFromKeys)

Focus node (null clears focus). bFromKeys: it was moved by keyboard or gamepad, so the ring shows and it is scrolled into view. A click passes false.

auto Cursor() const -> CursorShape

The cursor to show: from the hovered node or its nearest ancestor that sets one.

auto Value(NodeHandle node) const -> float

What a value widget currently shows: its own value while held and until the bound value next changes; otherwise the bound value.

auto ValueBitsOf(NodeHandle node) const -> ValueBits

Same, as raw bits.

auto ValueOpsOf(NodeHandle node) const -> const ValueOps*

The ops for the value's type; null if the node isn't a value widget.

template<ValueType T>

auto ValueAs(NodeHandle node) const -> T

The value as T, which must be the widget's type.

auto IsEditing(NodeHandle node) const -> bool

True while the user is holding the widget.

void BeginEdit(NodeHandle node)

Begin an edit, as the user would. Called by a widget's own handlers, and by tests and tools to act as a user.

void ChangeEdit(NodeHandle node, float value)

Change the edit's value, clamped and snapped to the widget's range and step.

void ChangeEditBits(NodeHandle node, ValueBits value)

The same, in the value's own type.

void CommitEdit(NodeHandle node)

Finish the edit.

void CancelEdit(NodeHandle node)

Abandon the edit: the widget reverts to its starting value and its author is told.

void StepEdit(NodeHandle node, int steps)

A complete edit moving the value by steps.

auto Reacts(NodeHandle node, GGReaction reaction) const -> bool

True if the node itself (not an ancestor) has reaction.

auto LastBuild() const -> const BuildStats&

What the last build or update changed.

auto TextCaret() const -> GGRect

Caret rect of the text-focused widget, in document space. Empty if none.

auto WidgetState(NodeHandle node, const WidgetDef& definition) const -> void*

The node's widget state if it is this kind, else null. Typed version: WidgetOf<T>.

template<typename T>

auto WidgetOf(NodeHandle node) const -> T*

The node's state if it is a T widget, else null.

auto WidgetName(NodeHandle node) const -> std::string_view

The node's widget kind name, for tools; empty if it isn't a widget.

void SetClipboard(const Clipboard& clipboard)

The system clipboard.

auto CopyToClipboard(std::string_view text) -> bool

Put text on the clipboard. False if there is no clipboard.

auto AskForPaste() -> bool

Request the clipboard. It arrives as a Paste for whatever has focus at that point.

auto WantsText() const -> bool

A text widget has focus, so every key is the UI's.

auto WantsTextEntry() const -> bool

And it takes typed text: the platform should deliver text input.

void SetPopupWindows(const PopupWindows& windows)

Where popups that ask for their own window go. Without it, every popup is in-window.

void SetPopupRoom(const GGRect& room)

The area a popup window may be placed in: the screen, in this document's space.

auto PopupWindowFailed(uint64_t popup) -> bool

The host couldn't give this popup a window: draw it in-window instead.

auto IsPopupInWindow(uint32_t index) const -> bool

True if the popup at index is in its own window.

void AdvanceTime(float seconds)

Advance document time, in seconds. Tooltip delays and transitions use it. Call once per UI update.

void SetTooltipDelay(float seconds)

Hover time before a tooltip shows.

auto StylesInUse() const -> const StyleTable*

The style table in use (SetStyles).

auto LinkCount(NodeHandle node) const -> uint32_t

How many links (<link Name>...</link>) a rich text node has.

auto LinkName(NodeHandle node, int link) const -> std::string_view

The name of link link, counting in order from 0.

auto LinkAt(NodeHandle node, float x, float y) const -> int

The link at a point relative to the node's top left; -1 if none.

auto FocusLinkOf(NodeHandle node) const -> int

The link the keys are on; -1 if none.

auto Play(NodeHandle node, std::string_view clip) -> bool

Play a clip declared on node (ui.Clip) from its start. False, reported, if there is none.

void Stop(NodeHandle node, std::string_view clip)

Stop it: what it set goes back to rest.

auto IsPlaying(NodeHandle node, std::string_view clip) const -> bool

Whether the clip is playing on node.

auto ClipTime(NodeHandle node, std::string_view clip) const -> float

Where a playing clip is, in seconds from its start (going back, as it plays back); -1 if it isn't playing. For tools that follow it.

auto Pose(NodeHandle node, std::string_view clip, float seconds) -> bool

Hold the clip still at seconds from its start (a tool scrubbing it): it shows what it sets then, and doesn't run. Play runs it again, Stop lets go. False if there is none.

void RunClipEvents(NodeHandle node, std::string_view clip, float from, float to)

Run the events of a clip declared on node from from (excluded) to to (included) seconds of its time, or back from from to to: a tool scrubbing it that wants them.

auto HasClip(NodeHandle node, std::string_view clip) const -> bool

True if a clip by that name is declared on node.

void SetTween(NodeHandle node, GGProperty property, float seconds, GGEase ease = GGEase::Out)

A bound property of node glides to each new value over seconds instead of jumping: a counter rolls up, a bar slides. Set after the binding, each build.

void DeclareClip(NodeHandle node, std::string_view name, std::shared_ptr<const GGClip> clip, std::span<const NodeHandle> targets, const GGBinding* rate, uint32_t serial, std::shared_ptr<const std::vector<GGWidgetAction>> events = nullptr)

Declare a clip on node, its tracks animating targets (one per track). Kept while a run of its content with serial declares it. rate: a bound speed, read each frame.

void DeclareTrigger(NodeHandle owner, uint32_t index, GGTrigger when, const GGBinding& value, NodeHandle watched, uint8_t state, bool bPlay, std::string_view clip, uint32_t serial)

Start or stop clip on owner when a value rises, falls, or changes (value: a binding, or a constant one; Rises starts from 0, so a constant 1 fires once), or when watched enters or leaves state.

void NameElement(NodeHandle owner, uint64_t name, NodeHandle node, uint32_t serial)

Record that node is the element named name in what owner built: for actions that play a clip in it ("in") and for tools.

auto NamedElement(NodeHandle owner, uint64_t name) const -> NodeHandle

The node recorded as element name in what owner built; null if none.

auto TransformOf(NodeHandle node) const -> const GGTransform*

Its group transform (GGTransform); null if it has none.

void SetTransform(NodeHandle node, const GGTransform& transform)

Set it, keeping any part a binding sets.

auto StyleOf(NodeHandle node) const -> const PaintStyle&

The node's look as resolved now, scopes and all, in its own state. For tools and tests.

void ExplainStyle(NodeHandle node, uint8_t state, std::vector<GGStyleOrigin>& out) const

For tools: where each property of the node's look in state comes from.

auto FindToken(std::string_view name, std::string_view scopes, GGColor& out) const -> bool

A colour token's value as an element with these scope classes sees it. False if there is none.

auto FindToken(std::string_view name, std::string_view scopes, float& out) const -> bool

The same, for a number token.

auto SetNodeTokens(NodeHandle node, ScopeKind kind, uint32_t rank, std::span<const GGTokenSet> tokens, uint32_t serial, std::string_view label, std::span<const GGLiveToken> live = {}) -> std::string_view

Give tokens to everything built inside node at rank, until a run of its content with another serial doesn't declare them.

auto OwnScopeOf(NodeHandle node) const -> std::string_view

The class of the node's own ui.Tokens scope; empty if none.

auto ComponentScope(NodeHandle component) const -> const std::string&

The scope classes a component was declared in.

void SetComponentScope(NodeHandle component, std::string_view scope)

Set the scope classes a component was declared in.

auto LocalStyleScopes() const -> const GGStyleScopes&

The document's own scopes: those its elements' tokens make.

void SetReducedMotion(bool bReduced)

Reduced motion (user or platform setting): styles change instantly regardless of their transition times. A popup inherits it from its owner.

auto ReducedMotion() const -> bool

Whether reduced motion is on, its own or its owner's.

auto LooksMoving() const -> uint32_t

Nodes mid-transition in the last snapshot. While non-zero, the document publishes every time its clock advances.

auto TransitionsBegun() const -> uint64_t

Total transitions started.

auto PopupCount() const -> uint32_t

Open popups, oldest first. Each is its own document.

auto PopupDocument(uint32_t index) const -> UIContext*

Popup index's document; null past the last.

auto PopupKindOf(uint32_t index) const -> PopupKind

What popup index is.

auto PopupAnchor(uint32_t index) const -> NodeHandle

The popup's anchor element.

auto PopupRect(uint32_t index) const -> GGRect

The popup's rect in this document's space.

auto HasCapturingPopup() const -> bool

True while a menu or Popup is open and has captured input.

void ClosePopups()

Close every popup, as a press outside would.

auto IsPopup() const -> bool

True if this document is a popup's content.

auto IsPopupOpenFor(NodeHandle node) const -> bool

True if the element has its own popup open.

auto TreeVersion() const -> uint64_t

Changes whenever a node is created or destroyed or a child list changes.

auto DescribeMemory(std::vector<MemoryUse>& out) const -> size_t

Memory by part, largest first: the tree, each side row, and the snapshots. Memory owned by values (string contents, widget state) isn't counted. Returns the total.

auto SourceOf(NodeHandle node) const -> SourceSite

Where the node was built.

auto ClassNameOf(NodeHandle node) const -> std::string_view

The node's style class as written; empty = none.

auto Totals() const -> const DebugTotals&

Its lifetime counters.

void DescribeBindings(NodeHandle node, std::string& out) const

The node's bindings, with their last values, as text.

void DescribeReactions(NodeHandle node, std::string& out) const

The node's reactions, as text.

void SetDebugOverlays(uint8_t overlays)

Turn on the DebugOverlay bits in overlays, and off the rest.

auto DebugOverlays() const -> uint8_t

The DebugOverlay bits that are on.

void FocusOrder(NodeHandle node, std::vector<NodeHandle>& out) const

Tab order from node: within its focus scope, else the whole document.

auto FocusToward(NodeHandle from, UIKey direction) const -> NodeHandle

Where an arrow key would move focus from from; null if nowhere.

void DebugSetLayout(NodeHandle node, const LayoutInput& layout)

Override a node's layout inputs from a tool. They apply from the next update until whatever builds the node next gives it different ones.

void SetHighlight(NodeHandle node)

Outline a node (null: none). The outline is the tool's, not part of the document.

auto Highlight() const -> NodeHandle

The outlined node; null if none.

void SetPickMode(bool bOn)

Pick mode: the pointer over this document belongs to the tool.

auto IsPickMode() const -> bool

Whether a tool is picking.

auto Picked() const -> NodeHandle

The node under the pointer while picking, or the last one picked; null if none.

void SetTagsElements(bool bTags)

Remember, for each node a widget asset builds, the asset and element it came from. Off by default: nothing is kept.

auto TagsElements() const -> bool

Whether it remembers.

auto ElementOf(NodeHandle node, TnxName asset) const -> TnxName

The element of asset that built node, or the nearest node above it that one built; invalid if none did.

auto NodeOfElement(TnxName asset, TnxName element) const -> NodeHandle

The first node asset's element built that is still there; null if none.

auto PickCount() const -> uint64_t

How many times picking has ended with a press.

Enum documentation

Function documentation