GG-UI — Core

Authoring

// The function is the row: it opens the row's scope.
void HealthRow(UI& ui, EntityHandle entity)
{
    if (auto row = ui.Row({ .Gap = 8, .Align = GGAlign::Center }))
    {
        ui.Label("Health");
        ui.Slider({ .Min = 0, .Max = 100, .Grow = 1 }, Field(entity, &CHealth::Value));
        ui.Button("Reset", [=] { ResetHealth(entity); });
    }
}

// Lambdas describe content, and how each piece of data is laid out.
void Inspector(UI& ui, Selection& selection)
{
    if (auto panel = ui.Panel("Details"))
    {
        ui.List(selection.Entities(), { .RowHeight = 22 }, [&](EntityHandle entity)
        {
            ui.Key(entity);                        // identity survives reordering
            ui.Row({ .Gap = 8 }, [&] { ui.Label(NameOf(entity)); ui.Badge(TypeOf(entity)); });
        });
    }
}

using namespace GGUI::StyleKeywords;

if (auto bar = ui.Row({ .Width = Grow, .Height = 32, .Gap = 6, .Padding = 8, .Align = Center }))
{
    ui.Label("Layers", "muted");            // a class where the props would be
    ui.Spacer();
    ui.Button("Add", "primary", [] { AddLayer(); });
}

ui.Stack({ .Class = "slot", .Priority = 1 }, [item](UI& ui)
{
    ui.Image(IconOf(item));
    ui.Label(CountOf(item));
});

How UI Updates

Two mechanisms, each with one job. Using the wrong one works and is merely slow.

void Inspector(UI& ui, Selection& selection)
{
    ui.Watch(selection);                         // structure: re-run when the selection changes
    if (selection.Empty()) { ui.Label("Nothing selected", "muted"); return; }
    for (const FieldInfo& field : FieldsOf(selection.Type()))
    {
        ui.Key(field.ID);
        PropertyRow(ui, selection, field);       // values inside are bound, not rebuilt
    }
}

• Identity is the source line plus ui.Key(x) or, without one, the count of elements that line has built under the parent. It keeps focus, scroll position, and local state on the right node across a re-run.
• Local state (ui.State<T>(initial)) lives with the node, not the function.
• A watch covers what is inside. Stored content (tabs, split panes, kept boxes, popups) follows what the components around it watch, so one ui.Watch at the top of a panel keeps all of it current. A dock panel is a page of its own and doesn't follow the dock's watches. A component re-run by its own state still skips stored content whose captures are unchanged. A part that changes more often than its panel watches its own revision.
• Idle is free. A component re-runs only when something it, or something around it, watches changed; a binding is re-read only when its source did.
• Deterministic mode: re-runs and binding reads happen in node order at a defined point of the fixed step.

Fields and Editors

Details views are generated from reflection. The core doesn't see the engine's reflection: the integration layer hands it a FieldSource (whose data, which type, and a function that enumerates fields as FieldInfo).

ui.Fields(source);                                           // a keyed row per field: name and editor
ui.Fields(source, [&](const FieldInfo& field) { ... });      // rows laid out by hand
ui.Editor(source, field);                                    // the widget registered for field.Type

• EditorRegistry maps a field type to its editor, with per-field overrides. UIHost::Editors() holds the built-in ones (AddDefaults) and whatever a game or plugin registers.
• A type with no editor shows its nested fields. One with neither shows a placeholder and is counted in BuildStats::MissingEditors.
• Editors never write data. They tell the source (FieldSource::SetValue with the edit phase, SetText), and show what the source reports afterwards.
• Built-in editors: number (or slider), toggle, text, vector, colour, item picker.

The engine's entities (EntityFields.h):

EntityFields fields(world, entity);   // one category per component, a field per reflected field
ui.Properties(fields);

• Values are read through the host's binding reader at the world's published read frame. A field edits in its own type (Fixed32 stays Fixed32).
• An edit is a FieldEdit the Brain applies. In the editor it goes through the edit sink: Begin to Commit is one undo step, and Cancel puts the starting value back. With no sink it is submitted to the world.
• A binding target is the entity's handle with the world's slot in its spare top byte, so a copy of the source stays valid; a world's slot is freed at shutdown and its targets then read as gone.
• The engine's flags component isn't listed.

Not yet: hints on engine fields (TNX_FIELD_HINTS, below); asset references as item pickers; Constructs' own fields.

Hints::Min(0), Hints::Max(100), Hints::Decimals(1), Hints::Units("m/s")      // on a field
const int places = field.Get(Hints::Decimals, 2);                            // in an editor
namespace WeaponHints { inline constexpr GGHint<float> Recoil{ "Recoil", "How far a shot kicks, in degrees" }; }

Data Sources

Presentation widgets take a GGDataSource and neither own nor copy the data. The source is a struct of functions the integration layer fills in (children, parent, columns, cells) plus a Structure revision bumped when items come, go, or move.

Two independent choices:

Selection is an ItemSet keyed by ItemID, so every view of the same items shares it.

ItemSet selection;
ui.List(source, { .RowHeight = 22, .Selected = &selection, .Select = GGSelect::Many },
        [=](UI& ui, ItemID item) { EntityRow(ui, item); });
ui.Tree(source, { .Toggled = &open, .RowHeight = 22, .Selected = &selection, .Sort = { .Column = 0 } },
        [=](UI& ui, ItemID item) { EntityRow(ui, item); });

ui.Tiles(assets, { .TileWidth = 96, .TileHeight = 112, .Gap = 8, .Selected = &selection },
         [=](UI& ui, ItemID item) { ui.Image(ThumbOf(item)); ui.Label(NameOf(item)); });

GGSort sort;
ui.Table(source, { .RowHeight = 22,
                   .Columns   = { { .Column = 0 }, { .Column = 2, .Width = 90, .bResizable = false } },
                   .Selected  = &selection,
                   .SortBy    = &sort });
ui.Table(source, props, [=](UI& ui, ItemID item, uint32_t column) { ... });   // cells laid out by hand

ui.Properties(selection, { .RowHeight = 22, .Filter = filterText, .Toggled = &closed });
ui.Properties({ first, second }, props);                     // several sources

Panels

UIPanels.h: what a tool window is assembled from.

ui.MenuBar([&] { ui.SubMenu("File", [=](UI& ui) { ui.MenuItem(OpenScene); }); });
ui.Toolbar([&] { ui.ToolButton(moveIcon, MoveTool, { .bChecked = bMoving }); ui.Separator(); });
ui.Split({ .Direction = GGSplit::Columns, .Ratio = &ratio, .Min = 120 },
         [=](UI& ui) { Outliner(ui); },
         [=](UI& ui) { ui.Tabs({ .bClosable = true }, tab, [&] { ui.Tab("Scene", [=](UI& ui) { ... }); }); });

• Split: each pane grows by a share of the space the bar leaves, so layout does the arithmetic and a resize keeps proportions without running anything. Dragging the bar writes the shares.
• Tabs: only the chosen tab's content is built. Ctrl+Tab cycles from anywhere inside. OnClose adds a close button; the owner removes the tab.
• Menu bar: a row of ui.SubMenus that open below their title. While one is open, the pointer on another title opens that one instead; Left and Right move between them (Right from an item without a submenu).
• Toolbar: a row of tool buttons.
• What doesn't fit: a toolbar or tab strip too narrow for its items shows those that fit whole and a >> button with a menu: a toolbar's lists the hidden buttons, a tab strip's lists every tab. A tab strip keeps the chosen tab shown by starting further along; tabs before the first shown aren't built. Hidden items aren't reached by Tab, only through the menu. Which items fit is worked out after layout from the widths they were laid out at, and the component around the strip is built again when that changes (so on a resize, not every frame). The dock's tab groups work the same way.
• A menu item or tool button given an action takes its title, tooltip, and chord from the action and runs the nearest command for it (input actions).

The workbench (--ui-workbench) exercises all of it over a made-up scene.

Not yet: a hidden item's place in the menu for anything but a tool button, separator, or tab (other content in a toolbar is clipped and not listed).

Graph

UIGraph.h. Nodes joined by wires, panned and zoomed: node scripts, and later material and animation graphs.

ui.Graph(view, { .OnMove = moved, .OnConnect = connect, .OnDisconnect = cut, .OnDelete = remove, .Menu = addNodeMenu }, [&]
{
    for (const Node& node : nodes)
    {
        ui.Key(node.ID);
        ui.GraphNode(node.ID, { .X = node.X, .Y = node.Y, .Title = node.Title }, [&]
        {
            if (auto row = ui.Row({ .Gap = 6, .Align = GGAlign::Center }))
            {
                ui.Pin(node.In, { .Side = GGPinSide::In, .Color = floatColour });
                ui.Label("Value");
            }
        });
    }
    for (const Link& link : links)
        ui.GraphLink(link.From, link.To);
});

• Nodes are UI. Anything goes inside a node; a pin is an element in it. Wires are drawn from where layout put the pins.
• The owner keeps the data. The graph reports a gesture once, at its end (a move at release, a wire when it is dropped), so each is one undo step in the owner's history. CanConnect can refuse a wire while it hovers.
• The view is the owner's (GGGraphView): pan, zoom, selection, and where the menu was opened. The graph writes it as the user acts, so each open graph keeps its own.
• Gestures: a box on the background selects (Shift adds, Ctrl removes); a press on a node selects it and a drag moves the selection, the pressed node landing on the grid; a drag from a pin draws a wire; Alt+click on a pin cuts its wires; Ctrl+drag from a pin picks its wires up, to drop on another pin or cut on empty space. Right or middle drag pans, the wheel zooms about the pointer, a right click opens Menu.
• Keys are actions (GGGraphKeys): delete, duplicate, copy, cut, paste at the pointer, select all, frame (Home or F), deselect.
• Cost: the nodes are in an Overflow::Pan box, so pan and zoom are paint-only; the GPU moves and scales them. Grid and wires are redrawn into canvases after layout, in the document's own units, so lines stay a pixel wide at any zoom.

Not yet: comments and reroute nodes, a minimap, dropping a wire on empty space to open the menu, text sharp when zoomed in past 1 (the default MaxZoom: glyphs are rasterised once).

Docking

UIDock.h. Panels the user arranges into splits and tab groups by dragging tabs. One GGDockSpace covers every window; the host owns it (UIHost::Dock()).

inline constexpr GGPanel Outliner{ "Editor.Outliner", "Outliner" };

dock.Panel(Outliner, [](UI& ui) { OutlinerPanel(ui); });
dock.SetDefault(GGDock::Columns({
    { 0.25f, GGDock::Tabs({ Outliner }) },
    { 0.75f, GGDock::Tabs({ Viewport, Log }) } }));

ui.Dock(dock);   // in the window's document

Dragging a tab

The same targets work in another dock window. Floating doesn't depend on there being free desktop to drop on, so it works with a maximised window.

A group that loses its last panel collapses. A floating window that loses its last panel closes.

Maximize(panel) shows that panel's tab group alone in its window, until Maximize(0) or a layout is applied. It isn't saved. Pointed() is the front panel of the group the pointer was last over, for a command about "the panel under the pointer".

Layouts

• Named: SaveAs(name), Use(name), Layouts(), Reset().
• Default is the layout set in code. It is always listed and can't be overwritten.
• Save() / Load() write every layout as hand-editable text. The host keeps it in Layout.ini (UIHost::SetLayoutFile) and writes once a change has settled.
• Switching layouts moves and resizes open floating windows to the layout's saved values.
• Panels are referenced by name. An unknown name is kept and shown once that panel is registered.

Floating windows

• Always real OS windows, each with its own document. The host opens and closes them to match FloatingWindows() (UIHost::SetDockWindowSink).
• Closing one from the OS closes every panel in it.
• Each has an Above toggle: stay above the main window or not. PanelProps::bAbove sets the initial value. Implemented with OS window ownership, so it never sits above other applications.
• Moving a panel between windows rebuilds its content. ui.State inside the panel does not survive the move; keep durable state outside it.

Threading

GGDockSpace is not thread-safe. Dock documents are updated one at a time (every floating document follows the main one), and the host reconciles windows inside the main document's update. From other threads use UIHost::FloatPanel / ClosePanel.

Limits

• Wayland: no window positions, so a tab can't be dragged between windows there. Tear-off works; the compositor places the window.
• Mixed-DPI monitors: window positions assume one display scale.
• The drop highlight shows the edge strip, not the half the panel will take. Nothing shows that a drop on the middle will float.
• A reopened panel goes to the main window's first tab group, not where it was.
• More tabs than fit are clipped.
• No keyboard control of docking.

Dialogs, Notices, and Files

UIPopups.h, UINotices.h.

ui.Dialog(open, { .Title = "Rename" }, [=](UI& ui) { ... });
ui.Ask(open, { .Title = "Quit", .Text = "Save first?", .Choices = { "Save", "Discard", "Cancel" } },
       [](int choice) { ... });

auto notices = ui.Notices();     // handles: take them while building, use them in handlers
auto files   = ui.Files();
ui.Button("Open", [=] { files.Open({ .Title = "Open scene" }, [](std::span<const std::string> paths) { ... }); });

• Dialog: a box centred over a backdrop that blocks the pointer. Open while its state is true. Focus goes to its first control and stays inside. Escape or its close button closes it; a press outside doesn't. Losing application focus closes menus but not dialogs.
• Ask: a dialog with a question and a button per choice. The chosen index goes to the handler; closing without choosing reports nothing. The question can say what it is about, as any text can: .Text = GGText("Editor.Delete", { { "name", name } }). It keeps its own copy, so the arguments needn't outlive the call (GGKeptText).
• Handles, not calls. A handler has no ui, so ui.Notices() and ui.Files() return handles to capture, the way a ui.State is captured.
• Notice: notices.Show(text, { .Seconds, .Kind }). A line in a corner box for a while. Takes no input. Classes: notices, notice, notice-success, notice-warning, notice-error.
• File dialog: the platform's. The result arrives later, at an update of the document that asked: the paths, or none if cancelled. A document destroyed first is told nothing.
• One service of each per host, shared by every document and by non-UI code from any thread (UIHost::Notices(), UIHost::Files()). They belong to the host, not a world: a window isn't a world's. UIHost::SetNoticeWindow picks the window that shows notices.

Not yet: a dialog in its own OS window; dismissible notices or notices with buttons; notices in the active window rather than a preset one.

Documents Inside Documents

UIDocument.h.

GGDocument Preview;   // kept by whoever shows it

ui.Document(Preview, { .Width = 2532, .Height = 1170, .Dpi = 3.0f, .Widgets = &previews, .Strings = french },
    [asset](UI& ui) { ui.Use(asset); });

const NodeHandle under = Preview.Hit(event.LocalX, event.LocalY);   // in its box's units
const GGRect drawn     = Preview.Bounds(under);

• A screen of its own. The content is laid out on a screen of Width by Height pixels at Dpi pixels to a unit: 2532 by 1170 at 3 is 844 by 390 units. Swapping the two is turning the screen round. With no size it fills its box at one unit to one, for an area whose size the parent sets.
• Drawn in its box, scaled to fit and centred, clipped to the box, in the parent's draw order: it is the box's primitives, under the parent's clips and transforms, so a pan space zooms it and a scroll moves it. Its own clips are kept inside the box. Its text is shaped for the pixels it is drawn at.
• Its own assets and text, or the parent's (Widgets, Strings unset). Styles, images, text measurement, actions, and editors are the parent's. SafeArea is what its ui.SafeArea keeps clear.
• Updated with the parent: built, bound, laid out, timed, and published in the parent's update, on its thread. A change inside repaints only the box.
• The handle keeps the document and what it built, and answers for the parent: Hit (what is under a point), Bounds (where a node is drawn), both in units from the box's corner. Not shown, it keeps what it built; destroyed, it leaves the parent. Either may go first.

Inside a zoomed box (a pan space) it is laid out and asked in its box's own units, as anywhere else, and its text is shaped for the size it is drawn at.

Not yet: input to the document inside (hover and press states shown in it); a box sized by its content.

From API to Pixels

Screen UI

1. Widget functions run and produce nodes.
2. Layout produces a rect per node.
3. Paint turns each node into a few primitives (rounded rects, glyph quads, images) in tree order.
4. Only dirty ranges are uploaded; one instanced draw per surface renders them.
5. When a bound value changes, that primitive's parameter is patched. No function runs and nothing is laid out.

World UI (templates, drawn in batches by the GPU)

1. The widget function runs once, against a placeholder entity.
2. Layout and paint produce a fixed primitive list in local space, with a parameter slot per binding.
3. Each frame the GPU evaluates the bindings from slab fields for every visible entity carrying the template and writes the primitives into the buffer screen UI uses. CPU cost doesn't grow with entity count.

void Nameplate(UI& ui, TemplateEntity e)
{
    const auto health = Field(&CHealth::Value) / Field(&CHealth::Max);
    if (auto plate = ui.Column({ .Class = "nameplate" }))
    {
        ui.Visible(e.Bind(health < 1));                 // an `if` on entity data becomes a visibility binding
        ui.Text(e.Text(&CName::Run));
        ui.Progress({ .Class = "health" }, e.Bind(health));
    }
}

Storage

Chunked SoA storage per UIContext, rows grouped by how often they change. See Memory Model.

• Chunk: 64 slots, so each bitplane is one word per chunk.
• Handles: a stable index plus a generation.
• Rows: structure (parent, children, siblings, depth, type, key); layout inputs; paint inputs; computed values; per-widget-kind state pools.
• Sparse data (bindings, state, watches, reactions) lives in pools linked into a short chain per node, so lookups cost the node's chain length, not the tree's size.

Mutation

Structural change from other threads goes through one lock-free multi-producer queue, applied at the start of the UI update (UIContext::Apply): destroy, append, insert-before, remove, and invoke (a function run in the update, with an optional pooled buffer).

One listener hears every change to the tree, whoever makes it: the builder, the queue, or a queued function. The context is that listener. It resets a new node's rows, releases everything stored for a destroyed node, and queues a changed child list for layout. No path can forget.

Layout

A flex-style box model, evaluated per depth over what changed.

• Driven by a queue. Everything that can affect layout queues its node. With an empty queue UpdateLayout touches nothing.
• Four passes: measure widths (deepest first), arrange widths (shallowest first), measure heights, arrange heights. A height can depend on a width (wrapping text), so widths are final first.
• How far a change travels: a queued node is measured and its parent re-arranges its children. The parent is itself re-measured only if the node's wanted size changed and the parent fits its content on that axis.
• Rects are relative to the parent, so a container that moves or scrolls rewrites one rect.
• Snapping happens on read, edge by edge, for the surface's scale: boxes that share an edge still share it. A scale change needs no box layout; text is re-measured.
• Text is measured through TextMeasurer and shaped once: the node keeps the run for paint. The built-in measurer (8 × 16 per character) needs no font and is what headless tests use.
• Free space: grow items share by weight; one clamped by min or max is settled and the rest redistributed. What nobody takes is what Justify distributes. A grow item wants no space of its own: in a box that fits its content it is as big as its siblings make it.
• Components are boxes round what they build. On an axis where what a component builds grows, the component grows too, and still wants its content's size, so a growing bar in a component (or a widget asset) fills the space the component is given. A button given content is a box round it, sized like a row.
• Overflow: visible, clip, scroll, or pan. The scroll offset is paint-only, so scrolling lays nothing out. A pan box has no bars or limits and also zooms (UIContext::SetPan): its content is drawn moved and scaled about its corner, hit-testing follows, and a handler is told where it was hit in its node's own units.
• Baselines: text's own, or a container's first text. GGAlign::Baseline aligns a row on them.
• Numeric type: written once and instantiated for float and Fixed32.

ui.Row({ .Gap = 4, .bWrap = true });                                   // wraps onto further lines
ui.Grid({ .Columns = 8, .Gap = 2 });                                   // eight equal columns
ui.Grid({ .Columns = { GGSize::Fixed(120), GGSize::Fit(), GGSize::Grow() } });
ui.Place({ .Anchor = GGAnchor::TopRight, .X = -4, .Y = 4 }, [&] { Badge(ui); });   // overlay
ui.Stack({ .Class = "dragged", .ZOrder = 1 }, [&] { ... });             // in front of its siblings

Not yet: wrapping columns; grid cells that span; a shared baseline on a wrapped line; layers across parents (which is what popups are for).

Publish

After layout the computed rows and paint output are published. Sentinel hit-tests the latest snapshot; Encoder draws it. A snapshot never points into rows the UI update is writing.

• Shape: a row per node at the node's slot, linked to parent, first child, and next sibling. Find(handle) is one lookup; Walk() visits in draw order.
• Rows hold unscrolled positions. Each scrolling box's offset is stored beside them (GGSnapshot::Spaces), so a scroll writes that and no row. GGSnapshot::Placed gives a node's on-screen rect.
• Snapshots share unchanged rows. Rows are in chunks of 64 aligned with the document's; a chunk is copied when first written. Four snapshots cost about what one does.
• A publish writes what changed. Anything that changes what a snapshot says about a node calls MarkPublish. Children are visited only when what the node passes down changed (origin, clip, visibility, opacity, disabled, text colour).
• Reach is the bounds of everything a node and its subtree draw. Hit-testing and painting skip subtrees by it, so both cost what is on the surface, not what is in the document.
• Publishing never waits. Four snapshots serve up to two readers. A reader acquires the latest and holds it; the writer fills one nobody holds. No locks.
• Hit-testing is a query on a snapshot in document space, respecting clip, scroll, layers, and visibility.
• Verified in tests. UIContext::VerifySnapshot recomputes every row from scratch and compares. Testbed turns it on for every publish, so a change that forgets MarkPublish fails whatever test exercises it.

Accessibility

Role, name, description, and state are rows written by the same widget functions that build the visuals: a Button is a button to a screen reader with no extra code. Authors add what a widget can't know with ui.Accessible. Text and buttons default to their text as a name. Published with the snapshot, so a bridge can read from another thread. The platform bridge is not built.

Determinism

The same inputs give bit-identical layout. UIContext::LayoutChecksum hashes every node's computed values in tree order. The test lays one document out three ways per numeric type (fresh, fresh again, and after a history of other content and sizes) and requires equal checksums. The Fixed32 checksum is recorded in the test, so another machine or compiler that differs fails it.

Foundation Layer

GGUI can't include engine headers, so what it shares with the engine lives in a foundation library both depend on: chunk allocation, handles, bitplanes, the lock-free ring, string IDs, math, and Fixed32 with its trig. SimFloat (the engine's float / Fixed32 choice) stays in the engine; GGUI instantiates layout for the fixed-point type directly.

Open Questions

• Component functions run on whichever thread updates their document, and two documents' may run at once. Touching engine state from inside one needs a clear rule and a debug check (reading the published frame is fine; anything else is a queued command).
• Designated-initialiser props can't express "unset" for every field without a wrapper.
• How a custom-drawn widget (node graph canvas, curve editor) emits primitives.