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

impl App

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

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 focused_is_text_input(&self) -> bool

Whether the focused widget accepts typed text (a TextField, TextArea, RichTextEdit, or a DragValue in its edit mode).

Web shells use this to decide when to focus the hidden DOM <textarea> that backs IME composition and clipboard events: without it focused, the browser never delivers copy / cut / paste events to a canvas-only app, so the in-canvas editors get no clipboard bridge.

Delegates straight to Widget::accepts_text_input on the focused widget rather than matching type-name strings, so any new editor that overrides the trait is enrolled automatically (a hardcoded name list would silently miss it and reintroduce exactly the wasm clipboard bug).

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_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. Convention matches winit / WheelEvent: positive delta_y = wheel rotated forward = user wants to see content ABOVE the current view. Scroll containers DECREASE their offset when delta_y is positive. Positive delta_x = see content to the LEFT.

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_file_dropped( &mut self, screen_x: f64, screen_y: f64, paths: Vec<PathBuf>, )

Native drag-and-drop landed paths on the window at the given screen position. Dispatches an Event::FileDropped to the widget under the cursor (same hit-test path as on_mouse_down), so a widget can opt in by handling the event in on_event.

Native shells typically receive one path per DroppedFile event from winit; they may forward each separately, or batch a single drag gesture into one call. The widget receives paths as-is.

pub fn ensure_focused_visible_above_keyboard(&mut self)

Lift the focused widget above the on-screen keyboard panel so typing never disappears behind it. No-op when already visible.