Module widget 

Widget trait, tree traversal, and the top-level App struct.

Coordinate system

Widget bounds are expressed in parent-local first-quadrant (Y-up) coordinates. A widget at bounds.x = 10, bounds.y = 20 is drawn 10 units right and 20 units up from its parent’s bottom-left corner.

OS/browser mouse events arrive in Y-down screen coordinates. The single conversion y_up = viewport_height - y_down happens inside App::on_mouse_move / App::on_mouse_down / App::on_mouse_up. All widget code sees Y-up coordinates only.

Tree traversal

Paint: root → leaves (children painted on top of parents). Hit test: root → leaves (deepest child under cursor wins). Event dispatch: leaf → root (events bubble up; any widget can consume).

Structs

App

Owns the widget tree, handles focus, and converts OS events to Y-up coords.

BackbufferCache

A CPU bitmap owned by a widget that opts into backbuffer caching.

BackbufferSpec

Widget-owned backbuffer request. Windows use this for retained GL FBOs, while existing label/text-field CPU caches map naturally to the software variants.

BackbufferState

Retained widget backbuffer state shared by software and GL implementations.

CompositingLayer

Offscreen compositing layer requested by a widget for itself and its descendants.

InspectorEdit

A pending inspector edit: navigate to the widget at path, look up field_path via reflection, and apply new_value.

InspectorNode

Flat snapshot of one widget for the inspector panel.

InspectorOverlay

Snapshot pushed to the platform render loop so the host can draw a Chrome F12-style three-band overlay (margin + bounds + padding) around the widget the inspector is hovering.

WidgetBaseEdit

Queued mutation for a widget’s WidgetBase. The inspector pushes these; the host frame loop drains and applies via apply_widget_base_edit.

Enums

BackbufferKind

Unified backbuffer target kind requested by a widget.

BackbufferMode

How a widget’s backbuffer stores pixels.

WidgetBaseField

One field in a widget’s crate::layout_props::WidgetBase that the inspector can change at runtime.

Traits

Widget

Every visible element in the UI is a widget.

Functions

active_modal_path

Return the path to the topmost active modal subtree, ignoring normal hit-testing bounds. Modal overlays paint at app level, so their event routing must also bypass regular child clipping/window hit regions.

apply_inspector_edit

Apply a single queued inspector edit against the live widget tree. Returns true if the edit landed; false if the path was stale or the field path didn’t resolve.

apply_widget_base_edit

Apply a single queued WidgetBaseEdit against the live widget tree. Returns true when the edit landed, false if the path was stale or the widget does not expose a WidgetBase.

collect_inspector_nodes

Walk the subtree rooted at widget and collect an InspectorNode per widget in DFS paint order (root first).

current_mouse_world

Retrieve the latest world-space mouse position. Widgets doing a drag gesture that needs invariance against ancestor-layout shifts (e.g. a nested Resize inside an auto-sized Window, where the window grows/shrinks as the user drags and moves the widget’s ancestor frame) should prefer this over the widget-local pos carried in Event::Mouse*.

current_paint_clip

Current visible paint clip in root coordinates, if painting is inside a clipped subtree. Widgets can use this to avoid starting expensive work for content that traversal visits but the active clip will discard.

current_viewport

Retrieve the latest app-level viewport in logical coordinates.

dispatch_event

Dispatch event through a path (list of child indices from the root). The event bubbles leaf → root; returns Consumed if any widget consumed it.

dispatch_unconsumed_key

Give visible widgets a chance to handle a key ignored by the focused path.

find_widget_by_id

Depth-first search the subtree rooted at widget for one whose Widget::id matches id. Returns the first match in paint order, including widget itself. Used primarily by tests to locate a specific Window by its title without knowing the tree shape.

find_widget_by_id_mut

Mutable counterpart to find_widget_by_id. Required when a test needs to poke at a sub-widget’s mutable state (e.g. calling a ScrollView::set_scroll_offset) after finding it by id.

find_widget_by_type

Depth-first search for a widget by its Widget::type_name. Returns the first match in paint order. Used by tests that want to assert on a specific widget kind inside an opaque content subtree (e.g. “find the ScrollView inside this window”).

global_overlay_hit_path

Return the topmost widget whose app-level overlay contains local_pos.

hit_test_subtree

Walk the subtree rooted at widget and return the path (list of child indices) to the deepest widget that passes hit_test at local_pos.

mark_subtree_dirty

Recursively call mark_dirty on widget and every visible descendant. Used by the host frame loop after an async data source (image fetch + decode, font load, etc.) finishes outside the normal event-dispatch path that would otherwise mark widgets dirty as the event bubbles. Called explicitly at the top of the frame so the user-visible “freshly-decoded data lands in stale FBO contents” bug never opens a one-frame race window.

paint_global_overlays

Paint app-level overlays after the whole tree has rendered.

paint_subtree

Paint widget and all its descendants. The caller must ensure ctx is already translated so that (0,0) maps to widget’s bottom-left corner.

reflect_fields

Walk a reflected struct’s fields and produce (name, display) pairs suitable for the inspector’s property pane. Public so callers can build the same typed dump for ad-hoc reflectable values (e.g. a debug hover inspector outside the widget tree).

set_current_mouse_world

Record the current mouse cursor position in app-level (world / Y-up logical) coordinates. Called by App’s mouse entry points.

set_current_viewport

Record the current app-level viewport in logical Y-up coordinates.

walk_path_mut

Walk the widget tree from root along path and return the deepest reachable widget as a mutable reference. Returns None if the path indexes past the available children at any level — useful when the path is stale (e.g. the tree shape changed since the inspector snapshot).