GGUI::UI class

#include <GGUI/Public/UI.h>

Public types

struct ValueSpec

Type-erased "what it shows" and "what an edit does" for a value widget.

using Where = std::source_location

Where an element is built: identifies it. Left to its default.

Public static functions

template<typename T>

static auto MakeSpec(const GGShows<T>& shows, const GGDoes<T>& does) -> ValueSpec

A value widget's arguments, as a ValueSpec.

Public functions

auto Row(const BoxProps& props = {}, Where where = Where::current()) -> Scope

Children side by side, left to right.

auto Column(const BoxProps& props = {}, Where where = Where::current()) -> Scope

Children one under another, top to bottom.

auto Stack(const BoxProps& props = {}, Where where = Where::current()) -> Scope

Children stacked on top of each other.

auto Grid(const GridProps& props, Where where = Where::current()) -> Scope

Children in columns, filled row by row (GridProps::Columns).

auto Place(const PlaceProps& props, Where where = Where::current()) -> Scope

An overlay on the box being built into: takes no space among its children and sits at PlaceProps::Anchor. Built after them, it is in front.

void Row(const BoxProps& props, ChildrenRef content, Where where = Where::current())

A row whose children content builds now.

void Column(const BoxProps& props, ChildrenRef content, Where where = Where::current())

A column whose children content builds now.

void Stack(const BoxProps& props, ChildrenRef content, Where where = Where::current())

A stack whose children content builds now.

void Grid(const GridProps& props, ChildrenRef content, Where where = Where::current())

A grid whose children content builds now.

void Place(const PlaceProps& props, ChildrenRef content, Where where = Where::current())

An overlay whose children content builds now.

void Row(const BoxProps& props, ComponentFn content, Where where = Where::current())

A row whose children are stored content.

void Column(const BoxProps& props, ComponentFn content, Where where = Where::current())

A column whose children are stored content.

void Stack(const BoxProps& props, ComponentFn content, Where where = Where::current())

A stack whose children are stored content.

void Grid(const GridProps& props, ComponentFn content, Where where = Where::current())

A grid whose children are stored content.

template<ClassText TClass>

auto Row(TClass&& className, Where where = Where::current()) -> Scope

Row, with only a style class.

template<ClassText TClass>

auto Column(TClass&& className, Where where = Where::current()) -> Scope

Column, with only a style class.

template<ClassText TClass>

auto Stack(TClass&& className, Where where = Where::current()) -> Scope

Stack, with only a style class.

template<ClassText TClass>

void Row(TClass&& className, ChildrenRef content, Where where = Where::current())

Row, with only a style class, built now.

template<ClassText TClass>

void Column(TClass&& className, ChildrenRef content, Where where = Where::current())

Column, with only a style class, built now.

template<ClassText TClass>

void Stack(TClass&& className, ChildrenRef content, Where where = Where::current())

Stack, with only a style class, built now.

template<ClassText TClass>

void Row(TClass&& className, ComponentFn content, Where where = Where::current())

Row, with only a style class, as stored content.

template<ClassText TClass>

void Column(TClass&& className, ComponentFn content, Where where = Where::current())

Column, with only a style class, as stored content.

template<ClassText TClass>

void Stack(TClass&& className, ComponentFn content, Where where = Where::current())

Stack, with only a style class, as stored content.

template<ClassText TClass>

auto Label(const GGText& text, TClass&& className, Where where = Where::current()) -> NodeHandle

Label, with only a style class.

template<ClassText TClass>

auto Button(const GGText& label, TClass&& className, PointerHandler onClick, Where where = Where::current()) -> NodeHandle

Button, with only a style class.

auto Spacer(float weight = 1.0f, Where where = Where::current()) -> NodeHandle

Flexible empty space in a row or column. weight is its share relative to other growing children.

auto Label(const GGText& text, const TextProps& props = {}, Where where = Where::current()) -> NodeHandle

Text, localised by default; see UIStrings.h for formats and GGText::Verbatim.

auto Label(const GGBinding& value, const NumberFormat& format = {}, const TextProps& props = {}, Where where = Where::current()) -> NodeHandle

Text showing a bound number, formatted by format. Updates without any re-run; a different number may be a different size, so it triggers layout.

auto RichText(const GGText& text, const RichTextProps& props = {}, Where where = Where::current()) -> NodeHandle

A paragraph with styled parts, inline images, and action prompts, from markup in its string.

auto ActionPrompt(const GGInputAction& action, const TextProps& props = {}, Where where = Where::current()) -> NodeHandle

An input action's key (a "key-cap") or, while a gamepad is in use, its button: the game's image of it (Pad.Xbox.South, by name, in a "pad-glyph") or its label (a "pad-cap").

auto Button(const GGText& label, PointerHandler onClick, Where where = Where::current()) -> NodeHandle

A button with a label: clicking it runs onClick.

auto Button(const GGText& label, const ButtonProps& props, PointerHandler onClick, Where where = Where::current()) -> NodeHandle

The same, with props.

auto Button(const ButtonProps& props, PointerHandler onClick, Where where = Where::current()) -> Scope

A button whose content is what is built inside it (an icon, a label, a badge), in a row: if (auto buy = ui.Button({ .Class = "icon-button" }, onClick)) { ui.Image(coin); ui.Label("Buy"); }.

auto Switcher(const GGBinding& which, Where where = Where::current()) -> Scope

Each element built inside is shown when which is its position (0 first); the others are out of layout and drawing. All are built and kept, so changing which runs nothing.

auto Switcher(int which, Where where = Where::current()) -> Scope

The same, showing element which.

template<typename TFn>

void Repeat(const GGBinding& count, int most, TFn&& item, Where where = Where::current())

item(ui, index) for each index below most, each present while count is above its index: hearts, ammo pips, stars. Built once; a changing count runs nothing.

template<typename TFn>

void Repeat(int count, TFn&& item, Where where = Where::current())

item(ui, index) for each index below count.

auto SafeArea(Where where = Where::current()) -> Scope

Content kept inside the platform's safe area (a notch, rounded corners, a TV's overscan).

auto Progress(const ProgressProps& props, const GGBinding& value, Where where = Where::current()) -> NodeHandle

A bar filled to a fraction: from value's binding, or props.Value.

auto Progress(const ProgressProps& props = {}, Where where = Where::current()) -> Scope

Scope form: bind its value and build overlays inside.

auto Image(ImageID image, const ImageProps& props = {}, Where where = Where::current()) -> NodeHandle

An image by handle (from an ImageSource): a file, an atlas region, or a render target.

auto Image(std::string_view path, const ImageProps& props = {}, Where where = Where::current()) -> NodeHandle

An image by path, resolved at build. A missing path warns with this source line.

auto Swatch(GGColor colour, const SwatchProps& props = {}, Where where = Where::current()) -> NodeHandle

A box whose colour is data, not style (SwatchProps).

auto Color(const ColorProps& props, GGColor shows, HandlerOf<GGColor> does, Where where = Where::current()) -> NodeHandle

A swatch that opens a colour picker (saturation/value square, hue bar, alpha bar, hex). does(colour) is called on every change.

auto Color(GGColor shows, HandlerOf<GGColor> does, Where where = Where::current()) -> NodeHandle

The same, with default props.

auto Viewport(ImageID target, const ImageProps& props = {}, Where where = Where::current()) -> NodeHandle

A render target sized by layout. Give it a size (Grow, Fixed, Percent); its pixel size is published after layout (UIContext::Viewports) for the renderer to follow.

template<typename TDraw>

auto Canvas(const CanvasProps& props, TDraw&& draw, Where where = Where::current()) -> Scope

Custom drawing (UICanvas.h): draw(GGCanvas&) draws lines, arcs and shapes. Open for handlers and children, like a box.

auto Embed(uint64_t id, const EmbedProps& props = {}, Where where = Where::current()) -> NodeHandle

An area drawn and handled by something else, named by id (EmbedProps).

auto Document(GGDocument& document, const DocumentProps& props, ComponentFn content, Where where = Where::current()) -> NodeHandle

A document inside this one, kept in document: content laid out on the screen props describes, drawn scaled to fit its box (UIDocument.h). Returns the box.

auto Toggle(const GGText& label, const GGShows<bool>& shows, const GGDoes<bool>& does = {}, Where where = Where::current()) -> NodeHandle

A switch, with or without a label. Clicking anywhere on it toggles.

auto Toggle(const GGText& label, const ToggleProps& props, const GGShows<bool>& shows, const GGDoes<bool>& does = {}, Where where = Where::current()) -> NodeHandle

The same, with props.

auto Toggle(const GGShows<bool>& shows, const GGDoes<bool>& does = {}, Where where = Where::current()) -> NodeHandle

A switch with no label.

auto Toggle(const ToggleProps& props, const GGShows<bool>& shows, const GGDoes<bool>& does = {}, Where where = Where::current()) -> NodeHandle

A switch with no label, with props.

auto Toggle(const ToggleProps& props, const GGShows<bool>& shows, const GGDoes<bool>& does, ChildrenRef content, Where where = Where::current()) -> NodeHandle

A toggle whose content is content instead of a track and label: a button that stays in (:checked) while the value is true. Its class defaults to "toggle-button".

template<typename TShown>

auto Slider(const SliderProps& props, const TShown& shows, const GGDoes<Detail::ShownType<TShown>>& does = {}, Where where = Where::current()) -> NodeHandle

A draggable track and thumb. Typed like ui.Number.

template<typename TShown>

auto Slider(const TShown& shows, const GGDoes<Detail::ShownType<TShown>>& does = {}, Where where = Where::current()) -> NodeHandle

The same, from 0 to 1.

template<typename TShown>

auto Number(const NumberProps& props, const TShown& shows, const GGDoes<Detail::ShownType<TShown>>& does = {}, Where where = Where::current()) -> NodeHandle

A numeric field that is typed or dragged (NumberProps), edited in the type of what it shows: int, int64_t, float, double, or Fixed32.

template<typename TShown>

auto Number(const TShown& shows, const GGDoes<Detail::ShownType<TShown>>& does = {}, Where where = Where::current()) -> NodeHandle

The same, with default props.

template<NumberType T>

auto NumberOf(const NumberProps& props, const GGShows<T>& shows, const GGDoes<T>& does = {}, Where where = Where::current()) -> NodeHandle

The same, edited as T whatever shows is: for a bare binding of a non-float field.

template<NumberType T>

auto VectorOf(std::initializer_list<GGShows<T>> shows, const VectorProps& props, GGVectorDoes<T> does = {}, Where where = Where::current()) -> NodeHandle

Labelled numeric fields side by side, edited as T, with one handler told which component changed. ui.Vector is the float form.

auto Vector(std::initializer_list<GGShows<float>> shows, const VectorProps& props, GGVectorDoes<float> does = {}, Where where = Where::current()) -> NodeHandle

Labelled float fields side by side, with one handler told which component changed: ui.Vector({ x, y, z }, props, [](int axis, float value) { ... });. For another type use ui.VectorOf<Fixed32>({ x, y, z }, props, ...).

auto Vector(std::initializer_list<GGShows<float>> shows, GGVectorDoes<float> does = {}, Where where = Where::current()) -> NodeHandle

The same, with default props.

auto Carousel(std::span<const std::string_view> options, const CarouselProps& props, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

One of options, changed with the arrows beside it or Left and Right when focused (< Medium >): a dropdown for a gamepad. The value is the selected option's index.

auto Carousel(std::initializer_list<std::string_view> options, const CarouselProps& props, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

The same, options written in place.

auto Dropdown(std::span<const std::string_view> options, const DropdownProps& props, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

The chosen one of options, and a menu of them all. The value is the selected index.

auto Dropdown(std::initializer_list<std::string_view> options, const DropdownProps& props, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

The same, options written in place.

auto Dropdown(std::span<const std::string_view> options, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

The same, with default props.

auto Dropdown(std::initializer_list<std::string_view> options, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

The same, options written in place, with default props.

auto Choice(std::span<const std::string_view> options, const ChoiceProps& props, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

A segmented control: a few options side by side. The value is the selected index.

auto Choice(std::initializer_list<std::string_view> options, const ChoiceProps& props, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

The same, options written in place.

auto Choice(std::span<const std::string_view> options, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

The same, with default props.

auto Choice(std::initializer_list<std::string_view> options, const GGShows<int>& shows, const GGDoes<int>& does = {}, Where where = Where::current()) -> NodeHandle

The same, options written in place, with default props.

auto TextField(const TextFieldProps& props, const ShowsText& shows, const GGDoes<std::string_view>& does = {}, Where where = Where::current()) -> NodeHandle

Single-line editable text.

auto TextArea(const TextAreaProps& props, const ShowsText& shows, const GGDoes<std::string_view>& does = {}, Where where = Where::current()) -> NodeHandle

Multi-line editable text; scrolls when it doesn't fit.

auto SearchField(const SearchFieldProps& props, const ShowsText& shows, const GGDoes<std::string_view>& does = {}, Where where = Where::current()) -> NodeHandle

A text field with a clear button.

auto SearchField(const ShowsText& shows, const GGDoes<std::string_view>& does = {}, Where where = Where::current()) -> NodeHandle

A search field with default props.

auto TextField(const ShowsText& shows, const GGDoes<std::string_view>& does = {}, Where where = Where::current()) -> NodeHandle

A text field with default props.

auto TextArea(const ShowsText& shows, const GGDoes<std::string_view>& does = {}, Where where = Where::current()) -> NodeHandle

A text area with default props.

template<typename T>

auto Widget(Where where = Where::current(), WidgetType type = WidgetType::Box) -> WidgetScope<T>

Make the node a widget of kind T. Its state is created on first build and found afterwards.

auto BeginWidget(const WidgetDef& definition, void*& state, const Where& where, WidgetType type = WidgetType::Box) -> NodeHandle

The untyped core of Widget<T> and WidgetScope<T>.

void EndWidget()

Close the widget BeginWidget opened.

void WidgetLayout(NodeHandle node, const LayoutInput& layout)

Set a widget node's layout inputs.

void WidgetClass(NodeHandle node, std::string_view name)

Set a widget node's style classes.

void WidgetAccess(NodeHandle node, GGRole role, uint8_t state)

Set a widget node's accessibility role and state (AccessState bits).

void WidgetReact(NodeHandle node, GGReaction reaction, const GGHandler& handler, CursorShape shape = CursorShape::Arrow)

Give a widget node a reaction: handler for reaction, and shape for Cursor.

void WidgetAccessName(NodeHandle node, std::string_view name)

Set a widget node's accessible name.

void WidgetValue(NodeHandle node, const ValueSpec& spec, float min, float max, float step, uint8_t decimals, const Where& where)

Make the node a value node: what it shows, what an edit does, and its range.

auto VectorParts(std::span<const ValueSpec> parts, const VectorProps& props, Where where = Where::current()) -> NodeHandle

A vector from pre-built components (ValueSpec each), for editors building them from fields.

void WidgetValueBits(NodeHandle node, const ValueSpec& spec, ValueBits min, ValueBits max, ValueBits step, uint8_t decimals, const Where& where)

Same, with the range in the value's own type.

auto WidgetPart(WidgetType type, const LayoutInput& layout, std::string_view className, Where where = Where::current()) -> NodeHandle

A child that paint draws by type (a toggle's track and knob).

auto WidgetTextPart(std::string_view className, Where where = Where::current()) -> NodeHandle

A text child the widget writes itself (WidgetHost::SetText).

auto Document() -> UIContext&

The document being built.

auto LogView(const LogViewProps& props, const GGLineSource& lines, Where where = Where::current()) -> NodeHandle

A virtualised log view, newest line at the bottom.

auto CommandLine(const CommandLineProps& props, const GGCommandSource& commands, Where where = Where::current()) -> NodeHandle

A command line with history and completion.

void Tooltip(const GGText& text)

Shown on hover after a delay, or at once on keyboard focus.

void Tooltip(ComponentFn content)

The same, with content built when it shows.

void Tooltip(const UseProps& asset)

A widget asset as the tooltip (UIWidgetAsset.h).

void Menu(ComponentFn content)

Opened by a click, or by accept when focused.

void Menu(const PopupProps& props, ComponentFn content)

The same, placed by props.

void ContextMenu(ComponentFn content)

Opened by a right click, at the pointer.

void Popup(GGUI::GGState<bool> open, const PopupProps& props, ComponentFn content)

Open while open is true. Escape or a press outside sets it false.

auto Notices() -> GGNoticeHandle

Handles for handlers to capture (UINotices.h): auto notices = ui.Notices(); ... [=] { notices.Show("Saved"); }.

auto Files() -> GGFileHandle

The same, for the file dialog: auto files = ui.Files();.

void Dialog(GGUI::GGState<bool> open, const DialogProps& props, ComponentFn content)

A modal dialog, open while open is true (DialogProps).

template<typename TFn>

void Ask(const GGUI::GGState<bool>& open, const AskProps& props, TFn answer)

A dialog with one button per choice (AskProps): [=](int choice) { ... }.

auto MenuItem(const GGText& label, PointerHandler onClick, Where where = Where::current()) -> NodeHandle

Choosing it runs onClick and closes the menu.

auto MenuItem(const GGText& label, const MenuItemProps& props, PointerHandler onClick, Where where = Where::current()) -> NodeHandle

The same, with props.

auto MenuItem(const GGInputAction& action, const MenuItemProps& props = {}, Where where = Where::current()) -> NodeHandle

A menu item for an action: shows its title and current chord, and runs the nearest ui.Command for it. Disabled if no command is in reach.

auto SubMenu(const GGText& label, ComponentFn content, Where where = Where::current()) -> NodeHandle

A menu item that opens a nested menu.

auto Separator(Where where = Where::current()) -> NodeHandle

A divider. Vertical inside a toolbar.

auto Dock(GGDockSpace& space, const DockProps& props = {}, Where where = Where::current()) -> NodeHandle

Docked panels, where the user has arranged them (UIDock.h).

auto Split(const SplitProps& props, ComponentFn first, ComponentFn second, Where where = Where::current()) -> NodeHandle

Two panes and a divider the user drags (SplitProps).

auto Split(ComponentFn first, ComponentFn second, Where where = Where::current()) -> NodeHandle

The same, side by side, halved.

auto Graph(GGGraphView& view, const GraphProps& props, ChildrenRef content, Where where = Where::current()) -> NodeHandle

Panned and zoomed nodes and wires. content declares them with GraphNode and GraphLink; view is the owner's, written as the user pans, zooms and selects.

auto GraphNode(uint64_t id, const GraphNodeProps& props, ChildrenRef content, Where where = Where::current()) -> NodeHandle

A node at its graph position: a title, then content.

auto Pin(uint64_t id, const PinProps& props = {}, Where where = Where::current()) -> NodeHandle

A pin in a GraphNode, where wires start and end. Each pin's ID is unique in the graph.

void GraphLink(uint64_t from, uint64_t to, const GraphLinkProps& props = {})

A wire from an Out pin to an In pin.

auto Tabs(const TabsProps& props, const GGShows<int>& shows, ChildrenRef tabs, Where where = Where::current()) -> NodeHandle

A tab strip and the selected tab's content. tabs declares the tabs (ui.Tab). The value is the selected index, shown and edited like a dropdown's.

auto Tabs(const TabsProps& props, const GGShows<int>& shows, const GGDoes<int>& does, ChildrenRef tabs, Where where = Where::current()) -> NodeHandle

The same, with what a change of tab does.

auto Tabs(const GGShows<int>& shows, ChildrenRef tabs, Where where = Where::current()) -> NodeHandle

The same, with default props.

auto Tabs(const GGShows<int>& shows, const GGDoes<int>& does, ChildrenRef tabs, Where where = Where::current()) -> NodeHandle

The same, with default props and what a change of tab does.

void Tab(const GGText& title, ComponentFn content, Where where = Where::current())

One tab. Its content is stored and built only while selected.

void Tab(const GGText& title, const TabProps& props, ComponentFn content, Where where = Where::current())

The same, with props.

auto MenuBar(Where where = Where::current()) -> Scope

A horizontal menu bar. Add menus with ui.SubMenu inside. Scope or lambda form, like a row.

auto MenuBar(ChildrenRef content, Where where = Where::current()) -> NodeHandle

The same, built by content now.

auto Toolbar(const ToolbarProps& props = {}, Where where = Where::current()) -> Scope

A row of tool buttons; those that don't fit are listed in a menu at its end. ui.Separator inside it is vertical.

auto Toolbar(ChildrenRef content, Where where = Where::current()) -> NodeHandle

The same, built by content now.

auto Toolbar(const ToolbarProps& props, ChildrenRef content, Where where = Where::current()) -> NodeHandle

The same, with props, built by content now.

auto ToolButton(ImageID icon, const ToolButtonProps& props, PointerHandler onClick, Where where = Where::current()) -> NodeHandle

An icon button. With no icon it shows its tooltip as text.

auto ToolButton(ImageID icon, const GGInputAction& action, const ToolButtonProps& props = {}, Where where = Where::current()) -> NodeHandle

A tool button for an action: uses its title, shows its chord in the tooltip, and runs the nearest ui.Command. Disabled if none is in reach.

void BindProperty(GGProperty property, const GGBinding& binding, Where where = Where::current())

Drive property of the element being built into from binding.

void Value(const GGBinding& binding, Where where = Where::current())

A progress bar's fill fraction.

void Visible(const GGBinding& binding, Where where = Where::current())

Visible while the binding is non-zero.

void Opacity(const GGBinding& binding, Where where = Where::current())

Its opacity, 0..1, multiplying its content's.

void Rotation(const GGBinding& binding, Where where = Where::current())

The element being built into turned (degrees, clockwise), with its content, by data: no layout, a new view each change.

void Clip(std::string_view name, const GGClip& clip)

Declare a clip on the element being built into (UIAnimation.h); UIContext::Play runs it.

auto ScaleBox(const BoxProps& props, GGScaleFit fit = GGScaleFit::Contain, Where where = Where::current()) -> Scope

A box whose content is laid out at its own size and drawn scaled to fit it, centred: a heading that must fit a banner, a HUD that keeps its layout on any screen.

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

A bound property of node glides to each new value over seconds (UIContext::SetTween).

void Scale(const GGBinding& binding, Where where = Where::current())

The element being built into scaled, with its content, by data: no layout, a new view each change.

void Present(const GGBinding& binding, Where where = Where::current())

In layout while the binding is non-zero; at zero it is as if it weren't there. (Visible hides it but keeps its place.).

void OnClick(PointerHandler handler)

Left button pressed and released over it.

void OnPress(PointerHandler handler)

A button went down over it. It captures the pointer until release.

void OnRelease(PointerHandler handler)

The captured button came up, wherever the pointer is.

void OnDrag(PointerHandler handler)

The pointer moved while captured.

void OnHover(HoverHandler handler)

The pointer entered (true) or left (false).

void OnMove(PointerHandler handler)

The pointer moved over it with no button held. (Held, what it pressed hears OnDrag.).

void OnWheel(PointerHandler handler)

The wheel turned over it (PointerEvent::WheelX, WheelY): zoom a view, step a value. It takes the wheel unless it calls Pass, so nothing behind it scrolls.

void OnKey(KeyHandler handler)

Key down while it or a descendant has focus. The handler consumes the key unless it calls event.Pass(), which hands it on to the focused widget and then to focus navigation.

void OnFocus(FocusHandler handler)

Gained (true) or lost (false) keyboard focus.

template<typename T>

void DragSource(const T& value, const DragSourceProps& props = {})

Make the element being built into draggable, carrying value (small and trivially copyable). Declaring it again with another value updates what the next drag carries.

template<typename T, typename TFn>

void DropTarget(TFn onDrop, const DropTargetProps<T>& props = {})

Accept a dropped T: onDrop(value), or onDrop(value, event) for the position. The element has the :drop state while a matching drag is over it; props hears it there.

void Command(const GGInputAction& action, CommandHandler handler)

Bind action for the element being built into and its subtree: its chord runs handler, and so do menu items and buttons given the action.

void Command(GGChord chord, CommandHandler handler)

Same, for a fixed chord that can't be rebound.

auto KeyBinding(const GGInputAction& action, const KeyBindingProps& props = {}, Where where = Where::current()) -> NodeHandle

Shows an action's two chords, primary and alternate, and lets the user rebind either (KeyBindingProps). For settings pages.

void Focusable()

Make it keyboard-focusable: Tab and arrows reach it, Enter or Space clicks it. Buttons and value widgets already are; an element with only OnClick needs this too.

void FocusScope(uint8_t flags)

A focus scope. FocusScopeTrap keeps Tab and arrows inside (dialog, menu); FocusScopeRestore returns focus to where it was when the focused element inside goes away.

void BlocksPointer()

Block the pointer without reacting. A box with a filled style already does.

void Disabled(bool bDisabled = true)

Disable it and its subtree: no input, StateDisabled styling, still blocks the pointer. Declare only while true: ui.Disabled(!bConnected);.

void Cursor(CursorShape shape)

Cursor shown over it. Default: a hand over anything clickable.

void Fields(const FieldSource& source, Where where = Where::current())

One row per field: its name and its registered editor.

void Fields(const FieldSource& source, FieldVisitor content)

Calls content once per field, for custom layout. Key each field's element with its ID (ui.Key(field.ID)).

void Fields(const FieldSource& source, const FieldInfo& parent, FieldVisitor content)

Same, for the fields nested in parent.

void FieldRow(const FieldSource& source, const FieldInfo& field, Where where = Where::current())

One field's row, as Fields(source) builds it. Keyed by the field's ID.

void Editor(const FieldSource& source, const FieldInfo& field, Where where = Where::current())

The editor for field: its field override, else its type's (UIContext::SetEditors). A type with no editor shows its nested fields.

auto Properties(const FieldSource& source, const PropertiesProps& props = {}, Where where = Where::current()) -> NodeHandle

A property grid: name and editor per row, under collapsible categories (PropertiesProps).

auto Properties(const FieldSource& source, const PropertiesProps& props, GGPropertyFn value, Where where = Where::current()) -> NodeHandle

Same, with custom value cells from value(ui, field), which the grid stores.

auto Properties(std::initializer_list<FieldSource> sources, const PropertiesProps& props = {}, Where where = Where::current()) -> NodeHandle

Several sources edited as one: ui.Properties({ first, second }, props).

auto Properties(std::span<const FieldSource> sources, const PropertiesProps& props = {}, Where where = Where::current()) -> NodeHandle

The same, from a list made at run time.

auto Properties(std::span<const FieldSource> sources, const PropertiesProps& props, GGPropertyFn value, Where where = Where::current()) -> NodeHandle

The same, with custom value cells.

void Accessible(const AccessProps& props)

Add accessibility info to the element being built into, beyond what its widget sets: a role for a plain container, a name, a description. Kept while the content keeps declaring it.

void Tokens(std::initializer_list<GGTokenSet> tokens)

Give style tokens values for the element being built into and everything inside it, over those of the theme and of any widget asset: ui.Tokens({ { "bar-fill", GGColor::Hex(0x4C8DFFFF) } }).

void Tokens(std::span<const GGTokenSet> tokens)

The same, from a list made at run time.

auto List(const GGDataSource& source, const ListProps& props = {}, Where where = Where::current()) -> NodeHandle

Top-level items, one row each, showing every column.

auto List(const GGDataSource& source, const ListProps& props, ItemVisitor row, Where where = Where::current()) -> NodeHandle

Same, with rows built by row(item) immediately. Building other rows (scrolling a virtualised list) re-runs the enclosing function.

auto List(const GGDataSource& source, const ListProps& props, ItemRowFn row, Where where = Where::current()) -> NodeHandle

Same, with rows built by row(ui, item), which the list stores. Rows rebuild on their own.

auto Tree(const GGDataSource& source, const TreeProps& props = {}, Where where = Where::current()) -> NodeHandle

Items under their parents, with expand toggles. A row shows the item's first column.

auto Tree(const GGDataSource& source, const TreeProps& props, ItemVisitor row, Where where = Where::current()) -> NodeHandle

Same, with row content (after the toggle) from row(item), built now.

auto Tree(const GGDataSource& source, const TreeProps& props, ItemRowFn row, Where where = Where::current()) -> NodeHandle

Same, with row content from row(ui, item), which the tree stores.

auto Tiles(const GGDataSource& source, const TilesProps& props = {}, Where where = Where::current()) -> NodeHandle

A virtualised grid of equal-sized tiles (TilesProps). Tile content is tile(ui, item), stored by the view; without one a tile shows the item's first column.

auto Tiles(const GGDataSource& source, const TilesProps& props, ItemRowFn tile, Where where = Where::current()) -> NodeHandle

Same, with tile content from tile(ui, item).

auto Picker(const GGDataSource& source, const PickerProps& props, ItemID chosen, HandlerOf<ItemID> does, Where where = Where::current()) -> NodeHandle

A button showing chosen's name that opens a searchable list of the source's items. does(item) is called with the choice.

auto Picker(const GGDataSource& source, ItemID chosen, HandlerOf<ItemID> does, Where where = Where::current()) -> NodeHandle

The same, with default props.

auto Table(const GGDataSource& source, const TableProps& props = {}, Where where = Where::current()) -> NodeHandle

Items as rows with columns under a header (TableProps).

auto Table(const GGDataSource& source, const TableProps& props, ItemCellFn cell, Where where = Where::current()) -> NodeHandle

Same, with cells built by cell(ui, item, column), which the table stores. column is the source's column index.

void Use(const char* asset, std::initializer_list<GGWidgetInput> inputs, Where where = Where::current())

Build the widget asset asset from the context's library (UIContext::SetWidgets), as a component whose properties are inputs: ui.Use("StatBar", { { "Value", health } }).

void Use(const char* asset, Where where = Where::current())

The same, given nothing.

void Use(const UseProps& props, Where where = Where::current())

Same, with everything a use can say (UseProps): slot contents, a click action, its class's widget members.

void Component(ComponentFn content, Where where = Where::current())

A re-run boundary.

template<typename TProps>

void Component(void(*)(UI&, const TProps&) function, const std::type_identity_t<TProps>& properties, Where where = Where::current())

A component with explicit properties: function(ui, properties).

template<typename T>

auto State(const T& initial, Where where = Where::current()) -> GGUI::GGState<T>

State that lives with the element being built into and survives re-runs. See GGState<T>.

void Watch(const GGRevision& source, Where where = Where::current())

Re-run the component being built whenever source is bumped, and the stored content built inside it (tabs, split panes, boxes, popups) with it, down to the next dock panel, which is a page of its own.

void Key(uint64_t key)

Identify the next element by key instead of its position among elements built on the same line. Use it in loops.

void Key(std::string_view name)

By name: ui.Key(item.Name).

template<typename T>

void Key(const T& key)

By a small plain value (a handle): its bytes.

Function documentation

"Deal <class damage>{amount}</class> <img Coin/> damage"
"Press <action Game.Buy/> to buy"