Struct GroupRow 

pub struct GroupRow {
    pub groups: Vec<WindowGroup>,
    /* private fields */
}

Fields

groups: Vec<WindowGroup>

Implementations

impl GroupRow

pub fn edge_grab_at(&self, p: Point) -> Option<EdgeGrab>

The window edge a press at p would resize, by the seam rule (seam_owner): on a seam, the focused window’s edge, else the half’s; at either end of a lane, its outer window’s outer edge. None off every edge, on a maximized or fullscreen window, or where the viewport clips the edge away.

pub fn edge_resize_in_flight(&self) -> bool

pub fn edge_hover(&self) -> Option<(EdgeGrab, bool)>

The edge a press would resize now, and whether Shift is held.

impl GroupRow

pub fn hint_places(&self) -> HintPlaces

Where this row’s controls are for control hints.

impl GroupRow

pub fn set_canvas(&mut self, view: Option<CanvasView>)

Show this row’s windows on a canvas (Some), or in their strip.

pub fn canvas(&self) -> Option<&CanvasView>

How the row’s windows stand on its canvas, while it shows one.

pub fn canvas_group_at(&self, p: Point) -> Option<u64>

The window group whose drawn rect holds screen point p, while the row shows a canvas.

pub fn take_pending_canvas_move(&mut self) -> Option<(u64, Rect)>

A window carried by its bar to a new place on the canvas, once let go: its group and the place, in canvas pixels, for the host to keep.

impl GroupRow

pub fn set_floats(&mut self, floats: HashMap<u64, Rect>)

Show the windows of floats at their rects, in the surface’s coordinates, and every other window in its strip. A window that leaves the set is back in the strip.

pub fn floats(&self) -> &HashMap<u64, Rect>

The windows floating above the desk, by group id, at their rects.

pub fn is_floating(&self, id: u64) -> bool

Whether the group id floats above the desk.

pub fn float_group_at(&self, p: Point) -> Option<u64>

The floating window whose rect holds screen point p, the one on top first.

pub fn take_pending_float(&mut self) -> Option<FloatAsk>

Where a float the person moved or let go goes, once: drained by the host and kept in the workspace’s record.

pub fn float_rect_at(&self, p: Point) -> Rect

The rect a window let go at p floats in: the floating size, hung from the hand, kept inside the row’s display.

impl GroupRow

pub fn new(groups: Vec<WindowGroup>) -> GroupRow

pub fn set_external_navigation(&mut self, external: bool)

Set or clear the transient fullscreen override, driven by the shell from compositor state; (None, false) restores normal tiling exactly.

pub fn hold_sibling_fade_at(&mut self, elapsed: Duration) -> bool

Freeze the sibling fade at elapsed along durations.fast: offscreen paints cost more wall time than the curve, so a capture harness would only ever see the endpoints. Not gated on debug_assertions, since shots ships in release.

pub fn clear_sibling_fade_hold(&mut self)

pub fn set_fullscreen(&mut self, fullscreen_group: Option<u64>, hidden: bool)

pub fn is_fullscreen(&self) -> bool

pub fn set_covered_output(&mut self, output: Option<u32>)

Collapse this strip’s lane on output, where another strip’s fullscreen covers it, keeping its lanes on other displays; None shows every lane again.

pub fn set_promotion_keeps_gutter(&mut self, keeps: bool)

Whether the promoted group stops at its lane’s leading gutter (a maximize) or covers it (a client fullscreen).

pub fn set_promotion_keeps_controls(&mut self, keeps: bool)

Keep the maximized system controls even when the promoted group covers its gutter. Client fullscreen leaves this off.

pub fn with_leading_inset(self, px: f64) -> GroupRow

Reserve a canvas-x gutter before the first group so it pans with scroll_x; on a partitioned strip only the leading lane carries it.

pub fn leading_inset(&self) -> f64

pub fn set_leading_inset(&mut self, px: f64)

pub fn set_output_spans(&mut self, spans: &[OutputSpan])

Passing an empty slice restores the fallback in Self::usable_at.

pub fn output_spans(&self) -> &[OutputSpan]

pub fn set_lanes(&mut self, lanes: &[StripLane], assignment: &HashMap<u64, u32>)

Partition the strip across displays: one lane per display, left to right, and each group’s display. Fewer than two lanes restores the one continuous row, and a lane keeps its pan while its display stays. Groups must already be ordered lane by lane.

pub fn set_shown_outputs(&mut self, outputs: &[u32])

Show this strip on outputs only: its other lanes move off their display, so it neither draws nor takes input there, and a display coming back draws it where it was left.

pub fn set_group_display(&mut self, group_id: u64, display: u32)

Put group_id in display’s lane before the shell’s next Self::set_lanes, so the display a window opens on owns it from the first frame.

pub fn lanes(&self) -> Vec<StripLane>

The lanes this strip is partitioned into; empty for one continuous row.

pub fn is_partitioned(&self) -> bool

Whether the strip is partitioned across displays.

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

The shown group a left press at the remembered cursor lands in; mouse buttons carry no position of their own.

pub fn covers(&self, p: Point) -> bool

Whether logical point p is over this strip: inside one of its lanes when it is partitioned, else within its row’s band.

pub fn lane_of_group(&self, group_id: u64) -> Option<usize>

The lane group_id is laid out in; None when the strip is one continuous row or the group isn’t in it.

pub fn output_of_group(&self, group_id: u64) -> Option<u32>

The display group_id is laid out on, when the strip is partitioned.

pub fn lane_at(&self, p: Point) -> Option<usize>

The lane under logical point p, else the lane nearest to it horizontally. None for one continuous row.

pub fn set_focus_output(&mut self, output: u32)

Point keyboard-driven panning (direct strip pans, the visible span launches consult) at the lane of display output.

pub fn output_pan(&self, output: u32) -> Option<&Pan>

The pan of display output’s lane, when the strip is partitioned.

pub fn usable_at(&self, x: f64) -> f64

Usable width a group at canvas-x x resolves its width fraction against: canvas, not screen, so panning never resizes windows. Falls back to the row’s width less the leading gutter, then the default.

pub fn alone_per_group(&self) -> Vec<bool>

Per group, in strip order, whether it has its run of the strip to itself: a lone window at the default width takes it, so a neighbour closing widens it and a new one narrows it again.

pub fn usable_per_group(&self) -> Vec<f64>

Per-group usable width in strip order, from stored widths and pushed spans alone, so it is stable on the first frame.

pub fn group_canvas_spans(&self) -> Vec<(u64, f64, f64)>

Each group’s (id, left, right) in unscrolled canvas space, derived like the usable width so a group spliced in this frame already has a span; on a partitioned strip each lane’s canvas starts at its display’s edge.

pub fn onscreen_group_ids(&self) -> Vec<u64>

Ids of groups currently visible, read off laid-out rects: “can I see it” is about pixels, so a group with no rect yet reads as not on screen.

pub fn visible_canvas_span(&self) -> (f64, f64)

The visible viewport shifted by the pan, in the same space as the group canvas spans; on a partitioned strip, the focused display’s lane.

pub fn group_ids_on(&self, output: u32) -> Vec<u64>

Ids of the groups laid out on display output, in order. Every group when the strip is one continuous row.

pub fn group_ids(&self) -> Vec<u64>

Used by the shell’s resync_strips_from_tree to diff against the persisted window groups, keeping host state across an unrelated revision bump.

pub fn insert_group(&mut self, group: WindowGroup, idx: usize)

Inserting anywhere but the end pushes later groups along: the motion is armed here and measured by the next layout pass.

pub fn share_with_neighbour(&mut self, group_id: u64) -> bool

Make room for a window that just opened, beside the one it opened to the right of, else the one after it: two that don’t fit share the display, and when no share leaves both usable the strip scrolls instead. New widths are stamped as pending changes.

pub fn reorder_group_by_id(&mut self, id: u64, idx: usize) -> bool

Move one existing group to its persisted strip position without publishing a user drag. Shell reconciliation uses this after a remote/document revision changes the order: keeping the original WindowGroup instance preserves its tab hosts, focus and in-flight presentation state.

pub fn shift_offset_for(&self, group_id: u64) -> f64

How far right of its laid-out position group_id should be painted this frame (negative = left). The stored rect is always the final one, so hit-testing and the app’s configure size are never mid-flight — same choice the per-group spawn fade makes.

pub fn hold_shift_at(&mut self, elapsed: Duration) -> bool

Freeze the in-flight slide at elapsed, reporting whether there was one to freeze. The curve runs on wall time, but an offscreen render costs far more wall time per frame than the curve lasts, so a capture harness stepping frames would only see start and end — this lets it request a specific point (still production draw, not a reconstruction). Not gated on debug_assertions: shots walks scenario timelines through this and ships in release.

pub fn set_shown_elsewhere(&mut self, ids: Vec<u64>)

Say which groups another surface is drawing for now (the overview’s flight carries their pictures); the row leaves them out until they are handed back with a set that no longer names them.

pub fn remove_group_by_id(&mut self, id: u64) -> bool

pub fn scroll_x(&self) -> f64

How far the row is panned. On a partitioned strip, the leading lane’s pan (the one carrying the leading gutter); see Self::output_pan for any other display.

pub fn viewport(&self) -> Rect

The area the row is shown in, as last laid out. On a partitioned strip, the leading lane’s, as Self::scroll_x.

pub fn set_scroll_quantum(&mut self, quantum: Option<f64>)

Select the presenter’s strip-pan precision: the drawn pan lands on multiples of quantum layout pixels (1 / scale puts it on whole device pixels), or exactly where the gesture put it with None, the default. A quantum that is not finite and positive is ignored.

pub fn drawn_scroll_x(&self) -> f64

The pan used by layout, input geometry and the presenter’s canvas.

pub fn drawn_bounds(viewport: Rect) -> Rect

Where a strip whose viewport is viewport draws: the viewport and a 16 px pad above and below it that keeps shadow and glow sprites (ambient_pad=50, bloom_pad=120, see TileHost::draw_steady_state) intact at the top and bottom.

pub fn canvas_shift(&self) -> f64

How far a retained draw moves the row into canvas coordinates (crate::retained_present::unbake_scroll): the drawn pan plus the canvas’s padding while it lies within the canvas, zero outside a retained draw.

pub fn canvas_pad(&self) -> f64

Room a retained canvas keeps left of the content and right of the furthest pan, in layout pixels.

pub fn frame_presented(&mut self)

A frame was presented: each group may step its width spring once more. The token a step spends returns when the group is marked drawn, but a host that presents frames without marking its content drawn (the compositor) must say so here, or every width spring it does not snap stops after its first step while its group keeps asking for animation frames.

pub fn pan_to(&mut self, requested: f64) -> bool

Set the real strip viewport to an absolute finite offset. Browser and other external navigation controllers use this narrow seam instead of synthesizing wheel input or moving rendered output independently.

pub fn inherit_viewport(&mut self, previous: &GroupRow)

Carry peer-local viewport presentation through a retained hierarchy rebuild. The next layout still validates/clamps against its new geometry.

pub fn group_for_focus_target( &self, target: NodeId, tree: &TaffyTree, ) -> Option<u64>

Resolve an admitted keyboard owner through its actual layout ancestry. Stored layout identities prevent stale child indices after a splice.

pub fn group_layout_is_current(&self) -> bool

Whether the stored geometry still belongs to the current group order. A splice/reorder must complete layout before a host frames its selection.

pub fn handle_count(&self) -> usize

pub fn handle_at(&self, idx: usize) -> Option<&ResizeHandle>

pub fn group_at_for_test(&self, idx: usize) -> Option<&WindowGroup>

debug_assertions gated so it’s available to crates/sdk/ui-core/tests but not shipped in release.

pub fn content_width(&self) -> f64

0.0 before the first layout pass. On a partitioned strip, the focused lane’s.

pub fn max_scroll_x(&self) -> f64

pub fn pan_max_scroll_x(&self) -> f64

Furthest legal resting offset for direct strip panning. Unlike the content-tight focus bound, this leaves a deliberate glimpse of canvas after the final app. Content which already fits stays pinned at home.

pub fn begin_strip_pan(&mut self)

Rebase total-travel updates onto the strip’s current visual position. A fresh axis lock calls this even if a prior stream lost its End at a lock/session boundary, preventing stale gesture state from jumping. On a partitioned strip only the focused display’s lane pans.

pub fn update_strip_pan(&mut self, travel: f64, at: Instant) -> bool

Track a three-finger horizontal gesture in direct-manipulation space. travel is total signed scroll travel since Begin (positive moves toward later groups), reported at (the input event’s own time, so a batch drained late keeps its spacing). Legal canvas tracks 1:1; beyond either end the shared iOS-style curve supplies increasing resistance. Each frame shows the travel resampled at the frame’s time, so a steady swipe moves the strip evenly whatever the touchpad’s report rate.

pub fn hold_strip_pull(&mut self, requested: f64, at: Instant) -> bool

Hold the strip under a pan that reports where it is, not fingers: at requested, an offset that may lie past either end, shown 1:1 within the strip and against the rubber band beyond it, at once and with nothing to resample. A wheel gesture calls this with each event’s total and lets go with Self::cancel_strip_pan, so a pull past an end springs back as a released trackpad pan does.

pub fn end_strip_pan(&mut self, now: Instant) -> bool

Release direct manipulation at now. A strip released at rest stays exactly where the fingers left it; a thrown one coasts on with their velocity (not under reduced motion); elastic overpull settles to its end.

pub fn cancel_strip_pan(&mut self, now: Instant) -> bool

Cancel direct manipulation at now: the strip stays where it is, thrown nowhere, and only elastic overpull settles to its end.

pub fn hold_strip_pan(&mut self)

Keep the strip where a person’s pan left it, bounded as Self::pan_to bounds it, until focus next pans a window into view. A wheel spin stops wherever its notches took the strip, often with windows cut at both edges.

pub fn group_is_laid_out(&self, group_id: u64) -> bool

Whether a layout pass has given group_id its place. A group focused the same frame it was spliced in has none yet, so a pan to it has nothing to aim at. A window opening has its place from its first layout, while its slot still grows from nothing: a reveal aims at where it will be once grown (Self::scroll_target_for), so the strip pans as the window opens rather than once it has some width.

pub fn scroll_group_into_view(&mut self, group_id: u64) -> bool

Pan group_id’s run (the row, or its display’s lane) so the group is fully inside the viewport (Niri’s “focused column follows into view”). Call after a layout pass (it uses the group’s live rect). Cancels any in-flight wheel-snap so a snap-back does not override it.

pub fn scroll_group_into_view_animated( &mut self, group_id: u64, now: Instant, source: MotionSource, ) -> bool

Same target as Self::scroll_group_into_view, moved as source asks. After a pointer or gesture it glides on the group-move spring instead of teleporting, so a focus jump reads as motion rather than a cut, and a run of jumps (a spun wheel) as one motion that keeps its speed. After a shortcut or action the content is already where it belongs and only the viewport slides, within fast, to say where it went.

pub fn set_motion_source(&mut self, source: MotionSource)

Say what starts the transitions laid out next: a shortcut or action lands its result on the next frame (groups take their new slots, widths and maximized rects at once; siblings and tab chips do not fade), while a pointer or gesture keeps the full motion. The host sets it before acting and returns it to MotionSource::Pointer once the layout showing the result has run.

pub fn motion_source(&self) -> MotionSource

pub fn scroll_groups_into_view_animated( &mut self, keep: u64, also: u64, now: Instant, source: MotionSource, ) -> bool

Pan so that keep and also are both wholly in view when they fit on screen together, else just keep; glided like Self::scroll_group_into_view_animated. For a window that opened beside the one the person is in without taking their focus: both are shown, and if they cannot be, the person keeps what they were looking at. false when neither has been laid out in one lane or nothing has to move.

pub fn groups_cut_by_row_edges(&self) -> Vec<u64>

Ids of groups the viewport edges are cutting through right now. Empty when everything fits; otherwise the ones hanging off the ends, which is normal.

pub fn set_group_active_tab(&mut self, group_id: u64, tab_id: u64) -> bool

Select tab_id inside group_id widget-side. The bar’s active_id is authoritative and the shell’s per-frame harvest mirrors it into the persisted tree, so a tree-only write would be overwritten a frame later.

pub fn tick_snap_at(&mut self, now: Instant)

Split out from apply_layout so headless tests can advance simulated time deterministically without staging a full taffy tree. Advances every run’s snap.

pub fn direct_pan_in_progress(&self) -> bool

A direct pan is under the fingers, or settling after them.

pub fn set_scroll_x_for_test(&mut self, x: f64)

Leave the pan at x as a person’s own pan would.

pub fn transfer_tab( &mut self, src: usize, dst: usize, tab_id: u64, target_idx: usize, ) -> bool

Exposed separately from handle_event so tests can drive a transfer without staging a full winit event.

pub fn gap_index_for(&self, release_point: Point) -> Option<usize>

Some(gap_idx) if the release landed strictly between two groups (0 before the first, N after the last); None inside a group’s rect. Deliberately not y-band-restricted: the release comes from our own row’s TabBar, so anywhere that isn’t on a group is a new-window gap.

pub fn split_tab_into_new_group( &mut self, src: usize, tab_id: u64, gap_idx: usize, ) -> bool

Detach tab_id from src into a brand-new WindowGroup at gap_idx, pruning src if that leaves it empty.

pub fn take_pending_topology_change(&mut self) -> Option<Vec<GroupShape>>

Drain the current row topology after a same-strip tab transfer. Returning the final shape rather than a sequence of move events makes multiple transfers in one frame idempotent at the persistence boundary.

pub fn take_pending_cross_strip_detach(&mut self) -> Option<CrossStripDetach>

pub fn take_pending_group_reorder(&mut self) -> Option<(u64, usize)>

pub fn group_drag_active(&self) -> bool

pub fn group_reorder_target(&self) -> Option<usize>

pub fn tab_drop_target(&self) -> Option<DropTarget>

The target whose indicator is currently on screen for a tab drag.

pub fn cancel_tab_drag(&mut self) -> bool

Cancel owned tab gestures and their in-strip drop feedback.

pub fn tab_drag_active(&self) -> bool

Whether one of this row’s own tab bars currently owns a drag.

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

The tab one of this row’s tab bars is dragging, while one is.

pub fn cross_strip_drop_target(&self) -> Option<DropTarget>

The exact destination currently painted for a tab from another strip.

pub fn set_cross_strip_tab_drag_hover(&mut self, cursor: Option<Point>)

Preview a tab arriving from another strip. The stored enum is later consumed verbatim by the shell’s cross-strip commit path.

pub fn set_external_content_drag_hover(&mut self, cursor: Option<Point>)

Drive the same preview for content carried by the compositor rather than by one of this row’s tabs. None retires the indicator when the protocol drag leaves or finishes.

pub fn tab_drop_target_at(&self, p: Point) -> Option<DropTarget>

Resolve one pointer position into the strip’s complete tab-drop grammar. The tab bar wins and keeps its precise pill-gap insertion; in the body, adaptive outer bands make a new group while the interior prepends or appends to the existing group’s tab list. Only space outside every group can otherwise produce a new group.

pub fn pointer_over_background(&self) -> bool

Whether the pointer is over canvas no window covers.

pub fn pointer_over_chrome(&self) -> bool

Whether the pointer rests on the strip’s own chrome rather than in a window’s content: canvas, or a window’s bar, where no app of the strip can scroll what a wheel turns. A seam a resize takes is neither.

pub fn accept_cross_strip_drop( &mut self, new_id: u64, desc: TabDescriptor, host: TileHost, target: DropTarget, ) -> bool

Apply the exact target already previewed by this destination row. Returns false for a stale group id so the shell can restore the detached payload to its source without losing its live host.

pub fn restore_cross_strip_detach(&mut self, payload: CrossStripDetach)

Restore a detach whose durable cross-strip transaction was refused. The original group and position win; this path must be visually a no-op.

impl GroupRow

pub fn layout_node(&self) -> Option<NodeId>

The row’s node in the retained layout tree, while it has one.

Trait Implementations

impl CollaborationTopology for GroupRow

fn collaboration_children_mut(&mut self) -> Vec<&mut dyn Widget>

impl ComponentLifecycle for GroupRow

fn close_components(&mut self) -> Vec<ComponentCloseReport>

Capture and close nested components before removing their live trees, transferring all recovery reports to the caller.

fn take_component_close_reports(&mut self) -> Vec<ComponentCloseReport>

Drain inert close-report ownership once; never invoke ordinary app callbacks through a closed component.

fn unsaved_documents(&self, doc: &AutoCommit) -> Vec<UnsavedDocument>

App-declared external document obligations. An in-memory record set is not evidence that an editable file has been saved.

fn checkpoint_components(&mut self) -> Vec<String>

Non-destructive persistence checkpoint. Never closes a wake scope or removes a tree; a failed host close must leave every child usable.

fn finish_admitted_close(&mut self) -> Vec<ComponentCloseReport>

Only the host may call this after every checkpoint succeeded, without dispatching another document mutation in between.

fn on_window_close_requested(&mut self) -> WindowCloseAdmission

Admit or defer the primary native window’s ordinary close request. Roots that defer must later produce a one-shot close intent.

fn take_window_close_intent(&mut self) -> bool

One-shot approval after an earlier deferred ordinary window close.

fn take_replacement(&mut self) -> Option<ComponentReplacement>

The component this root’s own component asked to show in its place (AppComponent::take_replacement), for the host that mounted it. A component nested deeper answers to the host that mounted it, so the default reaches no child.

fn take_save_status_presentation(&mut self) -> bool

One-shot: the durability of this root’s own component’s record changed since this was last asked, and the root already synced with the new state. A host that asks (an App) presents it with a frame of its own, not a rebuilt tree; one that does not ask sees it through take_structure_dirty.

impl FloatingSurfaceProvider for GroupRow

fn on_floating_surface_focus_changed(&mut self, id: Option<&str>, focused: bool)

Route native keyboard focus to the exact presentation instance.

fn on_floating_surface_ime_source_changed(&mut self, id: Option<&str>)

Keep the exact secondary presentation’s editor logically focused while the platform deliberately retains text-input focus on its source. A host-authenticated input route, not a claim by the app; the host clears it when the continuation ends or no longer validates.

fn on_floating_surface_event_source(&mut self, id: Option<&str>)

Identify the native surface delivering the current input event. The host resets this immediately after dispatch; it grants no authority.

fn floating_surface_event( &mut self, id: &str, event: &WindowEvent, ctx: &mut EventCtx<'_>, ) -> bool

Deliver one input event aimed at the card id, in the desk’s coordinates: the frame the card’s hits were recorded in. Answers whether the card took the event.

fn floating_surface_accessibility(&self, id: &str) -> Option<AccessNode>

The retained semantic subtree presented in one secondary window.

fn perform_floating_surface_accessibility_action( &mut self, id: &str, target: &str, action: &Action, state: &mut Edits<'_>, path: &ExId, ) -> bool

fn floating_surface_ime(&self, id: &str) -> Option<(InputContent, Rect)>

IME content type and desktop-logical caret rect for one secondary window.

fn take_floating_surface_request(&mut self) -> Option<FloatingSurfaceRequest>

One-shot request to hand app content to the shared floating-surface host. Shell and in-app hosts consume the same description, so PiP does not require a second rendering/widget API.

fn take_capture_studio_request(&mut self) -> Option<CaptureMode>

One-shot request for the session shell’s shared capture/PiP chooser.

fn take_floating_surface_source_updates(&mut self) -> Vec<(String, Rect)>

Rising-edge source-geometry updates for an adopted floating surface.

fn draw_floating_surfaces( &mut self, scene: &mut Scene, transform: Affine, text_renderer: &mut TextRenderer, theme: &Theme, presence: &PresenceCtx, )

Paint app-owned content whose presentation has moved into shell space.

fn draw_floating_surface( &mut self, id: &str, scene: &mut Scene, transform: Affine, text_renderer: &mut TextRenderer, theme: &Theme, presence: &PresenceCtx, ) -> bool

Paint exactly one app-owned presentation into its native window. Native secondary windows are independent buffers: painting the plural overlay pass into each would duplicate sibling surfaces and let content escape the window’s own clip.

fn set_floating_surface_bounds(&mut self, bounds: Rect)

Push the shell’s authoritative combined-output bounds into the owner.

fn floating_surface_presentations(&self) -> Vec<FloatingSurfacePresentation>

Desktop-space presentations that need a native secondary window.

fn active_floating_surface_ids(&self) -> Vec<String>

Stable IDs whose underlying activity still exists.

fn on_floating_surface_host_message( &mut self, message: &FloatingSurfaceHostMessage, )

Deliver an acknowledged shell lifecycle edge back to the owner.

impl Widget for GroupRow

fn next_wake_deadline(&self) -> Option<Instant>

A group the latest frame left unpainted (outside the row) had that frame for every deadline due by its sync. One still pending waits for the group’s paint (a status pill that clears itself when drawn), so it must not wake the host every frame; its later deadlines (an alarm, a poll) still wake it.

fn draw_overlay( &mut self, scene: &mut Scene, transform: Affine, text_renderer: &mut TextRenderer, theme: &Theme, presence: &PresenceCtx, )

Each window’s top layer, in Self::children_mut’s order as the default draws it, noting which windows put anything there (Self::overlay_groups).

fn for_each_layout_child(&self, visitor: &mut dyn FnMut(&dyn Widget)) -> bool

The windows and the resize handles between them.

fn test_rects(&self) -> Vec<(String, Rect)>

Publish qualified affordances by group id, plus bare aliases for the leftmost group, so single-group scenarios stay unqualified.

fn take_structure_change(&mut self) -> StructureChange

A change a window carries out in place stays in place. The row’s own changes (a slot’s width, a pan’s bounds, a reveal, lanes, a window maximized or restored) restyle the nodes it keeps while its windows are the ones it laid out; a window come or gone rebuilds. Every window’s flag is drained.

fn remount_children(&mut self, remount: &mut Remount<'_>) -> bool

Lay the row out again in the nodes it keeps, as Widget::build_layout would: every slot’s spring stepped, every window’s nodes restyled, the seams mounted or let go as windows are maximized and restored, and the row’s children and runs set.

fn provide<'a>(&'a self, request: &mut Request<'a, '_>)

Answer a request for a capability this widget takes part in (see capability). Declare capabilities with crate::provides!.

fn provide_mut<'a>(&'a mut self, request: &mut RequestMut<'a, '_>)

Exclusive counterpart to Widget::provide.

fn modal_capture(&self) -> Option<Rect>

Some(rect) when this subtree holds an open modal, its panel box. While any widget reports Some, the host suppresses its own global focus shortcuts and swallows unhandled pointer presses so nothing behind the modal is clickable. Containers MUST forward (the default does, via first Some among children).

fn set_platform_conventions(&mut self, conventions: PlatformConventions)

Receive host-selected platform conventions. The default propagates to retained children, keeping target-OS branches out of app code.

fn set_interaction_environment(&mut self, environment: InteractionEnvironment)

Receive the host’s current input capabilities. The default propagates through retained containers, so app code does not need device branches.

fn mount_native_views(&mut self, host: &NativeViewHost<'_>)

Attach native child views through this owner’s retained lifecycle topology. Presentation containers with inactive or hidden live descendants override this traversal so lifecycle ownership stays independent of drawing and input visibility.

fn unmount_native_views(&mut self)

Tear native children down while their parent window still exists.

fn native_view_frame_start(&mut self)

Begin a native-view frame through this owner’s retained lifecycle topology.

fn children(&self) -> Vec<&dyn Widget>

fn children_mut(&mut self) -> Vec<&mut dyn Widget>

fn for_each_child(&self, visitor: &mut dyn FnMut(&dyn Widget))

Allocation-free read-only child traversal. Existing custom containers inherit a compatibility adapter over Self::children; toolkit containers override this to walk their retained storage directly.

fn as_any(&self) -> Option<&(dyn Any + 'static)>

Downcast to the concrete widget, for hosts and tests that reach a known widget through dyn Widget. Default None (a widget may borrow and so not be 'static); a widget opts in with Some(self), and a Decorator answers itself.

fn as_any_mut(&mut self) -> Option<&mut (dyn Any + 'static)>

fn sync(&mut self, state: &(dyn Any + 'static), root: &(dyn Any + 'static))

Pull model state into this widget before layout. The default syncs the children Widget::children_mut returns; a widget overrides it only to read state of its own, or to sync children it does not expose there.

fn update( &mut self, state: &(dyn Any + 'static), root: &(dyn Any + 'static), ) -> bool

Notice, between frames, state outside the document (a chrome revision, a momentum scroll still ticking) and report whether anything changed. The default updates every child Widget::children_mut returns without short-circuiting, so a container never freezes its descendants; an override checks state of its own and forwards.

fn composition_follows_allocation(&self) -> bool

Whether this widget composes its children from the size it was last allocated (it reads its own rect while building its layout: a compact layout under a width, a count of columns, an inset from a drawer). A window resize then needs a second composition against the new allocation, as well as the re-solve every resize gets. Widgets that compose independently of their allocation, or that report take_structure_dirty themselves when a new allocation changes what they show, keep the default: a resize re-solves the retained tree in place instead of recomposing all of it.

fn build_layout( &mut self, taffy: &mut TaffyTree, theme: &Theme, node_map: &mut HashMap<NodeId, *mut dyn Widget>, ) -> NodeId

fn apply_layout(&mut self, taffy: &TaffyTree, node: NodeId, origin: Point)

Take the geometry layout gave this node. The default keeps none, for widgets that neither draw nor hit-test.

fn draw( &mut self, scene: &mut Scene, transform: Affine, tr: &mut TextRenderer, theme: &Theme, presence: &PresenceCtx, )

Paint into scene. The default paints nothing.

fn handle_event(&mut self, event: &WindowEvent, ctx: &mut EventCtx<'_>)

Handle one input event with the runtime services for this retained node.

fn name(&self) -> &'static str

fn accessibility(&self) -> Option<AccessNode>

Role, name/description/value, and AccessState. Default None means presentational: the node is skipped and children reparent onto the parent. State must be derived, not stored so it can’t drift from draw; names must already be i18n!-resolved.

fn get_rect(&self) -> Rect

The rectangle this widget occupies. The default, for widgets that keep no geometry, is empty.

fn wants_pointer_capture(&self) -> bool

fn cursor_shape(&self, point: Point) -> Option<CursorIcon>

point is logical coords, same space as Widget::get_rect; None defers to the default arrow. The host hit-tests the whole tree via node_map and picks the smallest-area claim, so containers need not override this.

fn needs_redraw(&self) -> bool

Default false (clean). A widget is clean until something it reads changes: a leaf that keeps state says so by tracking a dirty: bool (set in handle_event/sync, cleared in mark_drawn()), and one that paints from the people on the document reads the frame’s presence (crate::presence::frame::frame). Containers MUST forward: dirty iff any descendant is.

fn mark_drawn(&mut self)

Called after this widget’s scene lands in the composed frame, to clear a dirty flag. Default forwards to children.

fn needs_animation_frame(&self) -> bool

App polls this in Event::AboutToWait; without it a curve would freeze until an unrelated event woke it.

fn take_structure_dirty(&mut self) -> bool

True if this subtree’s structural composition changed since the last frame; reading clears it. The default drains every retained child and reports whether any was dirty.

fn native_input_snapshot( &self, _state: &(dyn Any + 'static), _path: &(dyn Any + 'static), ) -> Option<Value>

Read-only state evidence for opt-in scheduled native input diagnostics. Called only around diagnostic inputs, never during ordinary input or paint. Keep this inexpensive and root-local; snapshots may be logged verbatim. This verifies widget state, not rendered pixels or display presentation.

fn view_only_scroll(&self, _event: &WindowEvent) -> bool

Opt in only when this wheel event changes scroll geometry and nothing else: no document edit, focus or selection, action availability, resource declaration, pending command or work that requires sync. The runner still lays out, paints and refreshes accessibility geometry; unknown handlers stay on the full path.

fn primary_vertical_scroll(&self) -> Option<PrimaryScrollRegion>

Explicit app-owned region; never search secondary children implicitly.

fn apply_primary_vertical_scroll( &mut self, _action: PrimaryScrollAction, ) -> PrimaryScrollResult

fn callback_binding(&self) -> Option<CallbackBinding>

Runtime binding inherited by descendants in a matching layout topology.

fn has_separate_document_owner(&self) -> bool

Whether this widget introduces a document owner distinct from the runner’s outer State. This is a compatibility check, never identity or authority for history access or restore.

fn history_owner(&self) -> Option<HistoryOwner>

Opaque actual custody for framework History source registration.

fn record_owners(&self) -> Vec<HistoryOwner>

Records this widget keeps open beside the document it shows, each synced on its own route: a framework app’s records in the person’s own workspace (crate::record::person). They take no part in this widget’s history or controls.

fn set_window_bar_control(&mut self, in_bar: bool)

Tell this widget whether it stands in a window bar. A bar’s controls are drawn at the bar’s control height whatever the pointer; the target a finger needs reaches beyond the drawn shape, invisibly. The default propagates to children.

fn settle(&mut self, edits: &mut Edits<'_>, path: &ExId)

Apply, after the sync pass, what the widget took up there and must write: a worker’s answer, a chooser’s file, an event a child queued. Writes go only through typed actions on edits; the host syncs again when the document changed. The default settles the returned children.

fn measure( &mut self, _known: Size<Option<f32>>, _available: Size<AvailableSpace>, _text_renderer: &mut TextRenderer, ) -> Size<f32>

fn layout_info(&self) -> Option<LayoutInfo>

Read-only resolved decisions for widgets with an explicit layout policy. None means the widget has no such policy; ordinary manual widgets remain valid. Values are available after build/settlement and carry real origins.

fn adjust_layout_style( &mut self, _taffy: &mut TaffyTree, _node: NodeId, _text: &mut TextRenderer, ) -> bool

Adjust this node’s style using its allocated size, before final geometry is applied. Return true only when the style changed (or an inherited decision child hooks read). An override may measure its owned children through ordinary references, entering their callback binding when present. Never reenter descendants through the raw node map while borrowing their parent, change topology, or build another layout tree. The shared host solver visits every registered widget, repeats layout at most eight times and skips a frame that does not settle.

fn observe_physical_input(&mut self, _input: PhysicalInput)

Observe this app’s ordinary foreground physical input before framework shortcuts consume it. Keep feedback ephemeral; this is not an input grant.

fn for_each_child_in_clip(&self, visitor: &mut dyn FnMut(&dyn Widget))

The children of Self::for_each_child that may paint inside the layout_clip in effect: what a scroll view’s damage and copy plan need. Every child by default; a long column visits only those near the clip, so a frame costs what is shown, not what the column holds.

fn for_each_hosted_child(&self, _visitor: &mut dyn FnMut(&dyn Widget))

Children this widget keeps in the retained tree but does not route input to: a subtree it does not own and answers the person’s events for itself, like a host drawing another widget’s card over the windows. Inspection, named controls and the accessibility tree walk these after the children Self::children lists, so what is walked there keeps the paths, sibling indices and registry entries it had.

fn test_id(&self) -> Option<&str>

Stable id for the e2e test harness; None falls back to a path-based key. Must be unique across the live tree — the registry resolves on first match, so a duplicate shadows the second occurrence.

fn window_slot(&self, _id: String) -> Option<ToolbarAction>

This control as an action of the window’s bar, sent back as id (crate::window_toolbar::ToolbarAction): a button’s icon and name. None for anything that is not a button.

fn stands_for(&self, address: *const ()) -> bool

Whether this widget is the one at address, or stands in the tree for it: a Decorator stands for every widget it wraps, so a scroller drawn inside one is found where the decorator is (crate::scroll_copy::offer).

fn focus_reveal_context(&self) -> Option<Rect>

Context that should remain visible with a focused descendant, such as a form control and its validation message. Opt-in scroll containers use this block when it fits; otherwise they prioritise the control.

fn reveal_descendant(&mut self, target: *const dyn Widget) -> bool

Reveal a newly keyboard-focused descendant inside any enclosing viewport. Containers override this to scroll; ordinary widgets simply recurse toward the target and report whether it was found.

fn child_clip_rect(&self) -> Option<Rect>

Absolute logical clip applied to ordinary children during painting and pointer routing. Inspectors and enclosing scroll regions must respect this boundary instead of treating clipped descendants as visible extent.

fn snap_points(&self, axis: ScrollAxis, out: &mut Vec<f32>)

Offsets along axis that this widget, as a scroll view’s content, offers it to settle on, measured from its own leading edge: a board’s lanes (crate::widget::Board). None leaves a scroller stopping wherever the hand left it.

fn take_action_palette_request(&mut self) -> Option<ActionAddress>

One-shot request to open the host’s action palette directly at a typed resource action. Parameter collection and permission checks remain host policy; widgets only name an address already present in resources().

fn take_search_request(&mut self) -> bool

One-shot request to open the host’s search palette, the same one the platform search shortcut opens. An app’s own search button latches it so search stays one shared host surface rather than an app overlay.

fn claims_raw_touch(&self, _point: Point) -> bool

Opt out of touch-to-pointer emulation for contacts that begin at point (logical coords, same space as Widget::get_rect).

fn touch_claim(&self, _point: Point) -> TouchClaim

What a one-finger contact that begins at point (logical coords) means here, when a drag moves something rather than scrolling.

fn tooltip(&self) -> Option<&str>

Revealed after a dwell over the widget’s rect, via the toolkit’s one tooltip mechanism (crate::widget::tooltip::TooltipHost), hit-tested like cursor_shape so containers need not forward it. An icon-only control should also use this as its accessible name.

fn tooltip_side(&self) -> TooltipSide

Which side of the control its tooltip goes: below by default, beside it for a control in a vertical rail.

fn tooltip_target_at(&self, point: Point) -> Option<(Rect, String)>

fn is_focusable(&self) -> bool

fn is_default_keyboard_focus(&self) -> bool

Preferred control when its app is explicitly activated without a valid saved control. Hosts still enforce visibility, enabled state and scope.

fn keyboard_input_scope(&self) -> Option<u64>

Exact app instance whose non-text shortcuts this subtree owns when activation has no control target. Unbound desktop chrome may declare the active tab; component boundaries default to their captured owner.

fn set_focus(&mut self, _focused: bool)

fn set_full_bleed(&mut self, _full_bleed: bool)

The window holding this content fills its display (a maximized window): it has nothing beside it to round its corners against or to set it apart from, so content that frames or clips itself to the window’s shape draws edge to edge instead. A client surface drawn that way, last and unclipped, is one the display can scan out directly. Content that frames nothing ignores it.

fn set_invalid(&mut self, _invalid: bool)

The form’s validation verdict for this control, set by Field::with_error: an invalid control edges itself in danger ink and reports invalid to assistive technology. Controls without a field face ignore it.

fn focus_requested(&mut self, target: Option<NodeId>, tree: &TaffyTree)

An explicit runner focus request, after resolving the actual keyboard owner. Retained flags and layout restoration are not user gestures. Containers can observe this to reveal the owning viewport.

fn is_focused(&self) -> bool

fn context_menu_anchor(&self) -> Option<Rect>

The box a context menu opened from the keyboard stands against: the item that has the keyboard, so the menu opens under it rather than under the whole widget. A widget that holds items (a list) answers for the one with the keyboard; None leaves the menu to stand under the focused widget’s own box.

fn wants_tab_input(&self) -> bool

Whether a focused widget owns Tab instead of the host’s focus traversal. This is deliberately opt-in: ordinary form fields and controls retain platform-standard Tab/Shift+Tab navigation, while a code editor or terminal can receive the key for indentation or completion. A widget around the focus may claim it too: a sheet that walks its own controls with Tab.

fn ime_cursor_rect(&self) -> Option<Rect>

Caret rectangle for the platform input method, in window-logical coordinates. Returning Some enables IME for the focused widget and positions its candidate window; non-text controls keep the default None and therefore disable IME.

fn traps_focus(&self) -> bool

While any widget answers true, the host restricts Tab/directional focus to this subtree (wrapping at the ends) and restores the prior focus once it goes back to false. Default false.

fn scopes_keyboard_focus(&self) -> bool

Whether Tab and directional focus travel stay inside this subtree while no trap holds focus: the content of the focused desktop window, so keyboard travel cycles through the app the person is in and never wanders onto the desktop’s chrome (its bars, menus and window titles), which the keyboard reaches through its own shortcuts. Unlike Self::traps_focus it moves no focus when it starts or ends, and pointer input is unaffected. Default false.

fn take_app_activation(&mut self) -> Option<u64>

One-shot (reading MUST clear it): the app instance the person just brought forward (a window they opened, clicked or switched to), whose keyboard focus the host restores, or puts on its default control, so what they type next reaches it. Default forwards the first request found among the children.

fn take_focus_request(&mut self) -> Option<String>

One-shot (reading MUST clear it): the test id of the control this subtree asks to take the keyboard once the runner laid it out, such as the first field of a view a person’s press just opened, so what they type next lands there. The runner focuses it as a press focuses a control, blurring any other; a control it does not find (or that takes no focus) leaves focus where it is. Default forwards the first request found among the children.

fn accessibility_shared(&self) -> Option<SharedAccessNode>

Self::accessibility with its synthetic children shared, for a widget that keeps them between frames: each child it did not change is handed over as the very Arc of the last frame, which the semantic tree takes as unchanged without copying or comparing it.

fn accessibility_hidden(&self) -> bool

Whether Self::accessibility reports this subtree hidden, for a host that asks it of every node to prune focus traversal. Widgets whose node is costly to build (text values, per-block children, a translated name) answer without building it: the focus walk asks every widget in the window on every recomputation. Any override must agree with accessibility(); debug builds check it in the walk.

fn accessibility_root(&self) -> Option<AccessNode>

Self::accessibility’s own node with its children left empty: its role, identity (semantic_key) and state. Focus capture and focus order read only these, for every node on every frame, so a widget whose node carries a large subtree (a document exporting its every block) answers without building it. An override must equal accessibility() with children cleared.

fn synthetic_accessibility_rect(&self, _path: &[usize]) -> Option<Rect>

Geometry for an immediate-mode semantic child from AccessNode::children. The path is its child-index path beneath this widget’s accessibility node. Returning a rect lets AccessKit activation inject the same click as pointer input.

fn focus_synthetic_accessibility(&mut self, _path: &[usize]) -> bool

Move this widget’s own immediate-mode focus to a synthetic semantic child. Retained widgets continue to use the ordinary taffy focus path.

fn accessibility_child_parent(&self, _child_index: usize) -> Option<usize>

Reparent one retained children entry beneath a synthetic child returned by accessibility. The returned index addresses AccessNode::children for this frame. Collections use this to place a real interactive row delegate inside its virtual ListItem/TreeItem instead of exporting a duplicate.

fn accessibility_child_path(&self, child_index: usize) -> Option<Vec<usize>>

Reparent one retained children entry beneath a nested path of synthetic children returned by accessibility.

fn accessibility_represents_child(&self, _child_index: usize) -> bool

Whether one retained children entry is already represented in this widget’s own synthetic accessibility tree, so the bridge must not export it a second time. A host that publishes a child’s semantics itself (to add its own controls inside the same dialog) answers true for that child; assistive technology then sees one copy, not two.

fn lays_out_child(&self, _child_index: usize) -> bool

Whether this widget lays one retained children entry out itself (an Embedded part of a painted page) rather than through the window’s layout, which then gives it no node. The accessibility walk reaches such a child, and every widget inside it, through this widget’s node.

fn accessibility_child_description(&self, _child_index: usize) -> Option<String>

What describes one retained children entry to assistive technology, when this widget holds the words for it: a row’s secondary line is its trailing switch’s description. The bridge sets it as that child’s node’s description unless the child describes itself.

fn perform_action( &mut self, _action: &Action, _key_path: &[u64], _state: &mut Edits<'_>, _path: &(dyn Any + 'static), ) -> bool

Perform an accessibility Action on this widget, or on one of its synthetic accessibility nodes. May mutate the CRDT like handle_event.

fn perform_semantic_action( &mut self, target: &str, action: &Action, state: &mut Edits<'_>, path: &(dyn Any + 'static), ) -> bool

Handle an action addressed to a synthetic accessibility child created by this widget. target is the opaque stable value supplied through AccessNode::with_action_target.

fn is_enabled(&self) -> bool

A disabled (false) widget is excluded from focus traversal, must reject input in handle_event, and renders dimmed (see DISABLED_ALPHA).

fn ime_requires_deferred_ack(&self) -> bool

This field needs a host that consumes deferred receipts. Ordinary native Wayland windows must not advertise it until they have that delivery path.

fn ime_refuses_ordinary_commits(&self) -> bool

Ordinary input-method commits (a composing keyboard IME, the on-screen keyboard) cannot reach this field: its text arrives only through deferred receipts (a browser page field), so hosts keep standard text input closed outside a dictation session. A field that needs deferred receipts for dictation but turns an ordinary commit into its own acknowledged edit (Terminal’s native editor) does not refuse them.

fn start_deferred_text(&mut self) -> Option<Receipt>

Begin one bounded deferred session after explicit host consent, preserving the existing original-field fingerprint. This grants no microphone access.

fn commit_deferred_text(&mut self, text: &str) -> Option<Receipt>

A private asynchronous final. None leaves ordinary synchronous IME dispatch to the host. A receipt binds this original field and must be acknowledged before the host releases its private recovery transcript.

fn ime_content(&self) -> Option<InputContent>

The focused widget wants platform text input (Wayland text-input-v3, native IMEs elsewhere). None is intentionally the default: enabling an IME for buttons, canvas tools or games makes the compositor raise an on-screen keyboard over content that cannot accept the committed text.

fn ime_multiline(&self) -> bool

Whether the original focused editor accepts line feeds as text. This is field policy, never inferred from a multiline accessibility presentation. Wrappers inherit only one unambiguous child at their active IME caret.

fn ime_edit_fingerprint(&self, key: &[u8; 32]) -> Option<[u8; 32]>

Opaque local invalidation of deferred input, including selection edits that leave the caret rectangle unchanged. The host supplies an ephemeral secret key; no text or selection is retained in the resulting digest. The default shares the accessibility door and excludes protected or read-only controls. Text controls can override it to avoid cloning text.

fn presented(&self) -> bool

Default true; false only for a widget standing in for a window’s content whose first frame has not drawn. Must latch: once true, never false again for the same content.

fn arrives_from(&self) -> Source

Where this content’s first frame comes from while it has not presented: this device (an app starting here), another device or a host. A frame from this device may hold the window’s first frame up to one frame budget; any other reserves the window’s place and says where it comes from after a while.

fn arrival_progress(&self) -> Option<Progress>

How much of what this content’s first frame waits on has come, when that measures itself (its app downloaded before it starts).

fn arrival_shape(&self) -> SkeletonShape

The shape this content declares for the placeholder standing in for its first frame. Undeclared, the placeholder is the ground alone: nothing guesses what a window will show.

fn text_review(&self) -> Option<(usize, String)>

(caret_byte, text), byte offset on a char boundary. The host diffs this before/after an event so caret-only moves (arrows, Home/End) get announced, not just typing.

fn on_external_event( &mut self, _payload: &str, _state: &mut Edits<'_>, _root: &(dyn Any + 'static), )

Delivers an out-of-band string payload from crate::app::UserEvent::External (e.g. a worker thread streaming output into a status log). Default no-op; the App redraws and re-syncs after dispatch, so mutating state here is enough.

fn on_nav_gesture( &mut self, dir: NavDirection, state: &(dyn Any + 'static), path: &(dyn Any + 'static), ) -> bool

Global back/forward gesture (swipe/edge-pull), recognised by crate::gesture::NavGestureRecognizer and delivered to the whole tree; return true once consumed. Default forwards to children, so a widget that owns history becomes swipe-navigable for free.

fn nav_availability(&self) -> NavAvailability

Which directions Self::on_nav_gesture would consume now. A widget that owns history overrides this beside on_nav_gesture.

fn take_focus_reset(&mut self) -> bool

One-shot (reading MUST clear it) signal to move focus to this subtree’s first focusable widget after the next rebuild. Only consulted under crate::app::App::autofocus_on_structure_change; a wizard raises it on step transitions.

fn take_accessibility_request(&mut self) -> Option<AccessibilityRequest>

One-shot (reading MUST clear it) request to change the window’s accessibility preferences, raised by a control the person used. The host applies it before the next frame. Default forwards the first request found among the children.

fn dev_route(&self) -> Option<RouteSnapshot>

Route history when this widget, or one it contains, is a Router.

fn restore_dev_route(&mut self, route: &RouteSnapshot) -> bool

Put route back. Returns whether a router in this subtree accepted it.

fn appearance_intent(&self) -> Option<AppearanceIntent>

Theme/high-contrast/reduced-motion/scale, polled under crate::app::App::appearance_reconcile — how a settings pane re-themes the running app live without a back-channel. Level-triggered; the App recurses Self::children itself, so containers need not forward it. First Some wins.

fn minimum_window_width(&self) -> Option<f64>

The narrowest this window still works at, in logical pixels: the minimum of its compact layout (a NavShell answers with one column at a time). The host states it to the window system, so the desktop stops a resize there. None: no opinion. The host walks the tree itself (minimum_window_width), so containers need not forward it; the first Some wins.

fn preferred_window_size(&self) -> Option<(f64, f64)>

The whole size this window wants, in logical pixels, when the app is the window’s only content and knows how big it must be: the on-screen keyboard parked to a strip. The host states it as the window’s minimum and maximum, so the desktop shapes the surface to it. None: the window is the user’s and the app lays itself out in whatever it gets.

fn set_motion_reduced(&mut self, reduced: bool)

Apply the effective reduced-motion preference before the host asks this subtree whether it needs another animation frame. The default forwards recursively, making the preference a framework policy instead of an optional convention that every container has to remember to implement.

fn needs_idle_sync(&self) -> bool

Whether sync still needs to run on idle frames without input or collab events — e.g. waiting out a document-adoption grace window.

fn disclosing(&self) -> Option<Disclosing>

While this widget is a band on its way in or out (motion::Disclosure: an in-window banner arriving or leaving), or a content-sized container one moves in, how far what follows it is drawn from where it is laid out. A moving band stands out of the layout; its container places it (Self::place_disclosing) and draws the widgets after it lower by transform, so they move with the band’s edge instead of being laid out again every frame. None at rest (the default).

fn place_disclosing(&mut self, _slot: Rect)

Where a band on its way (Disclosing::Band) stands while it is out of the layout: its slot’s top and width (slot’s height is zero), set by its container after each layout.

fn is_band(&self) -> bool

A band that comes and goes (an in-window banner): when its view stops building it, its column draws it leaving (widget::Disclosing). Its column leaves it out of its identity across rebuilds.

fn note_placement(&mut self, _placement: Placement)

Where a band stands in its column, set by the column after each layout: what it leaves when dropped, so the column a rebuild makes can draw it leaving.

fn animation_detail(&self) -> Option<String>

Why this widget itself asks for animation frames, for diagnostics that name a desktop which keeps painting. None when it has nothing to add to its name and geometry.

fn holds_frame_until(&self, now: Instant) -> Option<Instant>

Until when the frame that would show this subtree waits for data it reads from this device (crate::arriving): a local read that has not answered and is still inside its frame budget. The host keeps the frame on screen until then, or until the data lands, so the person never sees the space empty and then filled. Containers forward (the default does).

fn serve_deadline(&mut self, _now: Instant) -> bool

A deadline this subtree asked for (Self::next_wake_deadline) is due at now: do the work it was for, and say whether anything changed. The default says it did.

fn dismiss_presented_modal(&mut self) -> bool

Close every modal this subtree presents, as its own way out does (a host whose surface is a modal sheet calls it when the shell takes the sheet down). Whether any was presented; containers forward.

fn presents_modal(&self) -> bool

Whether this subtree presents a modal still drawn (arriving, open or leaving): the counterpart of Widget::dismiss_presented_modal.

fn has_pending_visual_work(&self) -> bool

Work already requested by this view whose completion will replace a placeholder. Unlike animations, this can be awaited by still captures.

fn has_transient_feedback(&self) -> bool

Temporary feedback currently presented, such as a save acknowledgement. Captures may intentionally include it; scene-invariance checks can wait for it to disappear separately from unfinished placeholder work.

fn collect_damage(&self, regions: &mut Vec<Rect>)

Logical-pixel bounds whose visual output differs from the last frame.

fn damage_covers_own_box(&self) -> bool

Whether, after this frame’s draw, this widget’s own Self::collect_damage covers every pixel a relayout changed by moving or resizing its layout box: a host that repaints where moved widgets were and are may then leave this widget’s box to it (its children’s boxes still count). A block editor that grew by a paragraph says where its blocks were and are; the default does not claim it.

fn mark_children_drawn(&mut self)

Rest this widget’s children after a frame drew them, for a widget that keeps its own dirty flag: it clears the flag itself, then calls this.

fn release_scene_cache(&mut self)

Release retained encoded-scene storage in this subtree without marking its visual/model state dirty. Outer caches call this after a successful reuse: while the outer display list is authoritative, keeping byte-for-byte descendant encodings only duplicates memory. A later outer rebuild causes descendants to record/cache normally.

fn is_layout_dirty(&self) -> bool

Default true; widgets with a fixed intrinsic size should override to false unless a size-affecting mutation landed. Containers MUST forward: layout-dirty iff any descendant is.

fn layout_needs_measure(&self) -> bool

Whether a layout_dirty frame needs taffy to re-solve sizes (compute_layout) rather than just reposition already-solved boxes. Scrollable is the motivating override: it translates its origin in apply_layout without changing any taffy size, so re-solving on every scroll frame is pure waste.

fn paint_bounds(&self) -> Rect

Everything this widget paints, children included; draw_child skips the draw when it misses the viewport. Override for widgets that paint past their own rect.