Struct TreeView 

pub struct TreeView<T, M = TreeNode<T>> { /* private fields */ }

Implementations

impl<T, M> TreeView<T, M>

where M: TreeModel,

pub fn with_context_menu<F>(self, items: F) -> TreeView<T, M>

where F: FnMut(&M, Option<u64>) -> Vec<MenuItem> + 'static,

Offer a context menu: right click on a row (which selects it) or on empty space (None), the Menu key or Shift+F10 on the focused row, a row action that opens the menu, and the accessibility ShowContextMenu verb. items builds the menu for its target each time it opens; an empty list opens nothing.

pub fn on_context_menu_item<F>(self, f: F) -> TreeView<T, M>

where F: FnMut(Option<u64>, usize) + 'static,

Receive the chosen context-menu item: the menu’s target and the item’s index in the list Self::with_context_menu returned (separators count).

pub fn with_row_actions(self, actions: Vec<TreeRowAction>) -> TreeView<T, M>

Show actions at the trailing edge of the hovered row.

pub fn on_row_action<F>(self, f: F) -> TreeView<T, M>

where F: FnMut(u64, usize) + 'static,

Receive a row action: the row and the action’s index.

pub fn with_heading_action(self, action: TreeHeadingAction) -> TreeView<T, M>

Place an icon button at the trailing edge of the heading band.

pub fn on_heading_action<F>(self, f: F) -> TreeView<T, M>

where F: FnMut() + 'static,

pub fn with_row_hint(self, hint: impl Into<String>) -> TreeView<T, M>

A second tooltip line under a row’s label, naming what the row does (“Click to open · double-click to rename”).

pub fn with_indent_guides(self) -> TreeView<T, M>

Draw a hairline per depth level through nested rows, so deep hierarchies keep their structure legible.

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

Hide tooltips while something the host paints covers the tree.

pub fn context_menu_is_open(&self) -> bool

pub fn close_context_menu(&mut self)

pub fn open_context_menu(&mut self, target: Option<u64>, at: Point) -> bool

Open the context menu for target (None: the tree itself) with its top-left corner at at. Returns whether a menu opened.

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

The heading action’s square, at the heading band’s trailing edge.

pub fn row_rect(&self, id: u64) -> Option<Rect>

The laid-out rect of id’s row, when it is in the viewport.

pub fn disclosure_rect(&self, id: u64) -> Option<Rect>

The disclosure of id’s row: the leading caret column of a tree row (whether or not it is a branch), the trailing chevron or the whole header of a navigation row.

pub fn row_action_rect(&self, id: u64, action: usize) -> Option<Rect>

The rect of row action action on id’s row. Actions paint only while the row is hovered, but their geometry is stable.

impl<T, M> TreeView<T, M>

where M: TreeModel,

pub fn on_rename<F>(self, f: F) -> TreeView<T, M>

where F: FnMut(u64, String) + 'static,

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

pub fn rename_on_double_click(self) -> TreeView<T, M>

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

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

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

pub fn on_delete<F>(self, f: F) -> TreeView<T, M>

where F: FnMut(u64) + 'static,

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

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

Open the inline rename field on id. Returns false when rename is not enabled or the node is unknown.

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

The row being renamed, if any.

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

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

pub fn commit_rename(&mut self)

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

pub fn cancel_rename(&mut self)

Close the rename field without reporting.

pub fn move_node(&mut self, id: u64, movement: TreeMove) -> bool

Perform movement on id through the reorder validator and commit. Returns whether the move was accepted. The row keeps focus and stays in view.

impl<T> TreeView<T>

pub fn new(root: TreeNode<T>) -> TreeView<T>

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

Batch edits to the convenient owned model and reconcile once.

pub fn reorderable(self) -> TreeView<T>

where T: 'static,

Enable safe before/inside/after dragging for the owned TreeNode model. Subtrees can be reordered among siblings or reparented without app-authored detach/insert bookkeeping.

impl<M> TreeView<(), M>

where M: TreeModel,

pub fn from_model(model: M) -> TreeView<(), M>

Build a view over an app-owned, database-backed, or asynchronous model. Call Self::notify_model_changes after the source applies a batch.

impl<T, M> TreeView<T, M>

where M: TreeModel,

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

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

pub fn on_select<F>(self, f: F) -> TreeView<T, M>

where F: FnMut(u64) + 'static,

pub fn on_expand<F>(self, f: F) -> TreeView<T, M>

where F: FnMut(u64, bool) + 'static,

pub fn on_load_request<F>(self, f: F) -> TreeView<T, M>

where F: FnMut(TreeLoadRequest) + 'static,

Receive demand-driven page requests. A loading slot is requested once when it enters the paint window; an error slot requests again only when the user activates it.

pub fn on_activate<F>(self, f: F) -> TreeView<T, M>

where F: FnMut(u64) + 'static,

Receive row activations — the “open this” gesture, distinct from selection. Enter, the accessibility Activate verb and the pointer gesture chosen by Self::click_activation activate a node; arrow keys, Space and focus changes never do, so keyboard browsing cannot open every row it passes. Activation also selects the row.

pub fn click_activation(self, activation: TreeClickActivation) -> TreeView<T, M>

Choose which pointer gesture activates a row (double click by default).

pub fn selection_follows_focus(self, enabled: bool) -> TreeView<T, M>

Make keyboard focus movement (arrows, Home/End, Page Up/Down) select the row it lands on, firing Self::on_select but never Self::on_activate — the platform list convention for navigator sidebars.

pub fn with_row_decoration<F>(self, decorate: F) -> TreeView<T, M>

where F: FnMut(&M, TreeRowInfo, &Theme) -> TreeRowDecoration + 'static,

Decorate built-in rows with an icon, a tone, trailing text and an accessible description, recomputed each frame from the model and the active theme. Rows mounted through Self::with_row_delegate are not decorated.

pub fn with_heading(self, heading: impl Into<String>) -> TreeView<T, M>

Paint a section heading above the rows (a sidebar’s “Explorer” or “Schema” label). The heading also names the tree for assistive technology unless Self::with_accessible_name overrides it.

pub fn set_heading(&mut self, heading: Option<String>)

Replace the heading (see Self::with_heading).

pub fn with_ground( self, ground: fn(&Theme) -> AlphaColor<Srgb>, ) -> TreeView<T, M>

Paint the tree on a surface other than surfaces.base (a raised sidebar). The function is resolved against the theme every frame, so the ground tracks theme changes; hover and selection lift from it.

pub fn hide_root(self) -> TreeView<T, M>

Hide the root: its children form the top level at depth 0 and it is always expanded. Suits a project or database whose name is already the heading.

pub fn fill(self) -> TreeView<T, M>

Take the height the parent allots (or the rect given to Self::place_at) and scroll internally, instead of sizing to the content for an outer Scrollable.

pub fn set_current(&mut self, id: Option<u64>)

Mark the host’s current item — the open file, the table on screen. The current row’s label is set in the heavier weight; it is independent of selection, which follows the user’s browsing.

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

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

Position the tree at an externally computed rect without a taffy pass — for a sidebar that slides over the content, whose geometry the host derives each frame. Paint, hit-testing and semantics all follow the new rect; a Self::fill tree also resizes its viewport to it. Rows mounted through Self::with_row_delegate keep the geometry of their last layout pass, so external placement suits built-in and decorated rows.

pub fn restore_expanded<I>(&mut self, ids: I)

where I: IntoIterator<Item = u64>,

Replace the expanded set without firing Self::on_expand — for a host restoring expansion it persists itself. Unknown ids, and leaves that cannot hold children, are ignored.

pub fn expanded_ids(&self) -> impl Iterator<Item = u64>

The expanded nodes, for a host persisting expansion itself.

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

Scroll id’s row into view if it is in the visible order. A Self::fill tree that has no viewport yet reveals the row once its first layout sizes one.

pub fn with_row_height(self, height_px: f32) -> TreeView<T, M>

Author the row height at the default text scale (the estimate Self::set_viewport takes, without fixing a viewport height). It grows only once the label line itself would not fit.

pub fn with_reorder( self, validate: impl FnMut(&M, u64, &DropTarget<u64>) -> bool + 'static, commit: impl FnMut(&mut M, ReorderDrop<u64>) -> bool + 'static, ) -> TreeView<T, M>

Enable validated before/inside/after node reordering. A successful commit mutates the model and returns true; the tree then reconciles expansion, selection, retained delegates, and its stable viewport anchor once.

pub fn reorder_target(&self) -> Option<&DropTarget<u64>>

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

pub fn with_row_delegate<F>(self, delegate: F) -> TreeView<T, M>

where F: FnMut(&M, u64, usize) -> Box<dyn Widget> + 'static,

Replace built-in text rows with retained widget subtrees for resident model nodes. Disclosure, selection, focus, indentation, loading/error placeholders, and tree semantics remain owned by TreeView.

pub fn with_slot_delegate<F>(self, delegate: F) -> TreeView<T, M>

where F: for<'a> FnMut(&M, TreeSlot, usize, TreeSlotState<'a>) -> Box<dyn Widget> + 'static,

Replace built-in loading and error text with retained widget subtrees.

The delegate is mounted only for unresolved slots in the virtual paint window. TreeView continues to own stable row identity, busy/invalid semantics, focus, activation-to-retry, measurement, and request deduplication. This lets apps localize placeholders or add ordinary progress and retry controls without turning them into model nodes.

pub fn invalidate_row_delegates(&mut self, ids: impl IntoIterator<Item = u64>)

Rebuild delegated widgets for model nodes whose displayed data changed.

pub fn with_expanded<I>(self, ids: I) -> TreeView<T, M>

where I: IntoIterator<Item = u64>,

Seed expansion without firing Self::on_expand. Unknown and leaf ids are ignored, which keeps generated/app-owned state tolerant of a model that has changed since it was persisted.

pub fn with_selected(self, id: Option<u64>) -> TreeView<T, M>

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

Enable platform-standard Ctrl/Command toggle, Shift range, and Ctrl/Command+A selection. Single selection remains the default.

pub fn with_selection(self, selection: KeySelection<u64>) -> TreeView<T, M>

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

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

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

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

Expand or collapse a branch and report whether state changed.

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

Does not require id to be visible: collapsing a parent doesn’t clear the selection.

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

pub fn selection(&self) -> &KeySelection<u64>

pub fn selection_mut(&mut self) -> &mut KeySelection<u64>

pub fn select_all(&mut self)

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

pub fn focused_row(&self) -> Option<TreeRowKey>

pub fn set_focused(&mut self, id: Option<u64>)

Move the keyboard focus ring to id without selecting it — for a host whose selection changed elsewhere, so arrow keys continue from the row it now shows as chosen.

pub fn is_dragging(&self) -> bool

Whether a row is being dragged (past the drag threshold).

pub fn model(&self) -> &M

pub fn update_source<R>( &mut self, changes: &[TreeModelChange], update: impl FnOnce(&mut M) -> R, ) -> R

Mutate an app-owned model stored directly in the view and apply its notification batch afterward. Models backed by shared interior state can mutate externally and call Self::notify_model_changes instead.

pub fn notify_model_changes(&mut self, changes: &[TreeModelChange])

Reconcile a batch already applied to the model. Label-only changes keep geometry; structural and slot-state changes rebuild once and preserve the current viewport anchor by stable row identity.

pub fn visible_rows(&self) -> Vec<(u64, &str, usize)>

Collect every expanded row as (id, label, depth). This convenience is intended for small owned trees and tests; large/paged models should use Self::visible_len, Self::visible_row, and Self::visible_row_range so they never materialize the full order.

pub fn visible_len(&self) -> usize

pub fn visible_row(&self, index: usize) -> Option<(u64, &str, usize)>

pub fn with_viewport( self, height_px: f32, estimated_row_height_px: f32, ) -> TreeView<T, M>

Fluent form of Self::set_viewport for app constructors.

pub fn set_viewport(&mut self, height_px: f32, estimated_row_height_px: f32)

Enable bounded internal virtualization. Without an explicit viewport, the tree keeps its historical content-sized layout and can be wrapped in an outer Scrollable.

pub fn set_scroll_y(&mut self, offset_px: f32)

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

Set a logical-pixel offset without the precision loss of f32 at hundred-million-row extents.

pub fn scroll_y(&self) -> f32

pub fn scroll_offset(&self) -> f64

pub fn max_scroll_y(&self) -> f32

pub fn max_scroll_offset(&self) -> f64

pub fn set_row_height(&mut self, visible_index: usize, height_px: f32) -> bool

Cache the measured height of one row in current visible order.

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

pub fn request_visible_rows(&mut self) -> usize

Demand every loading slot in the current paint window exactly once. Hosts that drive a headless tree can call this explicitly; normal widget drawing calls it automatically.

pub fn stage_reorder(&mut self, source: u64, before: u64)

Stage a drag of source hovering just before before, for a capture: the row lifts and follows a pointer resting on the seam above before, the drop line shows, and nothing is committed unless a real release follows (Escape cancels it). Staged before the first layout, it applies once the rows have geometry.

Trait Implementations

impl<T, M> Widget for TreeView<T, M>

where T: 'static, M: TreeModel + 'static,

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

The open context menu is a floating Panel in the window’s top layer, above every pane and the window’s chrome.

fn set_interaction_environment(&mut self, environment: InteractionEnvironment)

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

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

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

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

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

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

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

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

Paint into scene. The default paints nothing.

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

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

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

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

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

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

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

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

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

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

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

fn needs_animation_frame(&self) -> bool

App polls this in Event::AboutToWait; without it a curve would freeze 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 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 is_layout_dirty(&self) -> bool

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

fn layout_needs_measure(&self) -> bool

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

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

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

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

fn get_rect(&self) -> Rect

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

fn is_focusable(&self) -> bool

fn set_focus(&mut self, focused: bool)

fn is_focused(&self) -> bool

fn 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 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 tooltip_target_at(&self, point: Point) -> Option<(Rect, String)>

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

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

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

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

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

fn observe_physical_input(&mut self, _input: PhysicalInput)

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

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

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

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

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