Struct UiState 

pub struct UiState {
    pub pointer_pos: Option<(f32, f32)>,
    pub hovered: Option<UiTarget>,
    pub pressed: Option<UiTarget>,
    pub focused: Option<UiTarget>,
    pub focus_visible: bool,
    pub current_selection: Selection,
    pub modifiers: KeyModifiers,
    /* private fields */
}

Internal UI state — interaction trackers + the side maps the library writes during layout / state-apply / animation-tick passes. Owned by the renderer; the host doesn’t interact with this directly.

The side maps replace the per-node bookkeeping fields that used to live on El (computed rect, interaction state, envelope amounts). Keying is by El::computed_id, the path-shaped string assigned by the layout pass.

Fields

pointer_pos: Option<(f32, f32)>

Last known pointer position in logical pixels. None until the pointer enters the window.

hovered: Option<UiTarget>

pressed: Option<UiTarget>

focused: Option<UiTarget>

focus_visible: bool

Whether the focused element should display its focus ring. Tracks the web platform’s :focus-visible heuristic: keyboard focus (Tab, arrow-nav) raises the flag; pointer-down clears it. Widgets where the ring belongs even on click — text inputs and text areas, where the ring communicates “this surface is now active” beyond the caret alone — opt back in via crate::tree::El::always_show_focus_ring.

current_selection: Selection

Mirror of the application’s current crate::selection::Selection. Set by the host runner once per frame from crate::event::App::selection; read by the painter to draw highlight bands and by the selection manager to know what’s currently active when extending a drag.

modifiers: KeyModifiers

Last known keyboard modifier mask. Updated by the host runner from winit’s ModifiersChanged; pointer events stamp this value into their UiEvent.modifiers so widgets that need to detect Shift+click / Ctrl+drag can read it without separate plumbing.

Implementations

impl UiState

pub fn envelope(&self, id: &str, kind: EnvelopeKind) -> f32

Current eased state envelope amount in [0, 1] for (id, kind). Missing entries read as 0.0.

pub fn tick_visual_animations(&mut self, root: &mut El, now: Instant) -> bool

Walk the laid-out tree, retarget per-(node, prop) animations to the values implied by each node’s current state, step them forward to now, and write back: app-driven props mutate the El’s fill / text_color / stroke / opacity / translate / scale (so the next rebuild reads the eased value); state envelopes are written to the envelope side map for draw_ops to modulate visuals from.

Returns true if any animation is still in flight; the host should request another redraw next frame.

pub fn set_animation_mode(&mut self, mode: AnimationMode)

Switch animation pacing. The default is AnimationMode::Live; headless render binaries flip to AnimationMode::Settled so a single-frame snapshot reflects the post-animation visual without depending on integrator timing.

pub fn animation_mode(&self) -> AnimationMode

Current animation pacing. Backends read this to gate time-driven shader uniforms (e.g. frame.time) so headless fixtures stay byte-identical regardless of when they ran.

pub fn has_animations_in_flight(&self) -> bool

Whether any visual animation is still moving. The host’s runner uses this (via the renderer’s PrepareResult) to keep the redraw loop ticking only while there’s motion.

pub fn debug_summary(&self) -> String

One-line summary of interactive state for diagnostic logging. Format: hov=<key|->|press=<key|->|focus=<key|->|env={...}|in_flight=N. Keep terse — this is intended for per-frame console.log.

impl UiState

pub fn cursor(&self, root: &El) -> Cursor

Resolved pointer cursor for the current frame.

Picks the cursor in this order:

1. If Self::pressed is set: a. If the press target itself declares .cursor_pressed(...), use that — drives the slider’s Grab → Grabbing transition and the more general “press has its own affordance” idiom. Does not inherit: an ancestor’s cursor_pressed doesn’t apply to a descendant press target. b. Otherwise walk from the press target up to root for the first explicit .cursor(...). Press capture wins so a button drag that wanders onto a text region doesn’t flicker the cursor mid-press.
2. Else if the pointer is over a text-link run (hovered_link is Some), use Cursor::Pointer. Link runs aren’t keyed hit-test targets, so this branch sits parallel to the keyed-hover lookup. Beats any .cursor(Cursor::Text) declared on a containing paragraph — link affordance is more specific than panel affordance.
3. Else if Self::hovered is set, walk from the hovered target up to root for the first explicit declaration — so a panel that sets .cursor(Move) once propagates to children that don’t override.
4. Else Cursor::Default.

Disabled state isn’t auto-mapped to Cursor::NotAllowed; widgets that want that affordance branch in their build closure.

impl UiState

pub fn sync_focus_order(&mut self, root: &El)

pub fn set_focus(&mut self, target: Option<UiTarget>)

pub fn push_focus_requests(&mut self, keys: Vec<String>)

Queue programmatic focus requests by key. Each entry is resolved once per prepare_layout, after the focus order has been rebuilt: matching keys focus the corresponding node; unmatched keys are dropped silently. Hosts call this once per frame from crate::event::App::drain_focus_requests; apps that own a Runner can also push directly for tests.

pub fn drain_focus_requests(&mut self)

Drain the queued focus requests, resolving each by key against the current focus order. The last successfully-resolved key wins. Called by prepare_layout after sync_popover_focus so explicit requests override popover auto-focus.

pub fn set_focus_visible(&mut self, visible: bool)

Set whether the current focus should display its focus ring. The runtime calls this from input-handling paths: pointer-down clears it (false), Tab and arrow-nav raise it (true). Apps that move focus programmatically can also flip it explicitly, e.g. force the ring on after restoring focus from an off-screen menu close. See UiState::focus_visible.

pub fn focus_next(&mut self) -> Option<&UiTarget>

pub fn focus_prev(&mut self) -> Option<&UiTarget>

impl UiState

pub fn node_state(&self, id: &str) -> InteractionState

Resolved interaction state for id. Returns InteractionState::Default when no tracker matches.

pub fn apply_to_state(&mut self)

Rebuild the resolved per-node interaction-state side map from the current focused/pressed/hovered trackers. Press wins over Hover on a same-node match; Hover wins over Focus on a same-node match (so a keyboard-auto-focused menu item still gets its hover-lighten when the cursor is over it). Focus applies on its own when the node isn’t pressed or hovered.

Press is gated on the pointer being currently over the originally-pressed target — drag the cursor off and the press visual decays, drag back on and it returns. Mirrors the HTML / Tailwind :active behaviour: the visual reflects “would release-here activate?”, not “was pointer_down captured?”. Drag events still route to pressed regardless of pointer position (see runtime::pointer_moved); this gating only affects the visual envelope.

impl UiState

pub fn set_hotkeys(&mut self, hotkeys: Vec<(KeyChord, String)>)

Replace the hotkey registry. Called by the host runner from App::hotkeys() once per build cycle.

pub fn set_modifiers(&mut self, modifiers: KeyModifiers)

Update the tracked modifier mask. Hosts call this from their platform’s “modifiers changed” hook (e.g. winit’s WindowEvent::ModifiersChanged); the value is stamped into UiEvent.modifiers for every subsequent pointer event so widgets can detect Shift+click / Ctrl+drag without needing a per-call modifier parameter.

pub fn try_hotkey( &self, key: &UiKey, modifiers: KeyModifiers, repeat: bool, ) -> Option<UiEvent>

Match key + modifiers against the registered hotkey chords. Returns a Hotkey event if any registered chord matches; the event.key is the chord’s registered name. Used by both the library-default path and the capture-keys path (hotkeys always win over a widget’s raw key capture).

pub fn key_down_raw( &self, key: UiKey, modifiers: KeyModifiers, repeat: bool, ) -> Option<UiEvent>

Build a raw KeyDown event routed to the focused target, bypassing the library’s Tab/Enter/Escape interpretation. Used by the runner when the focused node has capture_keys=true. Returns None if no node is focused.

pub fn key_down( &mut self, key: UiKey, modifiers: KeyModifiers, repeat: bool, ) -> Option<UiEvent>

impl UiState

pub fn rect(&self, id: &str) -> Rect

Look up the layout-assigned rect for id; returns a zero rect when id is unknown (pre-layout, or not in the laid-out tree).

pub fn rect_of_key(&self, root: &El, key: &str) -> Option<Rect>

Look up the layout-assigned rect for an app-supplied element key. Returns None when the key is absent from root or layout has not written a rect for that node yet.

pub fn target_of_key(&self, root: &El, key: &str) -> Option<UiTarget>

Build a UiTarget for an app-supplied element key using the current layout rect. Useful for hosts that need to anchor native overlays or forward events into externally painted regions.

pub fn hovered_key(&self) -> Option<&str>

The keyed leaf currently under the pointer, or None when nothing is hovered. Mirrors pointer hit-test target data, but is read-only and stable across rebuilds so apps can branch the build output on “what is hovered right now.”

Returns the leaf — the deepest keyed hit-test target. Use Self::is_hovering_within for subtree-aware queries (“is anything inside this row hovered?”), which matches the semantics of crate::tree::El::hover_alpha.

pub fn is_hovering_within(&self, key: &str) -> bool

True iff key’s node — or any descendant of it — is the current hover target. Subtree-aware: a focusable card with keyed icon-buttons inside it reports true whether the cursor is on the card body or on one of the buttons. Same predicate El::hover_alpha uses to drive its declarative reveal, exposed for app-side reads.

Reads the underlying tracker, not the eased subtree envelope — the boolean flips immediately on hit-test identity change. For reactions tied to the eased animation, drive visuals through hover_alpha instead.

Returns false when key isn’t in the current tree (pre- layout, or the keyed node was removed in a recent build).

impl UiState

pub fn set_scroll_offset(&mut self, id: impl Into<String>, value: f32)

Seed or read the persistent scroll offset for id. Use this to pre-position a scroll viewport before crate::layout::layout runs (call crate::layout::assign_ids first to populate the node’s computed_id).

Examples found in repository

examples/virtual_list.rs (line 75)

fn main() -> std::io::Result<()> {
    let mut root = fixture();
    layout::assign_ids(&mut root);
    let list_id = find_id(&root, "entries").expect("virtual_list id");

    let mut ui_state = UiState::new();
    // Scroll so the realized window is near row 5000.
    ui_state.set_scroll_offset(list_id, 5000.0 * ROW_HEIGHT);

    let viewport = Rect::new(0.0, 0.0, 540.0, 540.0);
    let bundle = render_bundle_with(&mut root, &mut ui_state, viewport);

    let out_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("out");
    let written = write_bundle(&bundle, &out_dir, "virtual_list")?;
    for p in &written {
        println!("wrote {}", p.display());
    }

    if !bundle.lint.findings.is_empty() {
        eprintln!("\nlint findings ({}):", bundle.lint.findings.len());
        eprint!("{}", bundle.lint.text());
    }

    Ok(())
}

examples/scroll_list.rs (line 55)

fn main() -> std::io::Result<()> {
    // Scroll part-way down so the artifact actually shows the offset
    // applied — the top rows clip and middle rows fill the viewport.
    // Side-map architecture: we assign_ids first to populate the
    // scroll node's computed_id, seed UiState by id, then call
    // render_bundle_with so the layout pass sees the offset.
    let mut root = scroll_list_fixture();
    layout::assign_ids(&mut root);
    let scroll_id = find_id(&root, "notifications").expect("scroll node id");
    let mut ui_state = UiState::new();
    ui_state.set_scroll_offset(scroll_id, 220.0);

    let viewport = Rect::new(0.0, 0.0, 720.0, 600.0);
    let bundle = render_bundle_with(&mut root, &mut ui_state, viewport);

    let out_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("out");
    let written = write_bundle(&bundle, &out_dir, "scroll_list")?;
    for p in &written {
        println!("wrote {}", p.display());
    }

    if !bundle.lint.findings.is_empty() {
        eprintln!("\nlint findings ({}):", bundle.lint.findings.len());
        eprint!("{}", bundle.lint.text());
    }

    Ok(())
}

pub fn scroll_offset(&self, id: &str) -> f32

Read the current scroll offset for id. Defaults to 0.0.

pub fn push_scroll_requests(&mut self, requests: Vec<ScrollRequest>)

Queue programmatic scroll-to-row requests targeting virtual lists by key. Each request is consumed during layout of the matching list — viewport height and row heights are only known then, especially for virtual_list_dyn where unmeasured rows use the configured estimate. Hosts call this once per frame from crate::event::App::drain_scroll_requests; apps that own a Runner can also push directly for tests.

pub fn clear_pending_scroll_requests(&mut self)

Drop any scroll requests still queued after the layout pass completed. Called by prepare_layout so requests targeting a list that wasn’t in the tree this frame don’t silently fire against a re-mounted list with the same key on a later frame.

pub fn scrollbar_tracks(&self) -> impl Iterator<Item = (&str, &Rect)>

Iterate (scroll_node_id, track_rect) for every scrollable whose visible scrollbar is currently active. Hosts use this to drive cursor changes (e.g., a vertical-resize cursor over the thumb), to drive screenshot tools, or to test interaction flows. The map is rebuilt every layout pass.

pub fn thumb_at(&self, x: f32, y: f32) -> Option<(String, Rect, Rect)>

Look up the scrollable whose track rect contains (x, y), returning its computed_id, the track rect, and the visible thumb rect. Returns None if no track is currently visible at that point. The track rect is wider than the visible thumb (Fitts’s law) and spans the full viewport height so callers can branch on whether y lands inside the thumb (grab) or above/below (click-to-page).

pub fn pointer_wheel(&mut self, root: &El, point: (f32, f32), dy: f32) -> bool

Increment the scroll offset for the deepest scrollable container containing point. Returns true if any scrollable was hit and updated (host can use this to decide whether to request a redraw).

impl UiState

pub fn sync_selection_order(&mut self, root: &El)

Walk the laid-out tree and rebuild the selectable-text order. Same shape as Self::sync_focus_order but filters for selectable keyed leaves instead of focusable ones. Should run on every frame post-layout, before the selection manager processes pointer events.

pub fn selection_order(&self) -> &[UiTarget]

Read access to the current document-order list of selectable leaves. Mainly for tests; the selection manager uses internal access.

impl UiState

pub fn push_toast(&mut self, spec: ToastSpec, now: Instant)

Queue a toast for the next frame. Stamps an id (monotonic) and computes the expires_at deadline from now + spec.ttl. The runtime re-walks the queue each frame and drops expired entries before synthesizing the toast layer.

Examples found in repository

examples/toast.rs (line 68)

fn main() -> std::io::Result<()> {
    let viewport = Rect::new(0.0, 0.0, 720.0, 360.0);
    // Seed the runtime's toast queue directly so the bundle dump
    // shows the synthesized layer. In a live app the host calls
    // `runner.push_toasts(app.drain_toasts())` once per frame.
    let mut state = UiState::new();
    let now = Instant::now();
    let long_ttl = Duration::from_secs(60);
    state.push_toast(ToastSpec::success("Settings saved").with_ttl(long_ttl), now);
    state.push_toast(
        ToastSpec::warning("Battery low — connect charger").with_ttl(long_ttl),
        now,
    );
    state.push_toast(
        ToastSpec::error("Failed to reach update server").with_ttl(long_ttl),
        now,
    );
    state.push_toast(
        ToastSpec::info("New version available").with_ttl(long_ttl),
        now,
    );

    let mut tree = fixture();
    assign_ids(&mut tree);
    let _ = synthesize_toasts(&mut tree, &mut state, now);
    let bundle = render_bundle_with(&mut tree, &mut state, viewport);

    let out_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("out");
    let written = write_bundle(&bundle, &out_dir, "toast")?;
    for p in &written {
        println!("wrote {}", p.display());
    }

    if !bundle.lint.findings.is_empty() {
        eprintln!("\nlint findings ({}):", bundle.lint.findings.len());
        eprint!("{}", bundle.lint.text());
    }
    Ok(())
}

pub fn dismiss_toast(&mut self, id: u64)

Remove the toast with the given id. Used by the runtime when the user clicks a toast-dismiss-{id} button; apps that want to programmatically cancel a toast can call this directly via the Runner::dismiss_toast host accessor.

pub fn toasts(&self) -> &[Toast]

Read-only view of the current toast queue (post-expiry). Used by hosts that want to drive cursor / accessibility state from the visible stack.

impl UiState

pub fn widget_state<T: WidgetState>(&self, id: &str) -> Option<&T>

Look up the widget state of type T for id. Returns None if no entry exists or the entry was inserted as a different type.

pub fn widget_state_mut<T: WidgetState + Default>(&mut self, id: &str) -> &mut T

Get a mutable reference to the widget state of type T for id, inserting T::default() if no entry exists. Use this in the build closure of a stateful widget so the first call after the node enters the tree produces a fresh state, and every subsequent call returns the live one.

pub fn clear_widget_state<T: WidgetState>(&mut self, id: &str)

Drop the widget state of type T for id, if any.

pub fn widget_state_summary(&self, id: &str) -> Vec<(&'static str, String)>

Iterate (id, type_name, debug_summary) for every live widget state. Used by the tree dump to surface per-widget state in the agent loop’s view.

impl UiState

pub fn new() -> Self

Examples found in repository

examples/virtual_list.rs (line 73)

fn main() -> std::io::Result<()> {
    let mut root = fixture();
    layout::assign_ids(&mut root);
    let list_id = find_id(&root, "entries").expect("virtual_list id");

    let mut ui_state = UiState::new();
    // Scroll so the realized window is near row 5000.
    ui_state.set_scroll_offset(list_id, 5000.0 * ROW_HEIGHT);

    let viewport = Rect::new(0.0, 0.0, 540.0, 540.0);
    let bundle = render_bundle_with(&mut root, &mut ui_state, viewport);

    let out_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("out");
    let written = write_bundle(&bundle, &out_dir, "virtual_list")?;
    for p in &written {
        println!("wrote {}", p.display());
    }

    if !bundle.lint.findings.is_empty() {
        eprintln!("\nlint findings ({}):", bundle.lint.findings.len());
        eprint!("{}", bundle.lint.text());
    }

    Ok(())
}

examples/scroll_list.rs (line 54)

fn main() -> std::io::Result<()> {
    // Scroll part-way down so the artifact actually shows the offset
    // applied — the top rows clip and middle rows fill the viewport.
    // Side-map architecture: we assign_ids first to populate the
    // scroll node's computed_id, seed UiState by id, then call
    // render_bundle_with so the layout pass sees the offset.
    let mut root = scroll_list_fixture();
    layout::assign_ids(&mut root);
    let scroll_id = find_id(&root, "notifications").expect("scroll node id");
    let mut ui_state = UiState::new();
    ui_state.set_scroll_offset(scroll_id, 220.0);

    let viewport = Rect::new(0.0, 0.0, 720.0, 600.0);
    let bundle = render_bundle_with(&mut root, &mut ui_state, viewport);

    let out_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("out");
    let written = write_bundle(&bundle, &out_dir, "scroll_list")?;
    for p in &written {
        println!("wrote {}", p.display());
    }

    if !bundle.lint.findings.is_empty() {
        eprintln!("\nlint findings ({}):", bundle.lint.findings.len());
        eprint!("{}", bundle.lint.text());
    }

    Ok(())
}

examples/toast.rs (line 65)

fn main() -> std::io::Result<()> {
    let viewport = Rect::new(0.0, 0.0, 720.0, 360.0);
    // Seed the runtime's toast queue directly so the bundle dump
    // shows the synthesized layer. In a live app the host calls
    // `runner.push_toasts(app.drain_toasts())` once per frame.
    let mut state = UiState::new();
    let now = Instant::now();
    let long_ttl = Duration::from_secs(60);
    state.push_toast(ToastSpec::success("Settings saved").with_ttl(long_ttl), now);
    state.push_toast(
        ToastSpec::warning("Battery low — connect charger").with_ttl(long_ttl),
        now,
    );
    state.push_toast(
        ToastSpec::error("Failed to reach update server").with_ttl(long_ttl),
        now,
    );
    state.push_toast(
        ToastSpec::info("New version available").with_ttl(long_ttl),
        now,
    );

    let mut tree = fixture();
    assign_ids(&mut tree);
    let _ = synthesize_toasts(&mut tree, &mut state, now);
    let bundle = render_bundle_with(&mut tree, &mut state, viewport);

    let out_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("out");
    let written = write_bundle(&bundle, &out_dir, "toast")?;
    for p in &written {
        println!("wrote {}", p.display());
    }

    if !bundle.lint.findings.is_empty() {
        eprintln!("\nlint findings ({}):", bundle.lint.findings.len());
        eprint!("{}", bundle.lint.text());
    }
    Ok(())
}

Trait Implementations

impl Debug for UiState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for UiState

fn default() -> UiState

Returns the “default value” for a type.