GG-UI — Styling and Widgets

Widget Definitions

A widget is a struct. Its members are per-node state; its methods are the hooks it wants. Hooks are detected at compile time, the way a Construct gets a tick by having the method: a missing hook costs nothing, and one with the right name and the wrong signature is a compile error that states the expected signature.

struct LogView
{
    static constexpr std::string_view Name = "LogView";

    GGLineSource Source;                   // state: plain typed members
    uint64_t     Top = 0;

    using Host = WidgetHost<LogView>;

    void Woken(Host& host);
    void Sized(Host& host);
    bool Key(Host& host, const InputEvent& input);         // true: handled
    bool Wheel(Host& host, float notches);
    void Publish(const Host& host, GGSnapshot& out) const;
    bool ScrollBar(const Host& host, float& scrollY, float& contentHeight) const;
};

WidgetHost<T> is what a hook is handed: the widget's node plus the part of the document a widget may use. It is deliberately not the UIContext.

• Its node: rect, layout inputs, class, state bits; InvalidatePaint, InvalidateLayout, Rerun(component).
• Watch(revision), WakeNextUpdate(), WakeAfter(seconds): the only ways it runs without an event. A widget nobody woke does no work, so an idle document is idle whatever widgets it holds.
• Text measurement, setting text and classes on nodes it built, the clipboard, Report (run the author's handler for a reaction), Find<T>(node).
• Opt-in services. EditsValue = true adds the value service (Value, BeginEdit, ChangeEdit, CommitEdit, CancelEdit, and the same in the value's own type). TakesText = true adds the text service (SetTextFocus, TextCaret, AskForPaste). On any other widget's host those calls don't compile.

if (auto box = ui.Widget<LogView>(where))      // created on the first build, found again after
{
    box.Layout({ .Width = props.Width, .Height = props.Height, .Overflow = Overflow::Clip });
    box.OnPress([](LogView& view, LogView::Host& host, const PointerEvent& event) { view.Pressed(host, event); });
    box->Configure(box.Host(), lines, props);
}

• The core knows no widget by name. It holds one type-erased WidgetDef per kind, generated from the struct. A test fails if UIContext.h names a widget.
• Built-in widgets use only what an outside widget could use. ui.Widget<T> and WidgetScope<T> are public, as are the part helpers (WidgetPart, WidgetTextPart, WidgetValue, WidgetAccessName).
• State is pooled per kind per document, 32 to a chunk, and never moves.
• What stays in the core: popups (child documents), the value-edit phases (a service), focus, scrolling boxes, hover and press.

Not built: a Measure(host, width) → height hook asked inside layout's height pass. Nothing needs it yet; widgets whose content depends on their size are told (Sized) and laid out again in the same update. It is the right tool for a widget whose own height depends on its width with no child to carry it.

Known gap: a widget that moves because something above it moved isn't told, so the IME caret position can be stale until the next edit.

Tokens

A token is a name with a value: a colour, a length, a number.

• Styles refer to tokens rather than repeat values: a button's fill is surface-raised, not #3B4252.
• A theme is a set of token values. Changing them repaints; nothing re-runs.
• A token can alias another.
• styles.Token(name, value) in code; an @tokens { } block in a sheet.
• Tokens can be set for part of a document: ui.Tokens({ { "bar-fill", colour } }) in an element's content gives them to that element and everything inside it (ScopesScopes

).

Not yet: tokens derived by arithmetic (a colour lightened from another); a font as a token; a theme as a named object to switch between.

Rules

A rule is a selector and the properties it sets.

button                      every element of class "button"
button primary              ...that also has class "primary"
button:hover                ...while hovered
button:hover:checked        ...in both states
slider::knob                the knob part of a slider
textfield::placeholder      the placeholder part of a text field

styles.Rule("button:hover", { .Fill = Token("surface-hover") });     // sets only what it names
styles.Token("accent", GGColor::Hex(0x88C0D0FF));
styles.Set("demo-glass", { .Fill = ..., .Radius = 12.0f });          // a whole style: every paint property

Box Rendering

• Gradient: fill to a second colour at an angle, mixed in linear light. The primitive stayed 48 bytes: a solid box has no use for its texture region, so the second colour and direction live there.
• Outline: one more box primitive outside the node's own. Nothing is laid out differently for it.
• Shadow: a primitive kind under the box: the same rounded rect, offset, with its edge fading over the blur. Not a Gaussian; cheap, single pass, and close enough at UI sizes.

The fragment shader and the reference rasterizer do the same arithmetic, and the GPU-against-reference test covers all three.

Not yet: more than two gradient stops; radial gradients; several or inset shadows. A node's paint bounds don't include its shadow or outline, so one that extends past its clip is cut off. Popups have no shadow for the same reason: a popup's document is the size of its box.

Transitions

button { transition: fill 80ms, border 80ms, shadow 200ms ease-in-out; }

• Per property group (fill, border, text, accent, knob, radius, outline, shadow): a duration and an easing (ease-out by default, ease-in-out, linear). The duration used is the target style's.
• Paint properties only. A node mid-transition repaints each frame; nothing is built or laid out. When the last one arrives the document is idle again.
• Only nodes whose style names a duration are tracked. Reversed halfway, a transition continues from where it had got to.
• The snapshot carries the interpolated style (GGSnapshot::Looks).
• Time is the document's clock (AdvanceTime). A sim-bound document advanced by simulation steps transitions identically every time.
• Not animated: an element's first appearance, and the styles themselves changing (a theme applies at once).
• A colour fading from or to transparent keeps its hue, so nothing passes through black.
• Reduced motion: UIHost::SetReducedMotion makes every change immediate. The engine sets it from the OS preference at start (Windows only so far); the console's ui.reduced_motion changes it.

Not yet: opacity, spacing, and per-property delays.

Style Sheets

StyleTable::SetSheet(name, text, &error) parses a sheet: an @tokens { } block and rules.

• All or nothing. A sheet is parsed completely before any of it is applied. One that fails changes nothing, and GGSheetError gives the line and reason ("no property is called colour").
• Setting a name again replaces that sheet and keeps its layer position; RemoveSheet removes it.
• A token's value is the topmost sheet's, so a theme is a sheet of tokens.

GGUI::StyleTable styles;
UITheme::Apply(styles);                  // the built-in sheet, with the theme over it
styles.SetSheet("game", ...);            // the game's own, over both
UITheme::Watch(host, styles);            // development: hot reload the theme's file

Inspector

The panel under the inspector's tree has three tabs:

• Node: source line, rect, size rules (editable live), state, reactions, bindings, accessible name.
• Style: every property a rule sets for the selected node in its current state, as a sheet would write it, with the token, the rule, and the sheet: fill #4C566A surface-hover · button:hover · built-in (StyleTable::Explain).
• Tokens: every token, editable. A typed value overrides the token in every document using those styles (StyleTable::OverrideToken). The table itself isn't changed, nothing is saved, and Reset or closing the inspector undoes it.

Overlays: repaints, layout, focus, pointer blocking, and transitions.

Not yet: a colour picker for tokens; writing changes back to the sheet's file; inherited text properties aren't listed under an element; the hint list.

Decisions