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.

InspectorNode

Flat snapshot of one widget for the inspector panel.

Enums

BackbufferKind

Unified backbuffer target kind requested by a widget.

BackbufferMode

How a widget’s backbuffer stores pixels.

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.

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.

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.

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.