Struct TextInput 

pub struct TextInput { /* private fields */ }

Implementations

impl TextInput

pub fn new(path: Vec<PathSegment>) -> TextInput

Empty path opts the widget out of presence rendering.

pub fn set_align(&mut self, align: TextAlign)

None disables authorship stamping. Align the text within the input’s width (a centred title).

pub fn align(&self) -> TextAlign

How the text is aligned within the input’s width.

pub fn set_local_author(&mut self, author: Option<String>)

pub fn bind_text(&mut self, obj: ExId)

Show the text object obj, read on every sync. What the user types stays local until the owner takes it (Self::take_dirty) and submits it as an action.

pub fn clear_text_binding(&mut self)

Stop showing a text object, keeping what the input shows.

A binding replaces any earlier local mode, so the input stays unbound until an owner calls Self::bind_text again.

pub fn bound_obj(&self) -> Option<&ExId>

For BlockEditor to match local blocks to doc list elements by object identity.

pub fn with_text_role(self, role: TextRole) -> TextInput

Set the field’s text in role (default TextRole::Body).

pub fn with_plain_chrome(self) -> TextInput

pub fn set_text_role(&mut self, role: TextRole)

Change the field’s text role; see Self::with_text_role.

pub fn text_role(&self) -> TextRole

The field’s text role.

pub fn set_plain_chrome(&mut self, plain: bool)

pub fn with_mono(self) -> TextInput

pub fn set_mono(&mut self, mono: bool)

pub fn is_mono(&self) -> bool

pub fn with_kind(self, kind: TextInputKind) -> TextInput

Declare the exceptional structured intent of a field. Natural-language prose is already the default and never needs an annotation.

pub fn set_kind(&mut self, kind: TextInputKind)

pub fn kind(&self) -> TextInputKind

pub fn with_spellcheck(self, on: bool) -> TextInput

Enable or disable spelling assistance for this field. It defaults on for ordinary text and is automatically suppressed for secret and code-like fields.

pub fn spellcheck_enabled(&self) -> bool

pub fn with_autocorrect(self, on: bool) -> TextInput

Override automatic correction for this field. Without an override the user-wide Spell checker setting applies.

pub fn autocorrect_enabled(&self) -> bool

pub fn with_spell_language(self, language: &str) -> TextInput

Select a language dictionary, accepting both en-US and en_US style tags. If that Hunspell dictionary is unavailable, non-English checking quietly disables itself; English retains the embedded fallback.

pub fn set_spell_language(&mut self, language: &str)

pub fn spell_language(&self) -> &str

pub fn with_text_action(self, id: &str, label: &str) -> TextInput

Add a host-owned action to the selection context menu. Activating it produces a request drained by take_text_action_request; the widget never blocks on the action itself.

pub fn add_text_action(&mut self, id: &str, label: &str)

pub fn take_text_action_request(&mut self) -> Option<TextActionRequest>

pub fn with_font_family(self, family: FontChoice) -> TextInput

Wins over the mono flag.

pub fn set_font_family(&mut self, family: Option<FontChoice>)

pub fn font_family(&self) -> Option<&FontChoice>

pub fn local() -> TextInput

A field with no document binding.

pub fn from_state(state: &LocalState<String>) -> TextInput

Create a true two-way binding to typed process-local text state.

User edits update state; mutations through any clone of state update this input on the next synchronization pass. Several inputs and read-only Text views can therefore share one value without initial-value snapshots, callbacks, or app-owned fan-out. Selecting a document or external-buffer binding later replaces this process-local binding explicitly.

pub fn with_char_filter(self, filter: fn(char) -> bool) -> TextInput

Admit only characters accepted by filter on every insertion path.

This is deliberately a character predicate, not a validator for the whole value: callers still own domain parsing and error reporting when the field is submitted.

pub fn with_initial_value(self, s: &str) -> TextInput

Cursor parks at the end; dirty stays false (programmatic seed).

pub fn set_text(&mut self, s: &str)

pub fn value(&self) -> &str

pub fn is_composing(&self) -> bool

Whether an IME candidate is displayed but not yet committed as text. Composite editors must leave candidate-selection keys to the IME.

pub fn on_change(self, callback: impl FnMut(&str) + 'static) -> TextInput

Register an app-local callback for committed user edits.

Keyboard input, paste, accessibility edits, and committed IME text notify once with the complete new value. IME preedit, cursor movement, selection changes, Self::set_text, and CRDT synchronization do not. It runs beside a bound action (Self::on_action), in either order of registration.

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

Route committed keyboard, paste, IME, and accessibility edits through an exported action with the complete current string as input.

pub fn insert_at_cursor(&mut self, s: &str)

Insert s at the caret as the user’s edit.

pub fn cursor_pos(&self) -> usize

pub fn caret_position(&self) -> TextPosition

The caret’s document offset and visual side at an ambiguous boundary.

pub fn set_cursor_pos(&mut self, pos: usize)

Does not count as a user edit (dirty stays false).

pub fn set_caret_position(&mut self, position: TextPosition)

Seat the caret at an exact shaped position without counting as an edit.

pub fn selection_range_public(&self) -> Option<(usize, usize)>

pub fn selection_anchor_focus_public(&self) -> Option<(usize, usize)>

The live selection endpoints in anchor/focus order for accessibility bridges. Unlike Self::selection_range_public, this preserves the direction in which the user extended the selection.

pub fn char_x_positions(&self) -> &[f64]

len() is text.len() + 1; empty until the first draw lands.

pub fn scroll_x(&self) -> f64

pub fn set_preserve_unfocused_scroll(&mut self, preserve: bool)

Retain bounded multiline scroll when used as an inert, unfocused source view. Does not enable focus, caret painting, input handling or document binding.

pub fn scroll_y(&self) -> f64

pub fn body_line_height(&self) -> f64

pub fn gutter_width(&self) -> f64

pub fn byte_at_point(&self, point: Point) -> usize

Requires a prior draw to have built the metrics.

pub fn position_at_point(&self, point: Point) -> TextPosition

Exact caret position under a point, including mixed-BiDi affinity.

pub fn scroll_by(&mut self, dy: f64)

No-op for a single-line field.

pub fn is_plain(&self) -> bool

pub fn text_padding_x(&self, theme: &Theme) -> f64

pub fn text_inset_x(&self, theme: &Theme) -> f64

Where the field’s text starts inside its rect: the multiline inset (and code gutter) of a wrapping field, the horizontal padding of a single-line one.

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

Single source of truth for both the local and any peer caret, so they line up.

pub fn caret_rect(&self, theme: &Theme, byte: usize) -> Rect

Peer carets render through this too, so a remote caret is pixel-identical, only recoloured.

pub fn caret_rect_at(&self, theme: &Theme, position: TextPosition) -> Rect

Caret geometry for an exact byte-and-affinity position.

pub fn selection_rect(&self, theme: &Theme, start: usize, end: usize) -> Rect

Single-line only; multiline callers use selection_rects.

pub fn selection_rects( &self, theme: &Theme, start: usize, end: usize, ) -> Vec<Rect>

One rect per visual row the range spans.

pub fn content_height(&self) -> f64

Falls back to one row when nothing has been laid out yet.

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

Some(text) if a user-initiated edit landed since the last call.

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

Places the input without a layout tree — only safe on local-mode TextInputs with no presence path or permission scope.

pub fn with_id(self, id: &str) -> TextInput

pub fn with_external_buffer(self, buffer: Arc<Mutex<String>>) -> TextInput

Mirror edits into caller-owned process-local memory without creating a CRDT object. Intended for passwords/PINs; use with Self::local.

pub fn with_secret(self, on: bool) -> TextInput

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

pub fn is_secret(&self) -> bool

pub fn with_reveal(self, on: bool) -> TextInput

Only meaningful together with with_secret. Secret fields start hidden; a single-line one also offers its own show/hide control.

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

pub fn toggle_reveal(&mut self)

No-op on a non-secret field.

pub fn is_revealed(&self) -> bool

pub fn has_reveal_control(&self) -> bool

Whether this field paints and offers the trailing show/hide control.

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

Where the show/hide control sits, or None without one.

pub fn multiline(self, on: bool) -> TextInput

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

pub fn is_multiline(&self) -> bool

pub fn with_gutter(self, on: bool) -> TextInput

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

pub fn with_current_line_highlight(self, on: bool) -> TextInput

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

pub fn with_highlighter(self, h: Box<dyn Highlighter>) -> TextInput

pub fn set_highlighter(&mut self, h: Option<Box<dyn Highlighter>>)

pub fn with_tab_width(self, n: usize) -> TextInput

0 = literal \t. Shift+Tab outdents by the same width.

pub fn set_tab_width(&mut self, n: usize)

pub fn with_enter_submits(self, on: bool) -> TextInput

Read the signal with take_submit.

pub fn take_submit(&mut self) -> bool

true once per submitting Enter; clears on read.

pub fn disabled(self, on: bool) -> TextInput

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

Drops any in-progress drag so the widget doesn’t hold pointer capture while inert.

pub fn is_disabled(&self) -> bool

pub fn with_placeholder(self, hint: impl Into<LabelKey>) -> TextInput

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

Set the stable label announced for this field by assistive technology. Placeholder text is intentionally not used as the label because it disappears after entry and often describes format rather than purpose.

pub fn set_placeholder(&mut self, hint: &str)

pub fn placeholder(&self) -> &str

pub fn shows_placeholder(&self) -> bool

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

How tall a single-line field is: the height of a button of the same size, so fields and buttons share a row. Regular (32) by default.

pub fn set_control_size(&mut self, size: ControlSize)

Change the field’s ControlSize; see Self::control_size.

pub fn with_min_lines(self, lines: usize) -> TextInput

A wrapping field at least lines lines tall, with the same text inset as a single-line field and never shorter than one.

pub fn on_submit(self, callback: impl FnMut(&str) + 'static) -> TextInput

Run callback with the text when the person presses Enter: the field’s commit for a tree-owned field nobody polls. Enter submits (Shift+Enter still breaks a wrapping field’s line).

pub fn with_clear_button(self) -> TextInput

A trailing clear button inside the field while it holds text.

pub fn with_trailing_accessory( self, icon: Icon, name: &str, action: AccessoryAction, ) -> TextInput

A trailing icon button inside the field, named name for assistive technology (a reveal toggle, a picker).

pub fn accessory_pressed(&self) -> Option<bool>

Whether the trailing accessory is a toggle that is on.

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

Turn a toggle accessory on or off (the host syncing from its model). No-op for any other accessory.

pub fn with_content_size(self, px: f32) -> TextInput

Edit text that belongs to a document in place, at the document’s own px size (a note on a zoomed page): the text scale does not grow it, the document’s zoom does.

pub fn set_content_size(&mut self, px: Option<f32>)

Change or clear the document-space size of Self::with_content_size.

pub fn with_span_highlighter( self, highlighter: impl Fn(&str, &Theme) -> Vec<(Range<usize>, AlphaColor<Srgb>)> + 'static, ) -> TextInput

Colour spans of a single-line field’s text (references in a formula); see SpanHighlighter. A wrapping field takes a Highlighter instead.

pub fn is_dragging(&self) -> bool

For BlockEditor’s cross-block drag coordinator.

pub fn set_selection(&mut self, anchor: usize, cursor: usize)

For BlockEditor’s cross-block drag coordinator, painting a selection band on a block being dragged through without it being the click target. anchor == cursor clears.

pub fn select_all(&mut self)

For wrappers with “focus selects the value” semantics, e.g. NumberInput.

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

What the last draw painted outside the field’s rect: while a correction is offered, its chip, which floats above or below the field. A host proving its own damage repaints this too when the field changes.

pub fn open_text_menu_at(&mut self, pos: [f32; 2])

Open the native text menu at a logical-pixel position. Hosts use this for keyboard menu keys, accessibility actions, and deterministic UI previews; pointer right-clicks route here automatically.

Trait Implementations

impl ActionControl<String> for TextInput

fn bind_action(self, binding: ActionBinding<String>) -> 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 TextInput

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

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

fn has_pending_control_invocation(&self) -> bool

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

impl Drop for TextInput

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl EditsText for TextInput

fn show_text(&mut self, obj: ObjId)

Show the text object obj, reading it on every sync, and keep edits out of the document.

fn hide_text(&mut self)

Stop showing a text object.

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

The text after the user’s edits since the last call, if any.

fn reset_text(&mut self, text: &str)

Show text, which is not a user edit.

fn shown_text(&self) -> &str

The text shown.

impl FormControl for TextInput

fn with_form_accessible_name(self, name: &str) -> TextInput

Attach the same localization key rendered by the field’s visible label.

impl PublishesPresence for TextInput

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

The widget’s path, so peers editing the same field share carets.

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

The caret, or the selection when one is extended, while focused. A secret field publishes nothing.

impl UndoPoints for TextInput

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

Ephemeral state (caret, selection) saved with an undo point.

fn set_state(&mut self, state: &str)

Restore ephemeral state saved by Self::get_state.

impl Widget for TextInput

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

Single-line keeps its fixed row height from build_layout (ZERO here). Embedded callers use apply_layout_external and never reach this.

fn layout_needs_measure(&self) -> bool

A single-line field scrolls content horizontally rather than growing, so it only needs re-measure before its first layout or right after a user edit — never blocking the scroll fast path while idle.

fn is_layout_dirty(&self) -> bool

Same inputs as Self::layout_needs_measure: an input’s size follows its content only through a user edit (dirty, drained by the owner’s take_dirty) or a model change that reshapes multiline or attributed text (model_layout_dirty, cleared by measure). Idle inputs would otherwise be re-measured on every retained frame.

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

A disabled input claims no cursor and defers to the host default.

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

Hosts that embed the field without a layout tree still get the show/hide control’s tooltip.

fn needs_redraw(&self) -> bool

Repaints like a leaf; the show/hide control does not make the field a container that only redraws for a dirty child.

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

The trailing accessory is a named control of its own: activating it (an agent, a screen reader) does what a press does.

fn wants_pointer_capture(&self) -> bool

Keeps receiving cursor events during a drag even if the cursor wanders into a sibling widget.

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

Paints the open context menu here so it floats above every sibling regardless of tree order.

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), root: &(dyn Any + 'static))

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

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

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

fn is_focused(&self) -> bool

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 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 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 perform_action( &mut self, action: &Action, _key_path: &[u64], _state: &mut Edits<'_>, _root: &(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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.