Widget

Base contract for any UI tree element: lifecycle, layout, rendering, input, and styling.

Overview

Widget is the root interface for every element in the UniGUI tree hierarchy. It unifies layout measurement, positioning, visual styling, hit testing, event dispatching, frame tick updates, and procedural drawing into a single coherent contract.

It extends EventEmitter, allowing every widget in the tree to subscribe to and emit strongly typed events.

Subsystem	Core Contract	Role & Execution
Hierarchy	`parent()`, `children()`, `uiContext()`	Defines parent-child tree relations, coordinate spaces, and window context.
Layout	`measure()`, `arrange()`, `desiredSize()`, `layoutBounds()`	Two-pass layout: computes size request then commits final geometry bounds.
Visual Styling	`style()`, `styleId()`, `styleClasses()`	Inline CSS declarations, class tokens, and Theme / StylePack rules.
Input & Focus	`handle()`, `mouseCursorAt()`, `focusable()`, `focusScope()`	Dispatches mouse, pointer, and keyboard events; manages focus scopes.
Invalidation	`invalidate()`, `clearInvalidation()`, `invalidationFlags()`	Tracks dirty layout and visual bits, avoiding unnecessary reflows.
Render & Tick	`render()`, `tick()`, `dispose()`	Per-frame state updates, procedural rendering into draw list, and resource disposal.

Extending WidgetBase vs Implementing Widget

In almost all cases, custom controls should extend WidgetBase rather than implementing Widget from scratch. WidgetBase provides complete implementations for retained render caching, FLIP animations, style resolution, and invalidation bubbling.

Lifecycle & Pipeline

Each frame, the UniGUI runtime executes a structured pipeline across the widget hierarchy:

measure(LayoutContext): Calculates requested dimensions (desiredSize()) based on content and layout constraints.
arrange(RectView): Commits final positioned bounds and aligns child widgets.
handle(Event): Processes routed input, mouse, and keyboard events.
tick(FrameContext): Updates transitions, spring animations, and time-based state.
render(RenderContext): Emits drawing commands into the active draw list.
dispose(): Cleans up internal widget resources prior to removal from the tree.

Tree Hierarchy & Structure

Widgets form a directed tree structure managed by parent() and children():

parent(): Returns the owning container widget, or null if the widget is the root or unattached.
children(): Returns child widgets in traversal order.
Order semantics: Children order defines rendering order (back-to-front: first child drawn first, last child on top) and hit-testing order (front-to-back: topmost child receives pointer events first).
uiContext(): Provides access to the root window, dispatcher, font registry, and input services.

Style & Layout

UniGUI strictly decouples geometry from visual presentation:

Geometry: Governed by layoutBounds() and desiredSize(), configured through LayoutStyle.
Visual Style: Assigned via styleId(...) (referencing a StylePack rule), styleClasses(...) (CSS classes), or inline declarations via style("background: #333; radius: 8;").
Style Scope: Widgets can declare styleScope(true) to isolate local style overrides from propagating to outer trees.

Input, Focus & Interaction

Interactive state is controlled through dedicated status flags:

State Flag	Purpose & Effect
`visibility()`	`VISIBLE` participates in layout and rendering; `HIDDEN` preserves layout space but hides visual; `COLLAPSED` leaves layout entirely.
`enabled()`	Controls user interactivity. Disabled widgets ignore events and receive the `:disabled` style pseudo-class.
`hovered()`	Indicates whether the mouse cursor is currently over this widget.
`mouseCursorAt()`	Returns the cursor shape (e.g. `HAND`, `TEXT`) when hovered at local coordinates.
`focusable()`	Determines whether the widget can accept keyboard focus via Tab navigation or clicking.
`focusScope()`	Traps Tab-cycling inside this subtree (crucial for modal dialogs and popup panels).
`focusOrder()`	Explicit relative priority index for Tab ordering.

Dirty State & Invalidation

To achieve maximum frame rates, UniGUI skips layout passes and retained draw command generation for clean subtrees:

invalidate(flags): Marks dirty bits from InvalidationFlags (LAYOUT, VISUAL, RETAINED_RENDER). Layout flags bubble upward to root.
clearInvalidation(flags): Clears processed dirty flags after the pipeline pass completes.
subtreeInvalidationFlags(): Returns combined bitmask of pending dirty flags for the widget and all descendants.

Widget button = new Button("Submit");
button.on(ButtonClickEvent.TYPE, event -> {
    System.out.println("Clicked widget: " + event.target().id());
});

public class CustomCard extends WidgetBase {
    @Override
    public void measure(LayoutContext context) {
        setDesiredSize(200.0f, 100.0f);
    }

    @Override
    public void render(RenderContext context) {
        context.fillRect(layoutBounds(), 0xFF2A2A2A);
    }
}

API

Identity & Styling

Method	Description
`id(String)`	Assigns a string identifier for tree lookups and debugging.
`id()`	Returns the widget identifier, or empty string if unset.
`styleId(String)`	Sets explicit StylePack style id for Theme resolution.
`styleId()`	Returns active style id token, or empty string.
`styleClass(String)`	Sets space- or comma-separated style class tokens.
`styleClasses()`	Returns list of assigned style class identifiers.
`addStyleClass(String)`	Adds a single style class to this widget.
`removeStyleClass(String)`	Removes a single style class from this widget.

Widget::`id(String)`

Set Identifier

Assigns a string identifier for tree lookups and debugging.

Parameter	Type	Description
`id`	`String`	widget identifier string

Returns Widget: this widget for fluent configuration.

Widget::`id()`

Get Identifier

Returns the widget identifier, or empty string if unset.

Returns String: identifier string.

Widget::`styleId(String)`

Set Style ID

Sets explicit StylePack style id for Theme resolution.

Parameter	Type	Description
`styleId`	`String`	style id token from Theme

Returns Widget: this widget for fluent configuration.

Widget::`styleId()`

Get Style ID

Returns active style id token, or empty string.

Returns String: style id string.

Widget::`styleClass(String)`

Set Style Classes

Sets space- or comma-separated style class tokens.

Parameter	Type	Description
`styleClasses`	`String`	style classes string

Returns Widget: this widget for fluent configuration.

Widget::`styleClasses()`

Get Style Classes

Returns list of assigned style class identifiers.

Returns List: list of style class tokens.

Widget::`addStyleClass(String)`

Add Style Class

Adds a single style class to this widget.

Parameter	Type	Description
`styleClass`	`String`	style class to add

Returns Widget: this widget for fluent configuration.

Widget::`removeStyleClass(String)`

Remove Style Class

Removes a single style class from this widget.

Parameter	Type	Description
`styleClass`	`String`	style class to remove

Returns Widget: this widget for fluent configuration.

Layout & Geometry

Method	Description
`layoutBounds()`	Returns arranged coordinates and size in parent/root space.
`desiredSize()`	Returns size calculated during the most recent measure pass.
`measure(LayoutContext)`	Measures widget and computes desired size for layout context.
`arrange(RectView)`	Positions and dimensions widget in final arranged rectangle.

Widget::`layoutBounds()`

Layout Bounds

Returns arranged coordinates and size in parent/root space.

Returns RectView: current arranged bounds.

Widget::`desiredSize()`

Desired Size

Returns size calculated during the most recent measure pass.

Returns LayoutSize: most recently measured desired size.

Widget::`measure(LayoutContext)`

Measure

Measures widget and computes desired size for layout context.

Parameter	Type	Description
`context`	`LayoutContext`	layout constraints and sizing context

Widget::`arrange(RectView)`

Arrange

Positions and dimensions widget in final arranged rectangle.

Parameter	Type	Description
`bounds`	`RectView`	assigned layout rectangle

State & Interaction

Method	Description
`visibility()`	Returns current visibility mode (VISIBLE, HIDDEN, COLLAPSED).
`visible()`	Returns true only if visibility is VISIBLE.
`enabled()`	Returns true if widget accepts user interaction.
`hovered()`	Returns true if mouse pointer is hovering over widget bounds.
`focusable()`	Returns true if widget can receive keyboard focus.

Widget::`visibility()`

Get Visibility

Returns current visibility mode (VISIBLE, HIDDEN, COLLAPSED).

Returns Visibility: current visibility mode.

Widget::`visible()`

Is Visible

Returns true only if visibility is VISIBLE.

Returns boolean: true if VISIBLE.

Widget::`enabled()`

Is Enabled

Returns true if widget accepts user interaction.

Returns boolean: true if enabled.

Widget::`hovered()`

Is Hovered

Returns true if mouse pointer is hovering over widget bounds.

Returns boolean: true if mouse is over the widget.

Widget::`focusable()`

Is Focusable

Returns true if widget can receive keyboard focus.

Returns boolean: true if focusable.

Rendering & Caching

Method	Description
`render(RenderContext)`	Draws the widget into the current frame render context.

Widget::`render(RenderContext)`

Render

Draws the widget into the current frame render context.

Parameter	Type	Description
`context`	`RenderContext`	frame render context

Events & Lifecycle

Method	Description
`uiContext()`	Returns the runtime context hosting dispatcher, theme, and input subsystems.
`parent()`	Returns the parent widget in the UI hierarchy tree.
`children()`	Returns the list of child widgets in layout/traversal order.
`invalidationFlags()`	Returns bitmask of pending invalidation flags.
`invalidate(int)`	Marks invalidation flags (VISUAL, LAYOUT, HIERARCHY, etc.).
`clearInvalidation(int)`	Clears specified flags after processing.
`handle(Event)`	Processes routed or direct UI events.
`tick(FrameContext)`	Updates per-frame state, timers, and animations.
`dispose()`	Releases widget resources before removal from tree.

Widget::`uiContext()`

UI Context

Returns the runtime context hosting dispatcher, theme, and input subsystems.

Returns UIContext: the active UIContext, or null if detached.

Widget::`parent()`

Parent Widget

Returns the parent widget in the UI hierarchy tree.

Returns Widget: the parent widget, or null if root.

Widget::`children()`

Child Widgets

Returns the list of child widgets in layout/traversal order.

Returns List: ordered list of children.

Widget::`invalidationFlags()`

Invalidation Flags

Returns bitmask of pending invalidation flags.

Returns int: bitmask of dirty flags.

Widget::`invalidate(int)`

Invalidate

Marks invalidation flags (VISUAL, LAYOUT, HIERARCHY, etc.).

Parameter	Type	Description
`flags`	`int`	bitmask of flags from InvalidationFlags

Widget::`clearInvalidation(int)`

Clear Invalidation

Clears specified flags after processing.

Parameter	Type	Description
`flags`	`int`	bitmask of handled flags

Widget::`handle(Event)`

Handle Event

Processes routed or direct UI events.

Parameter	Type	Description
`event`	`Event`	event object

Widget::`tick(FrameContext)`

Frame Tick

Updates per-frame state, timers, and animations.

Parameter	Type	Description
`frame`	`FrameContext`	current frame context

Widget::`dispose()`

Dispose

Releases widget resources before removal from tree.

Widget

Overview

Lifecycle & Pipeline

Tree Hierarchy & Structure

Style & Layout

Input, Focus & Interaction

Dirty State & Invalidation

Subscribing to widget events

Creating a custom widget

Related links

API

Identity & Styling

Widget::id(String)

Widget::id()

Widget::styleId(String)

Widget::styleId()

Widget::styleClass(String)

Widget::styleClasses()

Widget::addStyleClass(String)

Widget::removeStyleClass(String)

Layout & Geometry

Widget::layoutBounds()

Widget::desiredSize()

Widget::measure(LayoutContext)

Widget::arrange(RectView)

State & Interaction

Widget::visibility()

Widget::visible()

Widget::enabled()

Widget::hovered()

Widget::focusable()

Rendering & Caching

Widget::render(RenderContext)

Events & Lifecycle

Widget::uiContext()

Widget::parent()

Widget::children()

Widget::invalidationFlags()

Widget::invalidate(int)

Widget::clearInvalidation(int)

Widget::handle(Event)

Widget::tick(FrameContext)

Widget::dispose()

Widget::`id(String)`

Widget::`id()`

Widget::`styleId(String)`

Widget::`styleId()`

Widget::`styleClass(String)`

Widget::`styleClasses()`

Widget::`addStyleClass(String)`

Widget::`removeStyleClass(String)`

Widget::`layoutBounds()`

Widget::`desiredSize()`

Widget::`measure(LayoutContext)`

Widget::`arrange(RectView)`

Widget::`visibility()`

Widget::`visible()`

Widget::`enabled()`

Widget::`hovered()`

Widget::`focusable()`

Widget::`render(RenderContext)`

Widget::`uiContext()`

Widget::`parent()`

Widget::`children()`

Widget::`invalidationFlags()`

Widget::`invalidate(int)`

Widget::`clearInvalidation(int)`

Widget::`handle(Event)`

Widget::`tick(FrameContext)`

Widget::`dispose()`