Struct NavShell 

pub struct NavShell { /* private fields */ }

The one window shell. See the module docs.

Implementations

impl NavShell

pub fn back(&mut self) -> bool

Go back one step: lower or put away the inspector’s sheet (Self::sheet_back), else go back one screen, the app’s page stack first (Self::with_back), then a narrow window’s push stack. Returns whether it did.

impl NavShell

pub fn bottom_band(self, band: Box<dyn Widget>) -> NavShell

Put band across the window’s foot, under every column: the sidebar, the inspector and their drawers stop above it, and it is as tall as it measures at the window’s width. It stays whatever the window shows: a narrow window’s screens slide over it, never with it.

impl NavShell

pub fn is_inspector_open(&self) -> bool

Whether the inspector shows.

pub fn toggle_inspector(&mut self)

Show or hide the inspector, remembering the choice for this window size class (also while the app takes the inspector away and gives it back).

pub fn open_inspector(&mut self)

pub fn close_inspector(&mut self)

pub fn inspector_frame(&self) -> InspectorFrame

Where the inspector stands this frame (InspectorFrame).

pub fn inspector_link(&self) -> InspectorLink

The handle an app painting inside the shell reads the inspector’s frame from and asks it to open, close or move through (InspectorLink).

pub fn inspector_detent(&self) -> Option<SheetDetent>

Where the inspector’s sheet rests, while the inspector is one.

pub fn set_inspector_detent(&mut self, detent: SheetDetent)

Send the inspector’s sheet to detent, as an action asks: at once. It keeps the detent while the inspector is docked.

impl NavShell

pub fn nothing_listed(self, empty: Box<dyn Widget>) -> NavShell

Show empty in place of the overview, content and inspector while there is nothing to list: a first run, an empty library. The sidebar stays; the columns given before or after come back once Self::set_nothing_listed clears it.

pub fn set_nothing_listed(&mut self, empty: Option<Box<dyn Widget>>)

Self::nothing_listed on a kept shell: None brings the app’s columns back.

impl NavShell

pub fn toast(&mut self, text: impl Into<String>, kind: ToastKind)

Show a transient notice in the window’s bar: an operation’s result or failure. It replaces the one showing and leaves on its own.

pub fn toast_with_action( &mut self, text: impl Into<String>, kind: ToastKind, icon: &str, action: impl Into<String>, )

Show a notice with one button beside it in the bar, named action (“Undo”) with the icon icon (“undo-2”). Self::take_toast_action reports the press.

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

The text of the notice whose button the person pressed since the last call.

pub fn dismiss_toast(&mut self)

Take down the notice showing, when its news no longer holds.

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

The notice showing, if any.

impl NavShell

pub fn with_sidebar_state(self, state: &LocalState<bool>) -> NavShell

Keep whether the sidebar shows in state: the shell writes where it stands once laid out and every choice the person makes; setting the state shows or hides the sidebar (opens the drawer in a narrow window, from ViewCx::on_stage for a capture).

pub fn with_inspector_state(self, state: &LocalState<bool>) -> NavShell

Keep whether the inspector shows in state, as Self::with_sidebar_state.

pub fn with_inspector_revealed(self) -> NavShell

With Self::with_inspector_state, show the inspector once laid out (docked beside the content, or over it in a narrow window), for a shell built to show what was just chosen in it: a deep link, a selection made in another place of the app.

impl NavShell

pub fn stage_sidebar_width(&mut self, width: f64)

Stage the sidebar at width (authored at 1×) as a person who dragged it there left it, for a capture of a widened or narrowed sidebar. Live windows get the width from the person’s drag and from where it is remembered, never from the app.

impl NavShell

pub fn with_window_toolbar(self) -> NavShell

The app’s toolbar is its window bar’s slots (crate::window_toolbar): the shell draws no header row of its own, in a Tilo session or out of it. Its own buttons (the sidebar toggle, Back, the inspector toggle) are slots too: the app starts its declaration from Self::window_toolbar and hands what the person did in the bar to Self::window_toolbar_event first. Column titles and header actions given to the shell are not shown: the app declares its location and actions as slots.

pub fn set_sidebar_toggle_in_window_bar(&mut self, on: bool)

The app shows the sidebar toggle in the window’s bar (crate::window_toolbar::WindowToolbar::sidebar) and runs it with Self::toggle_sidebar: the header row keeps no toggle of its own, and stands only for what else it holds.

pub fn with_header_in_window_bar(self) -> NavShell

Put the header row in the window’s bar: while the window is maximized, the row hides with the window’s controls and appears with them over the top of the content when the person reaches for the bar (widget::top_edge_reveal), as one bar. In a tiled window the row stands above the content as usual.

pub fn can_go_back(&self) -> bool

Whether Back goes anywhere: the app’s page stack (Self::with_back, Self::set_can_go_back), a narrow window’s push stack, or the inspector’s sheet to lower or put away.

pub fn window_toolbar(&self) -> WindowToolbar

The shell’s own slots for the window’s bar (Self::with_window_toolbar): the sidebar toggle while there is a sidebar, Back while it goes anywhere (leading), and the inspector’s toggle while there is an inspector (the last action). The app adds its location, views and actions; the inspector’s toggle stays last.

pub fn window_bar_link(&self) -> WindowBarLink

The link an app painting inside the content column uses to put the shell’s own buttons in the window’s bar (WindowBarLink). Use with Self::with_window_toolbar.

pub fn push_window_actions( toolbar: &mut WindowToolbar, actions: impl IntoIterator<Item = ToolbarAction>, )

Add the app’s own actions to Self::window_toolbar’s, before the inspector’s toggle, which stays the last of the row.

pub fn window_toolbar_event(&mut self, event: &ToolbarEvent) -> bool

Run what the person did in the window’s bar on the shell’s own slots. Returns whether it was one of them; the app handles the rest.

impl NavShell

pub fn new() -> NavShell

An empty shell; give it columns with the builders.

pub fn sidebar(self, sidebar: Box<dyn Widget>) -> NavShell

The sidebar of destinations (usually a crate::widget::NavList).

pub fn overview(self, overview: Box<dyn Widget>) -> NavShell

The overview list beside the content (a message list, a city list): content the person reads, not navigation.

pub fn overview_rail(self, rail: Box<dyn Widget>) -> NavShell

What the overview collapses into where the list no longer fits beside the content but a rail does: a NavList::rail of the same places, so the window narrows to rail and detail before it pushes.

pub fn content(self, content: Box<dyn Widget>) -> NavShell

The content.

pub fn inspector(self, inspector: Box<dyn Widget>) -> NavShell

The inspector at the trailing edge: properties of the selection.

pub fn overview_controls(self, controls: Box<dyn Widget>) -> NavShell

Controls that act on the overview list (its sort order, a scope), under the overview’s header at the shell’s inset.

pub fn sidebar_header( self, title: impl Into<String>, actions: Vec<Box<dyn Widget>>, ) -> NavShell

The sidebar column’s header: a sentence-case title and the app’s actions (buttons). The toggle is the shell’s; do not add one.

pub fn overview_header( self, title: impl Into<String>, actions: Vec<Box<dyn Widget>>, ) -> NavShell

The overview column’s header (the list’s title and its actions).

pub fn content_header( self, title: impl Into<String>, actions: Vec<Box<dyn Widget>>, ) -> NavShell

The content column’s header: the detail title and toolbar actions.

pub fn content_header_bound( self, title: &LocalState<String>, actions: Vec<Box<dyn Widget>>, ) -> NavShell

The content’s header with its title bound to title: a view names its content from resource state, and the header follows the state.

pub fn content_header_leading(self, leading: Box<dyn Widget>) -> NavShell

The fill of the content’s header between the shell’s leading buttons and the actions: a path bar, or a mode or tab switcher with no title; it stands at its own width and takes more room when it needs it.

pub fn inspector_header( self, title: impl Into<String>, actions: Vec<Box<dyn Widget>>, ) -> NavShell

The inspector column’s header.

pub fn overview_count(self, count: usize) -> NavShell

How many items the overview lists, after its title.

pub fn content_count(self, count: usize) -> NavShell

How many items the content shows, after its title.

pub fn with_filter(self, filter: SearchField) -> NavShell

The one filter field of the window, scoped to the sidebar’s list (or the overview, else the content); Ctrl+F focuses it, and the shell carries its query to the column’s Filterable after every event.

pub fn with_page_column(self, lines: f32) -> NavShell

The content as one page column lines lines of body text wide, centred in a scroller that keeps its bar’s gutter; the content’s filter field stands on that column’s content edges so it lines up with the page under it.

pub fn mode(self, mode: NavMode) -> NavShell

What the sidebar becomes in a narrow window: the first push screen (the default), or an icon rail docked at every width.

pub fn content_kind(self, kind: ContentKind) -> NavShell

What the content is (ContentKind): the shell docks the sidebar, inspector and overview while the content keeps the minimum its kind needs, and the window’s narrowest width is that minimum’s compact layout.

pub fn minimum_width(&self) -> f64

The narrowest window this shell works at, in logical pixels: its compact layout, one column at a time, at the theme it was last built with (Widget::minimum_window_width).

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

Give the shell a stable id for tests and inspection; its headings group is keyed by it on the agent surface.

pub fn search_sidebar(self) -> NavShell

The window’s search narrows the sidebar’s list (crate::widget::Filterable) wherever it stands: also while a narrow window shows the content screen, whose content may then show what the list’s filter finds. Without it the search reaches the list only while it is on screen.

pub fn with_sidebar_hidden(self) -> NavShell

Start with the sidebar hidden (where it docks).

pub fn with_inspector_hidden(self) -> NavShell

Start with the inspector hidden (where it docks).

pub fn with_pane_state(self, state: &LocalState<NavPane>) -> NavShell

Keep the front screen of a narrow window in state: a row of the overview can push the content by setting NavPane::Content, and the Back button writes the screen it returns to.

pub fn with_back<T>(self, stack: &LocalState<NavStack<T>>) -> NavShell

where T: Clone + PartialEq + 'static,

Bind the content’s Back to the app’s page stack: while stack can go back the shell shows its Back chip at the leading edge of the content’s header, and pressing it pops the stack (browse history, a drill-down from a dashboard into a queue). A narrow window’s push stack shares the chip: Back pops the app’s pages first.

pub fn on_back( self, can_go_back: impl Fn() -> bool + 'static, go_back: impl FnMut() + 'static, ) -> NavShell

The content’s Back for a page stack the app keeps itself: can_go_back is asked every frame, go_back runs on a press.

pub fn set_sidebar(&mut self, sidebar: Option<Box<dyn Widget>>)

pub fn set_overview(&mut self, overview: Option<Box<dyn Widget>>)

pub fn set_content(&mut self, content: Box<dyn Widget>)

pub fn set_inspector(&mut self, inspector: Option<Box<dyn Widget>>)

pub fn set_overview_rail(&mut self, rail: Option<Box<dyn Widget>>)

pub fn set_overview_controls(&mut self, controls: Option<Box<dyn Widget>>)

pub fn set_content_header_leading(&mut self, leading: Option<Box<dyn Widget>>)

pub fn set_sidebar_header( &mut self, title: impl Into<String>, actions: Vec<Box<dyn Widget>>, )

Change the sidebar’s header in place: its title and actions.

pub fn set_overview_header( &mut self, title: impl Into<String>, actions: Vec<Box<dyn Widget>>, )

Change the overview’s header in place.

pub fn set_content_header( &mut self, title: impl Into<String>, actions: Vec<Box<dyn Widget>>, )

Change the content’s header in place (the selected message’s subject and what can be done to it).

pub fn set_inspector_header( &mut self, title: impl Into<String>, actions: Vec<Box<dyn Widget>>, )

Change the inspector’s header in place.

pub fn set_sidebar_title(&mut self, title: impl Into<String>)

Change the sidebar’s title in place.

pub fn set_overview_title(&mut self, title: impl Into<String>)

Change the overview’s title in place.

pub fn set_content_title(&mut self, title: impl Into<String>)

Change the content’s title in place (the selected message’s subject).

pub fn set_inspector_title(&mut self, title: impl Into<String>)

Change the inspector’s title in place.

pub fn set_content_count(&mut self, count: Option<usize>)

Show or clear the count after the content’s title.

pub fn set_overview_count(&mut self, count: Option<usize>)

Show or clear the count after the overview’s title.

pub fn set_can_go_back(&mut self, can: bool)

Whether the content’s page stack can go back, for an app that keeps it itself (Self::on_back).

pub fn sidebar_mut<T>(&mut self) -> Option<&mut T>

where T: Widget + 'static,

The sidebar as the widget the app gave it (the one waiting to be shown, if a swap is pending), through its Widget::as_any_mut (which the widget answers with Some(self)).

pub fn sidebar_ref<T>(&self) -> Option<&T>

where T: Widget + 'static,

The sidebar as the widget the app gave it, to read: the one waiting to be shown, if a swap is pending.

pub fn overview_mut<T>(&mut self) -> Option<&mut T>

where T: Widget + 'static,

The overview as the widget the app gave it.

pub fn overview_list_mut(&mut self) -> Option<&mut DescribedList>

The overview’s first list, however the app wraps it inside its view of the column: the rows it shows and the person’s choice among them.

pub fn content_mut<T>(&mut self) -> Option<&mut T>

where T: Widget + 'static,

The content as the widget the app gave it.

pub fn filter(&self) -> Option<&SearchField>

The window’s filter field (Self::with_filter): its query and the count the filtered column reports.

pub fn filter_mut(&mut self) -> Option<&mut SearchField>

pub fn geometry(&self) -> &NavGeometry

The geometry of the last layout, in window coordinates.

pub fn has_sidebar(&self) -> bool

pub fn has_overview(&self) -> bool

pub fn is_sidebar_open(&self) -> bool

Whether the sidebar shows (docked and not hidden, or a drawer that is open, or the front push screen).

pub fn front_pane(&self) -> NavPane

The front screen of the push stack (meaningful when it has more than one screen).

pub fn toggle_sidebar(&mut self)

Show or hide the sidebar, remembering the choice for this window size class. In NavMode::Push narrow, the sidebar is a screen: showing it goes back to it, and hiding it goes on to the screen the person left for it.

pub fn open_sidebar(&mut self)

pub fn close_sidebar(&mut self)

pub fn show(&mut self, pane: NavPane)

Bring pane to the front of a narrow window’s push stack. In a wide window every pane is already showing; this records which one a later collapse keeps in front.

The push follows the input that asked for it (HIG §9.7): a click or a tap the person just made slides the screen in; a key, or a show nobody visibly caused (an agent, a script, a sync, a restore), lands at once. A host that knows where the open came from says so with Self::show_from.

pub fn show_from(&mut self, pane: NavPane, source: MotionSource)

Self::show for an open whose origin the caller knows: source is what asked for it (crate::tokens::MotionSource::Action for an agent’s action, a search hit or an open request).

pub fn snap(&mut self)

Snap every animation to its end (deterministic shots and tests).

Trait Implementations

impl ActionControls for NavShell

Controls in a column the shell is not showing (a hidden sidebar, a closed drawer, a pushed-away screen) still belong to the window: custody, invocations and availability reach every part the shell owns.

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

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

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

impl Default for NavShell

fn default() -> NavShell

Returns the “default value” for a type.

impl Described for NavShell

fn set_props(&mut self, props: NavShellProps) -> bool

Titles, counts and whether Back goes back change in place; the columns and header actions change through their slots. Another kind of content builds the shell again.

type Props = NavShellProps

fn from_props(key: &str, props: NavShellProps) -> NavShell

The widget of props, with key its stable id.

fn slot_views(&mut self, slot: &str) -> Option<&mut dyn SlotViews>

The views of its slot slot, to change by key in place: None when a change of what the slot holds builds the widget again.

fn part_views( &mut self, slot: &str, key: &str, of: &str, ) -> Option<&mut dyn SlotViews>

The views its slot slot holds for the part key — a part being a component the slot takes, whose props the widget reads — in that part’s own view slot of, to change them by key where they stand. None when a change inside a part builds the widget again.

impl PublishesResources for NavShell

A header button the shell hands to the window’s bar is not among the shell’s laid-out children, yet a press on it in the bar runs it: it publishes its action, and the operation the press starts reaches it.

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 ResourceOperations for NavShell

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

Every type this widget and its subtree 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 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.

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

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

impl SlotViews for NavShell

The views of the slot the shell is changing: a column’s body, or a header’s actions.

fn len(&self) -> usize

How many views the slot holds.

fn view_mut(&mut self, index: usize) -> Option<&mut Box<dyn Widget>>

fn insert(&mut self, index: usize, view: Box<dyn Widget>)

fn remove(&mut self, index: usize)

fn move_view(&mut self, from: usize, to: usize)

fn replace(&mut self, index: usize, view: Box<dyn Widget>)

fn is_empty(&self) -> bool

impl Widget for NavShell

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

The parts themselves, also those of a screen not in front, which the host meets only as stand-ins.

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

Each column’s header row as the last layout left it: what its title says against what the row gave it, and what its actions kept of their labels and their place in the row.

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

A finger on the sidebar’s edge drags it; it never scrolls.

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

The window’s group, keyed by the shell’s id so what stands under a titled column keeps its identity on the agent surface while titles come and go; the titles are its headings.

fn needs_idle_sync(&self) -> bool

Only for what the next sync would change: a bound title or open state that moved, or a Back the page stack now answers differently. A binding alone asks nothing.

fn take_structure_change(&mut self) -> StructureChange

The shell’s own changes (a column shown or hidden, a part swapped) rebuild; what its parts describe (a column’s content changed in place) stays described. Every owned part’s change is taken so none keeps a stale one, and a part outside the tree is built whole when it comes in.

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

The parts the shell lays out carry out their own changes, those of a screen not in front too: they stand in the tree while it slides.

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

A part whose overlay holds the pointer (a popover a header button owns, an open More menu) first; then the default.

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

Paint into scene. The default paints nothing.

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

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

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

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 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 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 set_focus(&mut self, focused: bool)

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

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

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 collect_damage(&self, regions: &mut Vec<Rect>)

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

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 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_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 measure( &mut self, _known: Size<Option<f32>>, _available: Size<AvailableSpace>, _text_renderer: &mut TextRenderer, ) -> Size<f32>

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

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

impl WindowHeader for NavShell

fn set_window_presents_search(&mut self, presents: bool) -> bool

The window’s bar presents search for the window, in place (crate::widget::WindowSearch), or stops (false). While it does, the row drops its own button that opens the app’s search (crate::search::APP_SEARCH_BUTTON_ID): one search control per window. Returns whether the row took it.

fn set_history_control(&mut self, control: Option<HistoryControl>)

Show the window’s History control at the trailing edge of the row, or none (None: the app has no History, or the host’s own chrome presents it).

fn set_sync_status(&mut self, status: Option<&WindowStatus>) -> bool

Show the window’s sync status (“Working offline…”) as quiet text in the row, before its trailing controls, with its button (Retry) beside it when it has one, or none. Returns whether the row shows it; a row that does not leaves the host to present it.

fn set_window_bar(&mut self, bar: Option<WindowBar>) -> bool

Merge the window’s bar into this header row while the window is maximized, or stop (None). The row reserves bar.controls_width at its trailing end for the window’s controls, which the host paints there when the person reaches for them, so the app’s header and the window’s controls read as one bar instead of two stacked ones. A row whose app put its header in the window’s bar (WindowBarSlot::hides_with_bar) shows only while bar.revealed, over the app’s content. Returns whether the row took the bar; a row that does not leaves the host to float its controls over the window.

fn window_bar_slot(&self) -> Option<WindowBarSlot>

Where the row stands and where the window’s controls go, after layout, while it holds the window’s bar.