Struct Button 

pub struct Button { /* private fields */ }

Implementations

impl Button

pub fn new(id: &str, label: &str) -> Button

pub fn with_presence(self, path: Vec<PathSegment>) -> Button

An empty path leaves presence opt-out (the default).

pub fn with_permission_scope(self, scope: PermissionScope) -> Button

When the scope is denied the widget renders dimmed and rejects input.

pub fn on_click<F>(self, f: F) -> Button

where F: FnMut() + 'static,

Fires once per completed click (left-button release while the cursor is still over the button), Enter, Space or an assistive Activate.

pub fn on_action(self, binding: ActionBinding<()>) -> Button

Route pointer, keyboard and accessibility activation through an exported resource action. The host resolves policy against the fresh resource tree before dispatch.

pub fn on_effect<F>(self, handler: F) -> Button

where F: FnMut() + 'static,

Publish a zero-argument effect and route every activation through it.

This is the quick-app path: it keeps closure ergonomics without making an invisible callback-only control. For replayable document mutations, prefer a typed document Action.

pub fn on_view<F>(self, handler: F) -> Button

where F: FnMut() + 'static,

Publish a zero-argument transient presentation action. View actions are discoverable and agent-driveable but intentionally absent from document history and collaboration logs.

pub fn with_icon(self, icon: Icon) -> Button

With an empty label the icon is centred (icon-only button); with a label it sits to its left.

pub fn with_accessible_name(self, name: &str) -> Button

The text isn’t painted — it’s what a screen reader announces in place of the empty visible label. Use for every icon-only toolbar control so the glyph isn’t silent. A button that shows a label doesn’t need this; the label is its accessible name.

pub fn tooltip(self, text: impl Into<String>) -> Button

On an icon-only button, absent an explicit with_accessible_name, this also becomes the accessible name, so the same short label serves both mouse and screen-reader users. Rendered centrally by the host’s TooltipHost — no per-app wiring.

pub fn set_tooltip(&mut self, text: Option<String>)

pub fn set_accessible_name(&mut self, name: &str)

Change what an icon-only button is announced (and published) as, for a control whose meaning flips with state (“Show sidebar” / “Hide sidebar”).

pub fn icon_only(id: &str, icon: Icon, label: &str) -> Button

An icon-only button: icon is what it shows, label is what a screen reader announces and what its tooltip says. It is a square of its ControlSize’s height (never under the minimum pointer target) and, like every toolbar glyph, a ButtonRole::Plain button unless a role is given.

pub fn fill_width(self) -> Button

Stretch to the parent’s width. The height still comes from the ControlSize; without this a button is as wide as its label.

pub fn control_size(self, size: ControlSize) -> Button

How big this button is: its height and label role together (see ControlSize).

pub fn role(self, role: ButtonRole) -> Button

What the button does; the role decides its whole look.

pub fn set_role(&mut self, role: ButtonRole)

pub fn toggled(self, on: bool) -> Button

Make this a toggle button: while on it stands on a lift of its ground (a selected toolbar glyph, HIG §9.3) and is announced as a pressed toggle. Use it on a ButtonRole::Plain glyph.

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

Turn a toggle button on or off (the host syncing from its model).

pub fn is_toggled(&self) -> bool

Whether this is a toggle button that is on.

pub fn shortcut_hint(self, shortcut: Shortcut) -> Button

Show the keyboard shortcut that does the same thing, after the label, in the platform’s keycap legends (Ctrl+Enter on Linux and Windows, ⌘↩ on macOS). It is part of the button’s width.

pub fn with_enabled(self, enabled: bool) -> Button

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

pub fn enabled_from(self, state: &LocalState<bool>) -> Button

Follow state for whether the button can act (“Save” enabled while there is something to save): a change through any clone of it shows on the next sync.

pub fn with_default_focus(self) -> Button

Mark this button as its page’s encouraged action: when the page is rebuilt with a focus reset, keyboard focus starts here, so Enter activates it.

pub fn set_compact_toolbar_presentation(&mut self, compact: bool)

Prefer the icon in a space-constrained toolbar while retaining the original visible label as the accessible name and hover tooltip.

Apps should use this for responsive presentation only; activation, focus and resource-action semantics are intentionally unchanged.

pub fn apply_layout_external(&mut self, rect: Rect)

The counterpart to TextInput::apply_layout_external for an app that hand-positions a shared control over its own painted chrome; the button still owns its focus / a11y / activation contract, only its geometry is caller-driven.

impl Button

pub fn paint( scene: &mut Scene, transform: Affine, text_renderer: &mut TextRenderer, theme: &Theme, face: &ButtonFace<'_>, )

Paint a ButtonFace: the retained Button’s look for a canvas host that owns its own hit-testing (ButtonFace::contains).

impl Button

pub fn with_menu(self, items: Vec<MenuItem>) -> MenuButton

Make this button open items as a menu anchored to its own rect.

impl Button

pub fn with_popover<C>(self, content: C) -> PopoverButton<C>

where C: Widget + 'static,

Make this button open content in a popover anchored to its own rect.

Trait Implementations

impl ActionControl<()> for Button

fn bind_action(self, binding: ActionBinding<()>) -> Self

Invoke binding with the control’s committed value.

fn unavailable(self) -> Self

Present the control disabled: its action is not available.

impl ActionControls for Button

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

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

impl PermissionGated for Button

fn permission_scope(&self) -> Option<PermissionScope>

The scope gating this widget.

impl PublishesPresence for Button

fn presence_key(&self) -> Option<PresenceKey>

Stable identity for presence and permission lookup.

fn presence_payload(&self) -> Option<(PresenceKey, PresencePayload)>

Outbound presence (typically caret/selection) broadcast while this widget holds focus; the host polls the focused widget after each event and diffs it out to peers.

impl PublishesResources for Button

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

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

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

Resolve an addressable resource omitted from the contextual snapshot.

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

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

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 Widget for Button

fn adjust_layout_style( &mut self, taffy: &mut TaffyTree, node: NodeId, text: &mut TextRenderer, ) -> bool

An intrinsic button’s width is its measured content. Taffy only asks measure for an axis it cannot resolve, so the label is measured here as well and the width pinned when the solver has not done so.

fn is_layout_dirty(&self) -> bool

The Rect::ZERO sentinel keeps the first frame’s compute_layout running so apply_layout can populate the rect; after that it stays clean (pure translation handled via the cache’s append transform, no taffy involvement).

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

A host that lays buttons out (a header row) reaches their presentation through this.

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

Returns the raw string (a fluent key or plain text); the host resolves i18n and renders.

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

Enter, Space, or an AccessKit Activate performs the same CRDT mutation + imperative callback as a mouse click.

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 build_layout( &mut self, taffy: &mut TaffyTree, theme: &Theme, node_map: &mut HashMap<NodeId, *mut dyn Widget>, ) -> NodeId

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

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, out_scene: &mut Scene, out_transform: Affine, text_renderer: &mut TextRenderer, theme: &Theme, presence: &PresenceCtx, )

Paint into scene. The default paints nothing.

fn needs_redraw(&self) -> bool

Default true (dirty every frame). Opt into incremental redraw by tracking a dirty: bool, setting it in handle_event/sync, and clearing it in mark_drawn(). 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 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 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 handle_event(&mut self, event: &WindowEvent, ctx: &mut EventCtx<'_>)

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

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

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

fn is_focused(&self) -> bool

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 resource_operation_handlers(&self) -> HashSet<String>

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

Admit an exported effect or view operation: the one entry every handler implements. Document operations never enter it.

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 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/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 synchronization/publication 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 room (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.

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 update( &mut self, state: &(dyn Any + 'static), path: &(dyn Any + 'static), ) -> bool

Notice, between frames, state that lives 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 at build-time state; a widget overrides it to check state of its own and then forward.

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 (a resource’s dispatcher); the host syncs again when the document changed. The default settles the children Widget::children_mut returns.

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 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 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 local_resource_operation_handlers(&self) -> &'static [&'static str]

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

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 take_action_palette_request(&mut self) -> Option<ActionAddress>

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

fn take_search_request(&mut self) -> bool

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

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

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

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

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 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 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 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 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_purpose(&self) -> Option<ImePurpose>

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; the exception is a widget standing in for a process that has started but not drawn. Must latch: once true, never false again for the same content, or an un-presenting widget would make a window vanish mid-resize. What shows meanwhile is decided by Widget::opening.

fn opening(&self) -> bool

True once waiting long enough, while not yet presented, that showing nothing would read as broken. Delayed so a fast open never flashes an indicator.

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 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 take_committed_action(&mut self) -> Option<Vec<ChangeHash>>

The affordance-driven twin of the Ctrl+K palette: when a widget’s own control dispatches the same tilo_actions action its ActionSpec exports, it reports the document heads captured just before here, so the host can record one undo boundary the same way a palette dispatch does. Rising-edge: reading MUST clear it.

fn keeps_undo_step_open(&self) -> bool

Whether the undo step this widget’s last reported boundary opened stays open for the actions that continue it — the rest of a word typed a keystroke at a time. A hosted component then closes the step at the widget’s next boundary, or before an undo, a save or a merge, instead of after this event. Answered by the widget itself, never its children.

fn set_undo_status(&mut self, _status: &mut dyn FnMut() -> UndoStatus)

Host → widget: the live state of the undo history, published once per frame to every laid-out widget.

fn take_undo_request(&mut self) -> Option<UndoRequest>

Widget → host: an undo or redo the user asked for.

fn handle_local_undo_request(&mut self, request: UndoRequest) -> bool

Offer a host keyboard undo/redo shortcut to focused widget-local history before the application document consumes it.

fn apply_room_action( &mut self, _doc: &mut Edits<'_>, _type_id: &str, _payload: &[u8], ) -> bool

Apply an action another app in this room published, if this app owns the document — lets an app address a document it doesn’t hold by saying what should happen instead of writing bytes directly, keeping each document to one writer. An unrecognised type_id is silently declined, not an error.

fn semantic_readers(&self) -> &'static [RegisteredSemanticReader]

Inert immutable-reader registrations owned by this actual widget. Registration alone supplies no qualified owner frame or disclosure.

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

fn needs_animation_frame(&self) -> bool

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

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

Earliest wall-clock deadline at which this subtree needs a sync/redraw even if there is no input. Unlike needs_animation_frame, this keeps the event loop asleep until the requested instant and is appropriate for filesystem/status polling rather than animation.

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

True if this subtree’s structural composition (children inserted/removed) changed since the last frame; the App rebuilds the taffy tree when so. Reading clears it. The default drains every retained child (no short-circuit, so no child keeps a stale flag) and reports whether any was dirty; a leaf has no children and reports false. A container that changes its own child list sets its own flag and ORs it with this traversal.

fn take_structure_change(&mut self) -> StructureChange

Self::take_structure_dirty, saying whether the frame’s damage can still describe the rebuild (StructureChange::Described). Reading clears what take_structure_dirty clears; the two must agree on whether there is a change. The default is the flag, as a StructureChange::Rebuild: only a widget that knows every pixel its change touches lands in its own damage says less, and a container forwards a child’s StructureChange::Described only by overriding this.

fn has_pending_visual_work(&self) -> bool

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

fn has_transient_feedback(&self) -> bool

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

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

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

fn damage_covers_own_box(&self) -> bool

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

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

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.