Struct VirtualList 

pub struct VirtualList<M>
where
    M: ListModel,
{ /* private fields */ }

Implementations

impl<M> VirtualList<M>

where M: ListModel,

pub fn with_tail_title(self, title: impl Into<String>) -> VirtualList<M>

The title over the list’s tail group: the items done with, after every other group, closed until the person opens it. A list whose model names no tail reads as it did.

impl<M> VirtualList<M>

where M: ListModel,

pub fn on_view( self, id: impl Into<String>, f: impl FnMut(<M as ListModel>::Key) + 'static, ) -> VirtualList<M>

Called with the row chosen: the list, as control id, publishes choosing a row as its view action select (view_choice), each row addressed by its semantic key (Self::with_semantic_key), so a person’s click, a screen reader, a script and an agent choose through the same action. What is chosen is the window’s own state, never an edit.

pub fn on_activate_view( self, id: impl Into<String>, f: impl FnMut(<M as ListModel>::Key) + 'static, ) -> VirtualList<M>

Called with the row opened: the list, as control id, publishes opening a row as its view action open, each row addressed by its semantic key (Self::with_semantic_key), so a person’s second click or Enter, a screen reader, a script and an agent open through the same action. What is shown is the window’s own state, never an edit.

pub fn open_on_press(self) -> VirtualList<M>

A press on a row opens it (Self::on_activate_view), rather than moving the selection onto it and waiting for a second click. The rows of a list that stands for things to open — a task, a folder — open on the press itself, as a tree’s rows do with a single click; the row a keyboard or a reader moves to still only takes the keyboard.

pub fn choosing_on_press(self, choosing: bool) -> VirtualList<M>

A press on a row chooses it. A list whose view reports no choice of its rows is no picker (Self::choosing_on_press(false)): a press moves the keyboard to the row, and nothing shows as chosen, however the rows open.

impl<M> VirtualList<M>

where M: ListModel,

pub fn update_model<R>(&mut self, update: impl FnOnce(&mut M) -> R) -> R

pub fn update_model_changes<R>( &mut self, changes: &[ListModelChange<<M as ListModel>::Key>], update: impl FnOnce(&mut M) -> R, ) -> R

Apply a typed mutation batch to an owned model. Delegates whose stable keys survive structural edits remain live; only RowsChanged keys (or every key for Reset) are rebuilt.

pub fn notify_model_changed(&mut self)

Reconcile a source that mutated through shared interior state.

pub fn notify_model_changes( &mut self, changes: &[ListModelChange<<M as ListModel>::Key>], )

Reconcile a specific batch from a source mutated through shared interior state.

pub fn invalidate_rows( &mut self, keys: impl IntoIterator<Item = <M as ListModel>::Key>, )

impl<M> VirtualList<M>

where M: ListModel,

pub fn with_tree( self, marks: Rc<TreeMarks<<M as ListModel>::Key>>, ) -> VirtualList<M>

The rows stand as a tree: each under the row of the item it names as its parent, indented by the rows over it, with a disclosure on the rows that have subtasks, folding them away where the person folds them. marks is what the rows the list builds read, filled as it mounts them (TreeMarks).

pub fn with_indent_guides(self) -> VirtualList<M>

Draw a hairline up each depth’s gutter through nested rows, so a deep tree keeps its structure legible.

pub fn row_rect(&self, key: &<M as ListModel>::Key) -> Option<Rect>

Where the row of key stands on screen, its own box below the band of a heading it starts a group under. None while the row is not placed (folded away, or far from the box).

pub fn disclosure_rect(&self, key: &<M as ListModel>::Key) -> Option<Rect>

The box the row key’s disclosure takes: the chevron in its own depth’s gutter, centred on the row. None for a row with no subtasks, or one not placed.

pub fn row_depth(&self, key: &<M as ListModel>::Key) -> u32

How many rows under its top row key stands, as the list’s tree shows it.

pub fn row_is_branch(&self, key: &<M as ListModel>::Key) -> bool

Whether the row key has subtasks, a disclosure to show.

pub fn visible_key(&self, nth: usize) -> Option<<M as ListModel>::Key>

The key of the nth row the list shows, counting the rows on screen in reading order: a folded row’s subtasks are not among them, nor a closed group’s rows.

pub fn visible_len(&self) -> usize

How many rows the list shows, counting the rows not folded away.

pub fn is_dragging(&self) -> bool

Whether a drag past the threshold is in flight over the rows.

pub fn row_action_rect( &self, key: &<M as ListModel>::Key, action: usize, ) -> Option<Rect>

Where the hover action action of the row key sits, reordering what the row shows: the centre a person presses.

pub fn fold_row(&mut self, key: &<M as ListModel>::Key, folded: bool) -> bool

Fold the row’s subtasks away, or show them again, as its disclosure, its menu or the keyboard does, and remember what a person folded even for a row whose subtasks the model has not yet said it holds.

pub fn row_folded(&self, key: &<M as ListModel>::Key) -> bool

Whether the row folds its subtasks away now.

pub fn tab_indents(self, enabled: bool) -> VirtualList<M>

Bind Tab / Shift+Tab to indent and outdent the focused row of a tree, as an outliner does. The Alt arrows indent and outdent regardless. Needs Self::with_reorder; a Tab that cannot move the row is left to focus traversal.

pub fn move_row( &mut self, key: &<M as ListModel>::Key, movement: TreeMove, ) -> bool

Move the row of key one step through its tree, through the same validator and commit a drop uses; the row keeps the keyboard and stays in view. Whether it moved.

pub fn move_focused_step(&mut self, movement: TreeMove) -> bool

Move the focused row one step through its tree (TreeMove). Whether it moved: no focused row, a row with the keyboard elsewhere, or a step the tree has no room for moves nothing.

impl<M> VirtualList<M>

where M: ListModel,

pub fn with_context_menu( self, items: impl FnMut(&M, Option<&<M as ListModel>::Key>) -> Vec<MenuItem> + 'static, chosen: impl FnMut(Option<<M as ListModel>::Key>, usize) + 'static, ) -> VirtualList<M>

The menu a press, the Menu key or assistive technology opens: items says what a row (Some) or the list’s empty space (None) offers, and chosen hears the item the person took, with the row it was for. A list offers its rows one menu: this replaces the menu the host opens (Self::with_row_menu_reporter).

pub fn with_row_about( self, about: impl Fn(&<M as ListModel>::Key) -> Option<SharedSelection> + 'static, ) -> VirtualList<M>

Name what each row is about: about answers a row’s key with the selection the app keeps for it (a task’s issue, a note, a file), so a menu opened on that row carries it as its subject — the send-to box beside the menu starts with it, and its box stands at the row. The list only knows the row’s key, so the app names the record.

pub fn with_row_menu_reporter( self, report: impl FnMut(<M as ListModel>::Key, Rect, Point) + 'static, ) -> VirtualList<M>

Report a row’s menu to the host, which opens and paints its own: report hears the row’s key, the row’s box on screen and the point its menu opens at, when a secondary click, the Menu key, Shift+F10 or assistive technology asks for the row’s menu. The row takes the keyboard first, and the list changes no selection: what the menu acts on is the host’s. A list offers its rows one menu: this replaces the menu the list builds (Self::with_context_menu).

pub fn context_menu_is_open(&self) -> bool

Whether the rows’ menu is open.

pub fn close_context_menu(&mut self)

Close the rows’ menu, its chosen item unheard. A list that reports its row menus to the host has none of its own to close.

pub fn open_context_menu( &mut self, key: Option<&<M as ListModel>::Key>, at: Point, ) -> bool

Open the list’s own menu for key’s row (or the list, None) with its corner at at. The row is chosen and given the keyboard first, as a secondary click does. Whether a menu opened: none is offered, or it has no items for that row.

pub fn open_row_menu(&mut self, key: <M as ListModel>::Key, at: Point) -> bool

Open the menu on the row of key, with its corner at at: what a host’s row action does, and what a secondary click does. A list that owns its menu makes the row its selection and focus first; one that reports its row menus gives the row the keyboard and hands its host the box and the point. Whether a menu opened.

impl<M> VirtualList<M>

where M: ListModel,

pub fn on_rename( self, f: impl FnMut(<M as ListModel>::Key, String) + 'static, ) -> VirtualList<M>

Rename a row in place. F2, Self::begin_rename and (with Self::rename_on_double_click) a double click open a field over the row’s label; Enter, a click elsewhere or the list losing focus commit it, Escape cancels. The callback receives the trimmed title; an empty title is dropped. The host applies the rename to its model.

pub fn rename_on_double_click(self) -> VirtualList<M>

Make a double click on a row rename it instead of opening it, as an outliner does. Requires Self::on_rename.

pub fn on_delete( self, f: impl FnMut(<M as ListModel>::Key) + 'static, ) -> VirtualList<M>

Receive Delete on the focused row. The list never removes a row itself; the host decides.

pub fn begin_rename(&mut self, key: &<M as ListModel>::Key) -> bool

Open the inline rename field on the row of key. Whether it opened: the list renames (Self::on_rename), the row stands in it, and the model names it.

pub fn renaming(&self) -> Option<&<M as ListModel>::Key>

The row being renamed, if any.

pub fn rename_field(&self) -> Option<&TextInput>

The open rename field, for hosts and tests inspecting its state.

pub fn commit_rename(&mut self)

Close the rename field, reporting a non-empty trimmed title.

pub fn cancel_rename(&mut self)

Close the rename field without reporting.

impl<M> VirtualList<M>

where M: ListModel,

pub fn following_end(self) -> VirtualList<M>

Follow the list’s end, as a transcript does: it opens at its last row, and while it shows its end it stays there as rows arrive and settle their heights. A scroll away lets go; a scroll back to the end takes it up again.

pub fn unread_from(self, item: Option<String>) -> VirtualList<M>

Where a transcript’s first unread row is: the “New messages” divider stands over it, and while it is out of view a pill at the foot offers to take the reader there (crate::widget::conversation::Jump). None draws neither. A list that is not a transcript does not mark one.

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

The item the transcript’s reader has not seen, as the list was told.

pub fn set_key_presenting( &mut self, f: impl Fn(&str) -> Option<<M as ListModel>::Key> + 'static, )

How the list turns the item its reader has not seen into the key of its row, for a model of plain values that names no resources: the host that renders rows knows them.

pub fn set_unread(&mut self, item: Option<String>)

Move the divider to the row key: the rows the old and the new one are on build again, so each shows the divider over it (or not) at once, without the list’s items changing.

pub fn is_at_end(&self) -> bool

Whether the list shows its end, for one that follows it.

impl<M> VirtualList<M>

where M: ListModel,

pub fn stage_reorder( &mut self, source: &<M as ListModel>::Key, before: &<M as ListModel>::Key, ) -> bool

Show source being dragged to just before before, for a capture: the row lifts under a pointer resting on the seam above before and the drop line shows. Nothing moves unless a real release follows. Whether both rows stand placed, so it showed.

impl<M> VirtualList<M>

where M: ListModel,

pub fn new( model: M, estimated_row_height: f32, row_builder: impl FnMut(&M, usize, &<M as ListModel>::Key) -> Box<dyn Widget> + 'static, ) -> VirtualList<M>

A list of model’s rows, each built by row_builder once its data is there. A row still on its way (ListModel::row_state) keeps a reserved slot of its last or estimated height, with its placeholder painted by the list; a failed row shows why, with a retry when the model offers one. The builder never sees either.

pub fn with_selection_delegate( model: M, estimated_row_height: f32, row_builder: impl FnMut(&M, usize, &<M as ListModel>::Key, RowBuild) -> Box<dyn Widget> + 'static, ) -> VirtualList<M>

Build a list whose delegate paints its own selection from the RowSelection it receives (a run of selected rows as one lift, a separator hidden beside a selected row). The list rebuilds a mounted row when its own or a neighbour’s selection changes, and paints only the keyboard focus. A ListRow delegate takes the selection without being rebuilt.

pub fn reveal(&mut self, key: &<M as ListModel>::Key) -> bool

Scroll the row of key into view and make it the focused row. A reveal the person’s hand or key just asked for (a search hit opened, a row picked elsewhere) moves there (crate::motion::ScrollTo): a short jump glides, a long one fades in at the row; one nobody asked for lands at once.

pub fn with_id(self, id: impl Into<String>) -> VirtualList<M>

Give this list a stable app-test/inspection id.

pub fn with_feel(self, feel: Feel) -> VirtualList<M>

Play the list’s own motion — rows arriving, leaving and changing places, the reveal that takes the person to one — at feel rather than the theme’s pace.

pub fn set_feel(&mut self, feel: Feel)

Self::with_feel on a list already built.

pub fn with_viewport_height(self, height: f32) -> VirtualList<M>

pub fn set_viewport_height(&mut self, height: f32)

pub fn overlay_scrollbar(self) -> VirtualList<M>

Rows span the list, edge to edge: for rows that bring their own insets and lift no selection, as a page’s rows do, so their content shares the edge of the page around the list. Rows of a list stand one lift’s bleed in from its edges otherwise. The scroll bar lies over the rows’ trailing edge, shown while they scroll or the pointer is at it and faded out at rest, and the rows keep their whole width: for a sidebar, whose rows read as one column with the pane beside it.

pub const fn flush(self) -> VirtualList<M>

pub const fn in_column(self) -> VirtualList<M>

The list is a column’s whole body, edge to edge in it: its rows’ text starts on the column’s content edge (crate::chrome::column_gutter), where the column’s header starts its title, and their lift bleeds crate::chrome::row_bleed past it, as HIG’s one content edge has every list in a column do. The scroll bar stays on the column’s edge. Rows lift themselves, as a ListRow does.

pub fn with_edges(self, edges: impl ListEdges + 'static) -> VirtualList<M>

Leave the space edges asks for above the first row and below the last. It scrolls with the rows, as a page’s spacing does.

pub fn filling(self) -> VirtualList<M>

Take the parent’s full height (a pane’s one list) instead of a fixed viewport; the viewport follows the laid-out height.

pub fn fitting_rows(self) -> VirtualList<M>

Stand as tall as its rows, among the other content of a page that scrolls them all (a task’s steps above its notes), rather than taking its parent’s height and scrolling them itself: every row shows, and what follows the list stands after its last row.

pub fn multi_select(self, enabled: bool) -> VirtualList<M>

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

Select more than one row, or one again.

pub fn on_selected( self, callback: impl FnMut(&[<M as ListModel>::Key]) + 'static, ) -> VirtualList<M>

Told the rows selected, in the order they stand, after anything changed the selection: a click with its modifiers, the keyboard, Escape clearing it, or a row opened onto.

pub fn set_on_selected( &mut self, callback: impl FnMut(&[<M as ListModel>::Key]) + 'static, )

Self::on_selected on a list already built: what the list reports is the callback standing now, so a list whose items are given again tells its new host.

pub fn selection_follows_focus(self) -> VirtualList<M>

Select the row the keyboard moves to, as a single-selection list whose selection is what it shows elsewhere (the open item of a master-detail window) does. A modifier-extended move still extends.

pub fn with_selection( self, selection: KeySelection<<M as ListModel>::Key>, ) -> VirtualList<M>

Restore stable-key selection and discard keys absent from this model.

pub fn set_selection(&mut self, selection: KeySelection<<M as ListModel>::Key>)

Self::with_selection on a list already built: the rows chosen now, keys absent from the model dropped, and the rows on screen show it where they stand.

pub fn selection_len(&self) -> usize

How many of the rows the model holds the selection names.

pub fn with_accessible_name(self, name: impl Into<String>) -> VirtualList<M>

pub fn with_row_presence( self, presence: impl Fn(&M, usize, &<M as ListModel>::Key) -> Option<PresenceKey> + 'static, ) -> VirtualList<M>

Where each row stands for the people in it: the list paints the collaborators present at presence’s location over the row, in their colours, so a list shows where everyone is (crate::presence).

pub fn on_select( self, callback: impl FnMut(<M as ListModel>::Key, bool) + 'static, ) -> VirtualList<M>

pub fn set_on_select( &mut self, callback: impl FnMut(<M as ListModel>::Key, bool) + 'static, )

Self::on_select on a list already built.

pub fn on_activate( self, callback: impl FnMut(<M as ListModel>::Key) + 'static, ) -> VirtualList<M>

pub fn set_on_activate( &mut self, callback: impl FnMut(<M as ListModel>::Key) + 'static, )

Self::on_activate on a list already built.

pub fn on_opened( self, callback: impl FnMut(<M as ListModel>::Key) + 'static, ) -> VirtualList<M>

Told the item the person opened where it stands. A host keeping which item is open puts it back as the list’s open prop, so a list built again shows it.

pub fn set_on_opened( &mut self, callback: impl FnMut(<M as ListModel>::Key) + 'static, )

Self::on_opened on a list already built.

pub fn on_closed(self, callback: impl FnMut() + 'static) -> VirtualList<M>

Told the row standing open closed: the person pressed it again, pressed Escape, pressed beside it, or its item left the list.

pub fn set_on_closed(&mut self, callback: impl FnMut() + 'static)

Self::on_closed on a list already built.

pub fn on_fold( self, callback: impl FnMut(&<M as ListModel>::Key, bool) + 'static, ) -> VirtualList<M>

Told when a row’s subtasks fold away or open, which way it went, however they were folded: its disclosure, the keyboard, or assistive technology. A host keeping the person’s folding (a session’s open folders) hears it here.

pub fn with_semantic_key( self, encode: impl Fn(&<M as ListModel>::Key) -> String + 'static, ) -> VirtualList<M>

Encode a model key as a stable, unique string for accessibility and headless row actions. The string is opaque outside this list; it must remain unchanged while the key represents the same logical item.

pub fn with_reorder( self, validate: impl FnMut(&M, &<M as ListModel>::Key, &DropTarget<<M as ListModel>::Key>) -> bool + 'static, commit: impl FnMut(&mut M, ReorderDrop<<M as ListModel>::Key>) -> bool + 'static, ) -> VirtualList<M>

Enable row reordering. validate controls which stable-key targets receive a preview; commit mutates the model after a valid drop and returns whether the collection changed. A drag moves a row, and so does Ctrl+Up or Ctrl+Down (Alt+Up or Alt+Down, as a tree’s rows move) on the focused row, through the same validate and commit.

pub fn suppress_tooltips(&mut self, suppressed: bool)

Hide the mounted rows’ tooltips while something the host paints covers the list, as the tree does; the rows the list builds after this follow it.

pub fn reorder_target(&self) -> Option<&DropTarget<<M as ListModel>::Key>>

pub fn reorder_preview(&self) -> Option<Rect>

pub fn model(&self) -> &M

pub fn focus_row(&mut self, key: <M as ListModel>::Key)

The row key takes the keyboard: a heading that had it lets go. Give the row of key the keyboard, as a click or a reveal does; the selection stays where it was unless the list follows the focus.

pub fn selection(&self) -> &KeySelection<<M as ListModel>::Key>

pub fn selection_mut(&mut self) -> &mut KeySelection<<M as ListModel>::Key>

pub fn focused_key(&self) -> Option<&<M as ListModel>::Key>

pub fn mounted_len(&self) -> usize

pub fn mounted_rows(&self) -> impl Iterator<Item = usize>

The model indexes of the rows the list builds now, in order. What the list exports as its children is what it binds controls for: both read this, so a row reaches a screen reader and a control search alike.

pub fn visible_range(&self) -> Range<usize>

pub fn set_scroll_offset(&mut self, offset: f64)

pub fn scroll_offset(&self) -> f64

pub fn max_scroll_offset(&self) -> f64

pub fn scrollbar_thumb(&self) -> Option<Rect>

pub fn set_row_height(&mut self, index: usize, height: f32) -> bool

pub fn key_at_point(&self, point: Point) -> Option<<M as ListModel>::Key>

The key of the row at point (window coordinates), when one is drawn there.

impl<T, K> VirtualList<VecListModel<T, K>>

where T: 'static, K: Clone + Eq + Hash + 'static,

pub fn from_items( items: Vec<T>, estimated_row_height: f32, key: impl FnMut(&T) -> K, row: impl FnMut(&T, usize, &K) -> Box<dyn Widget> + 'static, ) -> Result<VirtualList<VecListModel<T, K>>, DuplicateListKey>

Short path for an owned collection. The row delegate receives the typed item plus its current display index and stable key.

pub fn reorderable(self) -> VirtualList<VecListModel<T, K>>

Enable ordinary before/after reordering for the owned vector model.

impl<M> VirtualList<M>

where M: ListModel,

pub fn open_row(&self) -> Option<&<M as ListModel>::Key>

The row standing open into its item, if one does: the item the person is reading where it stands, which the row builder draws its document into.

pub fn set_open(&mut self, key: Option<<M as ListModel>::Key>)

Open key into its item where it stands, or close it when it is the row standing open: the list’s own answer to choosing a row that opens in place, and how a host opens an item from elsewhere in the window. The two rows it changes build anew, so the one that opens grows into its document and the one that closes shuts it away.

Trait Implementations

impl<M> ActionControls for VirtualList<M>

where M: ListModel + 'static,

fn install_control_custody( &mut self, domain: &ControlDomain, attachment: CustodyAttachment, )

Bind retained producers before their first callback. Private holders must override this; child traversal alone never certifies full coverage.

fn take_control_invocation(&mut self) -> Option<ControlInvocation>

Drain one queued action-bound control intent from this subtree.

fn refresh_control_action_availability( &mut self, allowed: &HashSet<ActionAddress>, )

Push the fresh local permission-filtered action surface into every retained control: refresh this widget’s own emitter, then its children.

fn take_attributed_control_invocation( &mut self, ) -> Option<(ControlInvocation, Option<InvocationId>)>

Self::take_control_invocation, with the effect invocation the intent continues when an effect’s handler or completion queued it: the host applies it for that invocation’s invoker.

fn on_control_invocation_result( &mut self, address: &ActionAddress, result: &Result<ResourceOperationStart, DoorError>, )

Report the admission result of one queued local control invocation. Accepted means queued, not completed; confirmation remains an error while the host offers its normal confirmation UI. This notification grants no document authority and must not retry the invocation itself.

fn control_action_bindings(&self) -> Vec<ControlBindingMetadata>

Inventory action-native and explicitly legacy controls. A widget that owns an emitter prepends its metadata to its descendants’ inventory.

fn action_control_bindings(&self) -> Vec<ControlBindingMetadata>

Action-emitter bindings in the same order and exposure as the full inventory. Custom private inventories keep their authoritative default; wrappers can avoid allocating semantic-only accessibility snapshots.

fn has_action_control_bindings(&self) -> bool

Whether this exposed subtree contains controls consuming action availability. An override must match whether control_action_bindings contains an Action, including the same modal child exposure, regardless of current availability.

fn has_pending_control_invocation(&self) -> bool

Local control intent queued behind asynchronous startup preparation. A scheduling hint only; the host still checks live authority.

impl<M> PublishesResources for VirtualList<M>

where M: ListModel + 'static,

fn resources(&self, _doc: &AutoCommit) -> Vec<ResourceSpec>

The tree of resources this widget currently has open, each with the actions it exports, e.g. a playing video plus its comments. doc lets a provider enumerate resources living in the document.

fn caller_view_resources(&self, _doc: &AutoCommit) -> Vec<ResourceSpec>

Explicit host-local presentation/request controls for the portable caller palette. Only View operations are accepted; shared effects remain broker-owned.

fn action_directory_resource_page( &self, _doc: &AutoCommit, _cursor: &[u8], _max_results: usize, ) -> Option<ActionDirectoryResourcePage>

One cursor-addressable page of resource roots safe to expose through the broker pull directory. max_results is a hard ceiling; a live provider must return a non-empty opaque cursor when it has a tail. None is the default: an unbounded contextual Self::resources snapshot must not be reached from a remote query or revision.

fn action_directory_revision(&self, _doc: &AutoCommit) -> Option<String>

Revision of non-document bounded directory roots; None when this widget has no independently mutable remote directory state.

fn action_directory_invocation_domain( &self, _doc: &AutoCommit, ) -> ActionDirectoryInvocationDomain

Continuity coverage for this owning subtree’s effective invocation domain. Returning a value is a semantic promise, not authority; unknown coverage stays closed.

fn resource(&self, _doc: &AutoCommit, _id: &str) -> Option<ResourceSpec>

Resolve an addressable resource omitted from the contextual snapshot.

fn resource_pending(&self, _id: &str) -> bool

Whether id, which resolves to nothing now, may resolve once what the widget is reading off the UI thread lands (a row of a list not read yet). A caller resolving it is answered then, never kept waiting on a blocking read nor told it is unknown before the read ends.

fn resources_for( &self, participant: Option<&ParticipantId>, doc: &AutoCommit, ) -> Vec<ResourceSpec>

The tree as one participant (an agent task) sees it, built from that participant’s own view state. None is this widget’s own view. Multi-participant widgets override this and Self::resource_for, and never put one participant’s selection into another’s tree.

fn shared_resources_for( &self, participant: Option<&ParticipantId>, doc: &AutoCommit, ) -> Option<Vec<SharedResource>>

Self::resources_for as a SharedResource forest whose unchanged subtrees are the very nodes of the last one, so consumers skip what they have seen. None, the default, has callers wrap Self::resources_for. An answer must equal it exactly once materialised (SharedResource::to_resource).

fn resource_for( &self, participant: Option<&ParticipantId>, doc: &AutoCommit, id: &str, ) -> Option<ResourceSpec>

Self::resource in participant’s tree.

fn action_directory_visibility( &self, _doc: &AutoCommit, _resource_id: &str, ) -> Option<ActionAddress>

Explicit disclosure authority for an actionless resource container in the broker pull directory. None means its label and hierarchy are not remotely discoverable unless the resource itself has a safe view action.

fn document_action_result( &self, _doc: &AutoCommit, _address: &ActionAddress, _changes: &[Patch], ) -> Option<Value>

The result of document action address, which has just applied to doc as changes: a compact summary of what it produced, so its caller needs no second read to see what happened. Asked only for an action whose contract declares a JSON result, which this value must satisfy.

impl<M> ResourceOperations for VirtualList<M>

where M: ListModel + 'static,

fn local_resource_operation_handlers(&self) -> &'static [&'static str]

Effect/view operation type ids this widget can actually dispatch.

fn start_operation( &mut self, op: &ResourceOperation<'_>, doc: &mut Edits<'_>, path: &ExId, ) -> Result<Option<ResourceOperationStart>, String>

Admit an exported effect or view operation. Document operations never enter it.

fn resource_operation_handlers(&self) -> HashSet<String>

Every type this widget and its subtree dispatch.

fn poll_resource_operation( &mut self, invocation: InvocationId, cancellation_requested: bool, doc: &AutoCommit, path: &ExId, ) -> Option<InvocationUpdate>

Poll one admitted operation without blocking the UI thread.

impl<M> Widget for VirtualList<M>

where M: ListModel + 'static,

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

Rows a scroll brought near are mounted in place, and those it took away let go of; the rows themselves carry out their own changes.

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

The rows as the retained layout holds them: a row built anew since stands there as the row it replaces, until the remount mounts it.

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

The rows near its box: the others are clipped away.

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

Focus the row an assistive technology moves to, and select it, as the keyboard does.

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

The row with the keyboard: a menu opened from the keyboard stands under that row, not under the list.

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

A finger on a row is the row’s to claim (a row that swipes takes a sideways drag); the list scrolls whatever the row leaves to the pointer.

fn take_structure_change(&mut self) -> StructureChange

Rows mounted and let go — those a scroll brought near or took away, those the model re-keyed, reordered, or whose content was built anew — are mounted where they stand (Self::remount_rows) and draw themselves whole: the list shows them come and go.

With no layout of its own the list has nothing to mount under yet: the build that lays it out mounts the rows it shows, so until then it asks nothing of the host — a list the tree keeps without laying it out (a closed sidebar) would otherwise ask for a rebuild every frame and never have one carry it out.

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

A scroll that changed nothing else offers the host a copy of the rows that stay on screen, the bar’s track being what does not move with them; what changed in the rows besides is theirs to say. Any other change repaints the list.

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

The list and its rows, the rows kept between walks: a walk beside an unchanged list builds and compares no row (Self::accessibility_children).

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 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 sync(&mut self, state: &(dyn Any + 'static), path: &(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), path: &(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 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, text_renderer: &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 children(&self) -> Vec<&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 children_mut(&mut self) -> Vec<&mut dyn Widget>

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 name(&self) -> &'static str

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 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 get_rect(&self) -> Rect

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

fn is_focusable(&self) -> bool

fn set_focus(&mut self, focused: bool)

fn is_focused(&self) -> bool

fn wants_pointer_capture(&self) -> bool

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 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 draw_overlay( &mut self, scene: &mut Scene, transform: Affine, text_renderer: &mut TextRenderer, theme: &Theme, presence: &PresenceCtx, )

Top-layer pass, run once after the whole draw recursion, so anything emitted here composites above every sibling regardless of tree order — the toolkit’s overlay mechanism for content that escapes its layout box (an open Dropdown, a popover). Default recurses children_mut.

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 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 next_wake_deadline(&self) -> Option<Instant>

Earliest wall-clock deadline at which this subtree needs a sync or redraw with no input: the loop sleeps until then (not animation).

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 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 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 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 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 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 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_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_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 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 test_rects(&self) -> Vec<(String, Rect)>

Named hit rects for widgets that paint several affordances into one rect instead of composing children. Same space as Widget::get_rect; zero-area entries are dropped.

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