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 set_global_key_handler( &mut self, handler: impl FnMut(Key, Modifiers) -> bool + 'static, )

Register a global key handler invoked before the focused widget receives the key. Return true to consume the event (suppress focused dispatch).

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 animation tick flag so widgets can re-request it during this paint if they need another frame; hosts read [wants_animation_tick] after paint returns to decide whether to schedule continuous redraws.

pub fn wants_animation_tick(&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 tree-walk signal — Widget::needs_paint, which is visibility-gated: hidden subtrees cannot contribute — with the legacy thread-local crate::animation::wants_tick flag, which is retained as a transitional fallback for widgets that haven’t yet moved their pending-repaint state into their own struct. Widgets should prefer overriding needs_paint (visibility-safe) over calling the thread-local request_tick (fires even from hidden subtrees).

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

Earliest scheduled repaint 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 and bubbles up.

If a global key handler was registered via [set_global_key_handler] and it returns true, the key is consumed and the focused widget does not receive 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 collect_inspector_nodes(&self) -> Vec<InspectorNode>

Snapshot the entire widget tree for the inspector.

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).