Struct RenderRoot 

pub struct RenderRoot<State: 'static, V: View<State>> { /* private fields */ }

Owns the retained tree and drives the rebuild/layout/paint/event passes of a single-root app.

Implementations

impl<State: 'static, V: View<State>> RenderRoot<State, V>

pub fn set_focus_ring_policy(&mut self, policy: FocusRingPolicy)

Choose when the focused widget draws a ring (default FocusRingPolicy::KeyboardOnly).

pub fn focus_ring_policy(&self) -> FocusRingPolicy

The policy RenderRoot::set_focus_ring_policy last set.

pub fn set_tab_traversal(&mut self, enabled: bool)

Switch Tab traversal on (the default) or off. Off, a bare Tab/Shift+Tab the tree, the forward and the shortcut table declined stays unhandled, for the host’s own tab order. On, each such Tab rebuilds the walk’s stops (accepted: Tab is rare).

pub fn tab_traversal(&self) -> bool

Whether a declined bare Tab runs traversal (RenderRoot::set_tab_traversal).

pub fn set_layout_skip(&mut self, skip: bool)

Switch the layout skip on (the default) or off; false lays out every pod every pass.

pub fn layout_skip(&self) -> bool

Whether layout passes may skip clean pods (RenderRoot::set_layout_skip).

pub fn set_layout_audit(&mut self, audit: bool)

Turn the layout audit (a debug aid that doubles layout cost) on or off; off by default. With the skip on, layout re-runs forced and warns layout-audit: per pod moved >1e-3 px.

pub fn layout_audit(&self) -> bool

Whether the layout audit is on (RenderRoot::set_layout_audit).

pub fn layout_audit_mismatches(&self) -> u64

Pods the layout audit has found with mismatched geometry since creation, every occurrence counted (unlike the rate-limited log).

pub fn layout_epoch(&self) -> u64

The global layout epoch the next layout pass runs under, for tooling and tests.

pub fn set_retained_layers(&mut self, enabled: bool)

Enable or disable retained layers (default on); off, every boundary repaints its child.

pub fn set_retained_ledger(&mut self, ledger: &RetainedLedger)

Hand the root the renderer’s resident-key ledger from the previous frame (one frame stale by design); cloned only when it differs.

pub fn retained_layers(&self) -> bool

Whether retained layers are enabled (RenderRoot::set_retained_layers).

pub fn set_theme(&mut self, theme: Box<dyn Any>)

Store (replace) the app’s type-erased theme, recovered by widgets via theme_as. Marks LAYOUT | PAINT and invalidates every cached layout: widgets bake themed state at layout.

pub fn set_insets(&mut self, insets: WindowInsets)

Store the window’s insets, recovered by widgets via window_insets. An actual change dirties exactly like RenderRoot::set_theme; pushing the current value is a no-op.

pub fn insets(&self) -> WindowInsets

The window’s insets currently threaded into the layout/paint passes.

pub fn set_presented_frames(&mut self, presented: u64)

Store the shell’s presented-frame count (pushed once per UI frame, before paint). Dirties nothing: a ticking count marked dirty would keep the mobile frame gate from ever idling.

pub fn presented_frames(&self) -> Option<u64>

The presented-frame count currently threaded into the paint pass, or None if no shell has pushed one.

pub fn set_surface_translucent(&mut self, translucent: bool)

Store the surface’s resolved translucency (what the backend granted, not what the app asked: a refused request must stay opaque, or every platform-view slot punches a black hole). An actual change marks PAINT and invalidates retained paint; no relayout.

pub fn is_surface_translucent(&self) -> bool

Whether the shell’s GPU surface is currently marked translucent.

impl<State: 'static, V: View<State>> RenderRoot<State, V>

pub fn event(&mut self, state: &mut State, event: &InputEvent) -> EventOutcome

Deliver an input event to the widget tree. The outcome’s handled is the dispatch’s result; needs_redraw is set when a widget consumed the event or asked for a redraw, and for a hover that ended with nothing taking it (the one repaint no widget can request). The pass never rebuilds or repaints: the shell runs RenderRoot::rebuild afterwards, which itself calls this sequentially with InputEvent::Housekeeping.

Beside the outcome it resolves the cursor (RenderRoot::cursor, on a pointer Move), the clipboard write and paste request (every pass), the IME state and the focus epoch. A FileDropPhase::Drop or Cancel is followed in the same call by a FileDropPhase::Ended broadcast to the whole tree; an unhandled Key goes on (dispatch_declined_key); the outcome folds all.

impl<State: 'static, V: View<State>> RenderRoot<State, V>

pub fn layout(&mut self, window_size: Size) -> Size

Lay out the root widget against window_size and record its geometry.

The root gets loose constraints and sits at the origin; returns its size. No text context is threaded (use RenderRoot::layout_with_text).

pub fn layout_with_text( &mut self, window_size: Size, text_ctx: &mut dyn Any, ) -> Size

Lay out the root widget, threading a shared text-shaping context down to text widgets.

text_ctx is the shell-owned frust_text::TextContext, type-erased so this crate needs no frust-text dependency; widgets recover it via crate::widget::LayoutCtx::text_context.

impl<State: 'static, V: View<State>> RenderRoot<State, V>

pub fn paint( &mut self, scene: &mut dyn PaintScene, frame_time: FrameTime, ) -> PaintOutcome

Paint the root widget into scene. The outcome reports a continuation frame (PaintCtx::request_frame → PaintOutcome::needs_frame) and a paint-time PaintCtx::request_layout, which is also folded into the pending ChangeFlags as LAYOUT. frame_time is the shell’s clock for the frame, threaded unchanged to every widget (PaintCtx::frame_time).

The overlay post-pass

Surfaces registered during the main walk (PaintCtx::register_overlay) are painted after it in band order, escaping their owner’s paint order and clips; their routing rects are kept for the next event pass to hit-test first, and their outcomes merge into this one.

pub fn selection_toolbar(&self) -> Option<SelectionToolbarRequest>

The selection-toolbar request the focused field published during the most recent RenderRoot::paint, or None when no field is focused. A level: a shell driving the platform edit menu (SelectionToolbarPolicy::Native) reads it beside RenderRoot::ime_state. Present with a bare caret too (paste applies), and under the framework policy as well.

pub fn selection_toolbar_generation(&self) -> u64

A generation bumped on every change to the menu-significant part of RenderRoot::selection_toolbar (present_menu and actions, clearing included). A moved anchor is not an edge: a shell re-reads it per frame, caching this value like RenderRoot::focus_ime_generation.

impl<State: 'static, V: View<State>> RenderRoot<State, V>

pub fn platform_view_frames(&self) -> &[PlatformViewFrame]

The PlatformViewFrames the most recent paint published, in paint order (never stale).

pub fn input_shields(&self) -> &[Rect]

The z-shield rects the most recent paint reported, in paint order (never stale).

pub fn take_retired_platform_views(&mut self) -> Vec<u64>

Drain the slot ids whose platform_view widgets were torn down since the last call, so a shell retires their native views at once. Each id is reported exactly once; a merely culled slot never appears (culling runs no teardown).

pub fn take_change_flags(&mut self) -> ChangeFlags

Take (and clear) the dirtiness accumulated since the last call.

pub fn has_pending_change_flags(&self) -> bool

Non-draining peek: whether any LAYOUT/PAINT bit is pending. A frame gate reads it before deciding, so a skipped frame leaves the flags for the next running frame to drain.

pub fn root_id(&self) -> Option<WidgetId>

The root widget id, once built.

pub fn tree(&self) -> &WidgetTree

Shared access to the retained tree (for the shell / tests).

pub fn inspect(&self) -> Vec<InspectNode>

A read-only pre-order snapshot of the retained tree, container-owned pods included, for tooling: per node its id, parent, children, type name, debug label and absolute border box. Bounds are the last layout pass’s (all zero before the first).

pub fn inspect_layout_dirty(&self) -> Vec<(WidgetId, bool)>

Per-node layout-dirty state in RenderRoot::inspect’s order and ids, for tooling/tests.

pub fn inspect_paint_dirty(&self) -> Vec<(WidgetId, bool)>

Per-node paint-dirty state, read-only — see WidgetTree::inspect_paint_dirty.

pub fn rebuild( &mut self, build: &mut impl FnMut(&mut State) -> V, state: &mut State, ) -> ChangeFlags

Run the build closure, then build (first call) or rebuild the root widget, returning what changed. The closure re-runs in full every rebuild, so it must be cheap.

Deferred-callback flush

While a structural op has raised mark_pending_result_flush, each pass dispatches one InputEvent::Housekeeping broadcast (where &mut State is in scope) and re-diffs, capped by MAX_PENDING_RESULT_FLUSH_PASSES: past it the mark stays raised and one more frame is requested. A broadcast’s needs_redraw requests that frame too.

impl<State: 'static, V: View<State>> RenderRoot<State, V>

pub fn semantics(&self) -> SemanticsUpdate

Collect the accessibility tree as a SemanticsUpdate for a platform accesskit_* adapter. Pull-based (the shell calls it on demand, never per frame) and valid only after RenderRoot::layout, since bounds come from post-layout geometry. Always rooted at a synthetic window-sized accesskit::Role::Window node; an unbuilt tree yields that node alone.

pub fn semantics_generation(&self) -> u64

The semantics dirty gate: bumped by a rebuild that returned change flags, a theme swap, and an inset change. A shell records the value it last pushed and compares (RenderRoot::semantics_if_changed).

pub fn semantics_if_changed(&self, last_seen: u64) -> Option<SemanticsUpdate>

A fresh whole-tree SemanticsUpdate if the generation moved past last_seen, else None (the shell skips the walk and the push). Call it post-layout; on Some, store RenderRoot::semantics_generation.

pub fn perform_accessibility_action( &mut self, state: &mut State, node_id: NodeId, action: Action, ) -> EventOutcome

Perform a platform accessibility action by synthesizing pointer input at the node’s bounds center through RenderRoot::event, returning the combined EventOutcome. Handles Click and Focus only:

• accesskit::Action::Click → Down then Up, as a real tap.
• accesskit::Action::Focus → Down then Cancel: the Down claims focus for a widget that opts in on Down; the Cancel releases its capture without touching focus or firing an on-press callback.

Any other action, or a node_id not in the tree, is a no-op. Requires a prior RenderRoot::layout; a widget needing a real drag is not operable.

impl<State: 'static, V: View<State>> RenderRoot<State, V>

pub fn is_pointer_captured(&self) -> bool

Whether a captured pointer gesture is currently in flight.

pub fn pointer_capture_claimant(&self) -> Option<PointerId>

The contact that claimed the capture in flight (only its Up/Cancel ends it), or None.

pub fn pointer_capture_contacts(&self) -> bool

Whether the capture in flight routes the gesture’s other contacts to its captor.

pub fn is_focus_active(&self) -> bool

Whether some widget in the tree currently holds keyboard/IME focus.

pub fn is_hover_active(&self) -> bool

Whether the last hover pass left a widget holding the hover link; a rebuild removing the claimant ends it. A touch drag raises it too (LIMITATIONS hover-window-leave-standing).

pub fn cursor(&self) -> CursorIcon

The cursor the tree last asked the host to show: re-resolved on every pointer Move (CursorIcon::Default when nothing asked) and standing through every other pass. Residual: a widget that is torn down (or moves out from under a stationary pointer) while its request stands leaves the last shape in place until the next Move re-resolves it.

pub fn take_clipboard_write(&mut self) -> Option<String>

Take (and clear) the text a widget asked the shell to put on the host clipboard; drain after every RenderRoot::event. Destructive: a write is an edge, so a dropped result is lost.

pub fn take_paste_request(&mut self) -> bool

Take (and clear) whether a widget asked to read the host clipboard; the shell answers with a new EditCommand::Paste dispatch, dropping an async answer once focus_epoch has moved.

pub fn ime_state(&self) -> Option<ImeState>

The IME surface the focused widget published, for the platform input method. None is the only no-session form: an inactive publish is a release, so is_some() means a live session.

pub fn focus_ime_generation(&self) -> u64

Bumped on every actual change of is_focus_active or ime_state — the frame gate’s focus_or_ime_changed edge. It counts surface changes, not sessions (see focus_epoch).

pub fn focus_epoch(&self) -> u64

The live focus session’s identity. It advances once per honoured claim (an EventCtx::request_focus or a traversal grant) and once per release, so a Tab step that lands from a live session moves it by two (by one from none) and one that lands nowhere leaves it unchanged. It moves when focus crosses fields that publish alike. Never 0: a safe sentinel.

impl<State: 'static, V: View<State>> RenderRoot<State, V>

pub fn new() -> Self

Create an empty render root with no widget yet built.

pub fn shortcut_hints( &self, filter: impl FnMut(&ShortcutHint) -> bool, ) -> Vec<ShortcutHint>

The last paint’s shortcut declarations filter keeps, in paint order: a palette’s list.

Trait Implementations

impl<State: 'static, V: View<State>> Default for RenderRoot<State, V>

fn default() -> Self

Returns the “default value” for a type.