Struct App 

pub struct App { /* private fields */ }

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

Create with App::new, call App::layout every frame before App::paint, and feed OS events through the on_* methods.

Implementations

impl App

pub fn new(root: Box<dyn Widget>) -> Self

Create a new App with root as the root widget.

pub fn root(&self) -> &dyn Widget

Access the root widget — used by tests and inspectors that need to introspect the laid-out tree without re-routing events through the full dispatch machinery. Pair with find_widget_by_id to locate a specific widget by its Widget::id() (e.g. a Window’s title).

pub fn root_mut(&mut self) -> &mut dyn Widget

Mutable counterpart to [root]. Required when a test wants to drive a specific sub-widget directly (e.g. reading ScrollView scroll offset) after the App has routed an event.

pub fn focused_widget_type_name(&self) -> Option<&'static str>

Return the type name of the currently focused widget, if any.

pub fn set_global_key_handler( &mut self, handler: impl FnMut(Key, Modifiers) -> bool + 'static, )

Register a legacy global key handler invoked only after the widget tree has ignored the key. Prefer widget-owned key handling for new behavior.

Example

app.set_global_key_handler(|key, mods| {
    if mods.ctrl && mods.shift && key == Key::O {
        organize_windows();
        return true;
    }
    false
});

pub fn layout(&mut self, viewport: Size)

Lay out the widget tree to fill viewport. viewport is in physical pixels (e.g. window.inner_size() on native, canvas.width/height on wasm); this method divides by the current device scale factor so the widget tree lays out in logical (device-independent) units. Call once per frame before paint.

pub fn paint(&mut self, ctx: &mut dyn DrawCtx)

Paint the entire widget tree into ctx. Call after layout.

Applies a ctx.scale(dps, dps) transform up-front so the whole tree — widget dimensions, font sizes, margins — is rendered at physical pixel density on HiDPI screens without any widget having to know about DPI.

Also clears the immediate draw flag so widgets can re-request it during this paint if they need another frame; hosts read [wants_draw] after paint returns to decide whether to schedule continuous draws.

pub fn wants_draw(&self) -> bool

After a paint pass, returns true if any widget requested another frame (e.g. an in-progress hover animation). Hosts should use this to set their event-loop control flow to continuous polling while it’s true.

Combines the visibility-gated tree-walk signal (Widget::needs_draw) with the immediate draw request flag (crate::animation::wants_draw). Widgets call request_draw for ordinary visual invalidation; scheduled draw needs such as cursor blink should use needs_draw / next_draw_deadline so hidden subtrees do not keep the loop awake.

pub fn next_draw_deadline(&self) -> Option<Instant>

Earliest scheduled draw deadline across the visible widget tree. Hosts translate Some(t) into ControlFlow::WaitUntil(t) so that e.g. a text field’s cursor blink wakes the loop exactly at the flip boundary. Invisible subtrees contribute nothing.

pub fn on_mouse_move(&mut self, screen_x: f64, screen_y: f64)

Mouse cursor moved. screen_y is Y-down physical pixels.

pub fn on_mouse_down( &mut self, screen_x: f64, screen_y: f64, button: MouseButton, mods: Modifiers, )

Mouse button pressed. screen_y is Y-down physical pixels.

pub fn on_mouse_up( &mut self, screen_x: f64, screen_y: f64, button: MouseButton, mods: Modifiers, )

Mouse button released. screen_y is Y-down.

pub fn on_key_down(&mut self, key: Key, mods: Modifiers)

Key pressed. Delivered to the focused widget first, then to the visible widget tree as an unconsumed key if focus ignores it.

pub fn on_key_up(&mut self, key: Key, mods: Modifiers)

Key released. Delivered to the focused widget.

pub fn on_mouse_wheel(&mut self, screen_x: f64, screen_y: f64, delta_y: f64)

Mouse wheel scrolled. screen_y is Y-down. delta_y positive = scroll up. delta_x positive = content moves right.

pub fn on_mouse_wheel_xy( &mut self, screen_x: f64, screen_y: f64, delta_x: f64, delta_y: f64, )

Mouse wheel with an explicit horizontal component (trackpad pan, shift+wheel via the platform harness).

pub fn on_mouse_wheel_xy_mods( &mut self, screen_x: f64, screen_y: f64, delta_x: f64, delta_y: f64, modifiers: Modifiers, )

Mouse wheel with explicit horizontal component and modifier state.

pub fn collect_inspector_nodes(&self) -> Vec<InspectorNode>

Snapshot the entire widget tree for the inspector.

pub fn has_captured_pointer(&self) -> bool

true while a widget is actively capturing the pointer — i.e. the user is mid-drag (a window edge, slider thumb, scrollbar, etc.). Used by the demo harness to throttle expensive per-frame snapshots (the inspector tree walk) during interactions; the snapshot can safely defer until the user releases without changing the visible outcome (the underlying widget tree topology doesn’t change during a drag, only the widgets’ bounds).

pub fn dump_tree_json(&self) -> String

Serialize the widget tree — types, bounds, depth, properties — as JSON.

Produces a flat array of nodes in paint-order DFS. Suitable for writing to a file and diffing between runs to verify layout stability. Used by the demo harness’s debug hotkey.

pub fn has_focus(&self) -> bool

Returns true if any widget currently holds keyboard focus. Used by the render loop to schedule cursor-blink repaints.

pub fn on_mouse_leave(&mut self)

Call when the cursor leaves the window to clear hover state.

pub fn on_touch_start( &mut self, device: TouchDeviceId, id: TouchId, screen_x: f64, screen_y: f64, force: Option<f32>, )

pub fn on_touch_move( &mut self, device: TouchDeviceId, id: TouchId, screen_x: f64, screen_y: f64, force: Option<f32>, )

pub fn on_touch_end(&mut self, device: TouchDeviceId, id: TouchId)

pub fn on_touch_cancel(&mut self, device: TouchDeviceId, id: TouchId)

pub fn active_touch_count(&self) -> usize

Current number of fingers down across all devices. Used by widgets that want to know the gesture has begun before the first frame has had a chance to produce a delta (where current_multi_touch() may still be None).