Struct TextInput 

pub struct TextInput { /* private fields */ }

Implementations

impl TextInput

pub fn note_marks(&self, marks: impl IntoIterator<Item = Rect>)

Add marks (on screen) to what this frame shows painted over the field’s rows, for a host that paints over them (a code editor’s diagnostics): a frame where they changed repaints where they were and are.

pub fn collect_damage_for<T>(&self, owner: &T, regions: &mut Vec<Rect>)

where T: ?Sized,

This field’s damage since the frame on screen, for a host that draws it as part of owner (itself, as a widget in the tree): a scroll is offered as a copy, the lines and marks that changed repaint where they were and are, anything else repaints the field.

pub fn mark_shown(&mut self)

From the host’s mark_drawn: the frame just drawn is on screen.

impl TextInput

pub fn scroll_y(&self) -> f64

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

No-op for a single-line field.

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 set_autocorrect(&mut self, on: Option<bool>)

Self::with_autocorrect on a live field; None follows the user-wide setting again.

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

Leave the correction a typed word boundary makes pending instead of making it in the same keystroke; the host applies it with Self::apply_pending_autocorrection once the boundary is written, so the boundary and the correction are two undo steps.

pub fn has_pending_autocorrection(&self) -> bool

Whether a typed word boundary left a correction to apply.

pub fn apply_pending_autocorrection(&mut self) -> bool

Make the correction the last typed word boundary left pending, while the word and the boundary after it are still as typed and the caret right after them. Backspace right after reverts it, as for an immediate correction. false when there was nothing to make.

pub fn replace_range( &mut self, range: Range<usize>, expected: &str, replacement: &str, ) -> bool

Replace range, which must still hold expected, with replacement as exactly one undo step: the typing before it is closed off as a step of its own, and typing after it starts a new one. Leaves the replacement selected.

Refuses, changing nothing, when the range no longer holds expected (the text moved while an asynchronous action ran, or a collaborator edited it), when the field is read-only or disabled, or while an input method composition is open.

pub fn apply_text_action_result(&mut self, result: &TextActionResult) -> bool

Write back what a text action made of the text it was handed (Self::take_text_action_request), as Self::replace_range does.

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_change(self, change: Option<(String, String)>) -> TextInput

Someone else (identity, by their presence) changed what the field holds and the person has not seen it: the field is tinted in their colour, and hovering it says note (who changed it, and what it held before). None once it is seen.

pub fn with_presence_path(self, path: Vec<PathSegment>) -> TextInput

Key the field’s presence by path: collaborators editing the field at the same path see each other’s carets and selections in it.

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

Admit only characters accepted by filter on every insertion path. 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 and selection changes, Self::set_text and CRDT synchronization do not. It runs beside a bound action (Self::on_action), in either order.

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 selection_anchor_focus_or_caret(&self) -> (usize, usize)

The selection a host mirroring this field should paint after a pointer event: the anchor and caret, collapsed to the caret when nothing is selected. A click that collapses a selection has to reach the host too, or it keeps painting the selection it used to show.

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 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 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. Publishing consumes the edit notification (take_dirty), just as a document binding does; an idle sync never republishes a consumed edit.

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 with_entry(self, on: bool) -> TextInput

The entry at the end of a list: Enter or leaving the field with text commits what was typed (its submit) and clears it; Escape, or leaving it with nothing typed, leaves nothing. The field is its own draft: nothing it holds exists until it is committed.

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 wants_focus(self) -> TextInput

Ask for the keyboard as soon as this field is in the tree: the entry a command just opened is where the person types next, and they should not have to point at it. Asked once, when the window next lays out.

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_accessible_name(&mut self, name: impl Into<String>)

See Self::with_accessible_name.

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 set_on_submit(&mut self, callback: Option<Box<dyn FnMut(&str)>>)

Run callback on a submitting Enter (Shift+Enter still breaks a wrapping field’s line), or, given none, let Enter break the line again.

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

Route Enter through an exported resource action with the text as its input; see Self::on_submit. Enter submits the field’s action. A press whose submission the host has not collected yet is replaced by the next: two Enters delivered before the next frame submit once, so a repeated press cannot advance a wizard twice.

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

Run callback with the text on a submitting Enter, the field as control tilo.control:<id>, publishing the submit as its view action submit: a person’s Enter, a screen reader, a script and an agent submit through the same action.

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

Run callback with the text of every committed edit, the field, as control tilo.control:<id>, publishing the edit as its view action change: typing, pasting, an IME commit, a screen reader’s edit, a script’s and an agent’s all arrive through the same action. The control’s latest text is what it reports, so a burst of edits the host has not collected yet reports once, with the text it now holds.

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

Self::on_change_view on a field already built.

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 with_mistakes( self, marker: impl Fn(&str) -> Vec<Range<usize>> + 'static, ) -> TextInput

Underline what marker finds wrong in the text, as a misspelling is, for entries checked against something other than a dictionary (the words of a recovery key). The marker sees the text as drawn, so marks never lag an edit; it should leave the word still being typed alone.

pub fn with_read_only(self, read_only: bool) -> TextInput

Show text the person can select and copy but not change: a message body, a log. The field keeps the keyboard (arrows, Home, End, select all, copy) and the pointer (drag, double click), but typing, pasting and cutting do nothing, and keys it does not use reach the app. Addresses in the text are links, underlined, that open on a click.

pub fn set_read_only(&mut self, read_only: bool)

pub fn is_read_only(&self) -> bool

pub fn with_runs(self, runs: Vec<RichSpan>) -> TextInput

Show runs as the text, each in its own weight, slant, size and ink: a message body, a help page. A caller that edits the text afterwards loses the styling; use it with Self::with_read_only.

pub fn set_runs(&mut self, runs: Vec<RichSpan>)

pub fn place_wrapped( &mut self, rect: Rect, tr: &mut TextRenderer, theme: &Theme, ) -> f64

Lay a wrapping field out in rect’s width at rect’s top-left without a layout tree, for a host that paints it itself; the rect it takes is as tall as its text, and that height is returned.

pub fn with_links(self, links: Vec<(Range<usize>, String)>) -> TextInput

Targets for byte ranges of a read-only text whose words are not their own address (an HTML mail’s “click here”). These win over the addresses found in the prose.

pub fn set_links(&mut self, links: Vec<(Range<usize>, String)>)

pub fn interaction(&self) -> InteractionEnvironment

What inputs the host has: a coarse one makes the field a finger’s target tall.

pub fn own_width_in(theme: &Theme) -> f32

The width a field stands at where nothing else sets it: the theme’s field_min_width, grown with the text it holds.

pub fn is_dragging(&self) -> bool

For BlockEditor’s cross-block drag coordinator.

pub fn handle_chrome_pointer( &mut self, event: &WindowEvent, scale_factor: f64, modifiers: Modifiers, ) -> bool

Handle a pointer event for a chrome surface that owns this field outside the retained widget tree: the chrome lays the field out itself but still wants the toolkit’s caret placement, drag selection, double-click words and right-click menu. Returns whether the field took the event.

The caller keeps its own text and selection; read the selection back with Self::selection_anchor_focus_or_caret after a true answer.

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.

impl TextInput

pub fn completion(&self) -> TextCompletion

What this field offers inline: emoji from the toolkit’s catalogue and mentions from the workspace’s roster, both by default for prose. A secret or numeric field offers neither whatever its owner asks, so nothing can be inserted into it and nothing echoes it.

pub fn with_completion(self, completion: TextCompletion) -> TextInput

Set what the field offers inline. Mark a search field, a code field, a URL or a terminal plain here: : and @ are syntax there, so completion is wrong rather than unavailable.

pub fn set_completion(&mut self, completion: TextCompletion)

Self::with_completion on a live field.

pub fn with_mention_candidates( self, candidates: Vec<MentionCandidate>, ) -> TextInput

People the app knows of that the workspace’s presence does not (someone who wrote in a channel and has since left): offered after the roster for @ completion.

pub fn set_mention_candidates(&mut self, candidates: Vec<MentionCandidate>)

Self::with_mention_candidates on a live field.

pub fn is_completion_open(&self) -> bool

Whether a :emoji: or @mention candidate list is open beside the caret.

pub fn set_completion_sources(&mut self, sources: Vec<CompletionSource>)

Complete from sources, one per trigger, as the system gives them (the workspace’s resources for #, the actions available here for /): they take the place of the built-in : and @ for their triggers, and add the rest. They are given once; every keystroke filters them here.

pub fn set_on_completion_create( &mut self, create: impl FnMut(char, &str) + 'static, )

Run create with the trigger and the typed name when the person picks “Create …” in a drawer whose source allows it.

pub fn set_on_command(&mut self, start: impl FnMut(&Candidate) + 'static)

Run start with the command a person picked from a / drawer: its owner turns the field into the command’s chip and parameter fields.

pub fn pending_token(&self) -> Option<Range<usize>>

The token the open drawer answers, as typed (@mi), for tests and the pending tint.

pub fn set_on_reference_inserted( &mut self, inserted: impl FnMut(char, Range<usize>, &str) + 'static, )

Run inserted with the trigger, the range and the reference each time a pick writes a candidate that names one: a rich field marks the run.

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 Described for TextInput

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

The text it edits, what it says and how it behaves change where the field stands: it keeps the keyboard, the caret and whatever is being composed into it.

type Props = TextInputProps

fn from_props(key: &str, props: TextInputProps) -> TextInput

The widget of props, with key its stable id.

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

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

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

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

impl 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

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.

fn shared_selection(&self) -> Option<SharedSelection>

The selected text while focused. A field is no resource item, so it names no place; a secret field shares nothing.

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

Whether this widget is composing a message where it stands (a conversation’s composer holding a draft): published under the key beside it, so a reader can say “… is typing”. Ephemeral, a presence frame; never what the draft says.

impl PublishesResources for TextInput

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

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

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

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

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

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

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

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

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

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

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

Resolve an addressable resource omitted from the contextual snapshot.

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

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

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

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

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

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

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

Self::resource in participant’s tree.

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

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

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

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

impl ResourceOperations for TextInput

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

Answer a submit or a change addressed to this field: hand its text to the field’s handler, whoever submitted or edited.

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>

Every type this widget and its subtree dispatch.

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

Poll one admitted operation without blocking the UI thread.

impl 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 take_focus_request(&mut self) -> Option<String>

A field made for the person to type in right away takes the keyboard in the tree it stands in, once. It names itself as the runner finds it (Self::test_id).

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

Read the field’s bound state. A sync is a read of what the document holds, not a paint: a field lending its document after a frame’s draw would otherwise ask for a frame forever, and the flags of the pieces that do move (a paste landing, a bound value replaced) are theirs to raise below.

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 (0 here) and measures at its own width where it is given none. 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 an edit or a model change that reshapes multiline or attributed text (layout_dirty, cleared by measure). Whether the owner has taken the edit yet (dirty) is not one of them, so an edit is measured in one frame however long its owner waits to publish it, and idle inputs are never re-measured.

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 when something it shows moved; the show/hide control’s own paint is a child’s. Asking unconditionally kept every window that holds a field painting forever, which is what an idle window costs: nothing changed, so nothing is drawn. The pending edit notification (Self::dirty) is left out for the same reason: an owner that reads the text when the person submits leaves it standing, and a field sitting in a window people are not touching must not keep that window drawing.

fn wants_tab_input(&self) -> bool

An open completion drawer takes Tab to insert its selected row.

fn accessibility_hidden(&self) -> bool

The node above never sets hidden; answer without cloning the text.

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

A glide after the fingers lifted moves the text on in the frames it asks for.

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

Paints the open context menu and the candidate list here so they float above every sibling regardless of tree order.

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 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 as_any_mut(&mut self) -> Option<&mut (dyn Any + 'static)>

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

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

fn mark_drawn(&mut self)

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

fn is_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 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_content(&self) -> Option<InputContent>

The focused widget wants platform text input (Wayland text-input-v3, native IMEs elsewhere). None is intentionally the default: enabling an IME for buttons, canvas tools or games makes the compositor raise an on-screen keyboard over content that cannot accept the committed text.

fn ime_multiline(&self) -> bool

Whether the original focused editor accepts line feeds as text. This is field policy, never inferred from a multiline accessibility presentation. Wrappers inherit only one unambiguous child at their active IME caret.

fn ime_edit_fingerprint(&self, key: &[u8; 32]) -> Option<[u8; 32]>

Opaque local invalidation of deferred input, including selection edits that leave the caret rectangle unchanged. The host supplies an ephemeral secret key; no text or selection is retained in the resulting digest. The default shares the accessibility door and excludes protected or read-only controls. Text controls can override it to avoid cloning text.

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

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

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

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

fn 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 or selection, action availability, resource declaration, pending command or work that requires sync. The runner still lays out, paints and refreshes accessibility geometry; unknown handlers stay on the full path.

fn primary_vertical_scroll(&self) -> Option<PrimaryScrollRegion>

Explicit app-owned region; never search secondary children implicitly.

fn apply_primary_vertical_scroll( &mut self, _action: PrimaryScrollAction, ) -> PrimaryScrollResult

fn callback_binding(&self) -> Option<CallbackBinding>

Runtime binding inherited by descendants in a matching layout topology.

fn has_separate_document_owner(&self) -> bool

Whether this widget introduces a document owner distinct from the runner’s outer State. This is a compatibility check, never identity or authority for history access or restore.

fn history_owner(&self) -> Option<HistoryOwner>

Opaque actual custody for framework History source registration.

fn record_owners(&self) -> Vec<HistoryOwner>

Records this widget keeps open beside the document it shows, each synced on its own route: a framework app’s records in the person’s own workspace (crate::record::person). They take no part in this widget’s history or controls.

fn mount_native_views(&mut self, host: &NativeViewHost<'_>)

Attach native child views through this owner’s retained lifecycle topology. Presentation containers with inactive or hidden live descendants override this traversal so lifecycle ownership stays independent of drawing and input visibility.

fn unmount_native_views(&mut self)

Tear native children down while their parent window still exists.

fn native_view_frame_start(&mut self)

Begin a native-view frame through this owner’s retained lifecycle topology.

fn set_platform_conventions(&mut self, conventions: PlatformConventions)

Receive host-selected platform conventions. The default propagates to retained children, keeping target-OS branches out of app code.

fn set_window_bar_control(&mut self, in_bar: bool)

Tell this widget whether it stands in a window bar. A bar’s controls are drawn at the bar’s control height whatever the pointer; the target a finger needs reaches beyond the drawn shape, invisibly. The default propagates to children.

fn settle(&mut self, edits: &mut Edits<'_>, path: &ExId)

Apply, after the sync pass, what the widget took up there and must write: a worker’s answer, a chooser’s file, an event a child queued. Writes go only through typed actions on edits; the host syncs again when the document changed. The default settles the returned children.

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

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

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

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

fn observe_physical_input(&mut self, _input: PhysicalInput)

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

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

The children of Self::for_each_child that may paint inside the layout_clip in effect: what a scroll view’s damage and copy plan need. Every child by default; a long column visits only those near the clip, so a frame costs what is shown, not what the column holds.

fn for_each_hosted_child(&self, _visitor: &mut dyn FnMut(&dyn Widget))

Children this widget keeps in the retained tree but does not route input to: a subtree it does not own and answers the person’s events for itself, like a host drawing another widget’s card over the windows. Inspection, named controls and the accessibility tree walk these after the children Self::children lists, so what is walked there keeps the paths, sibling indices and registry entries it had.

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

Every child this widget’s Self::build_layout gives a layout node, also those Self::for_each_child keeps from routing (a hidden pane, a title, a spacer). A retained layout is checked against this walk before it is called through again, so a widget that replaced a child without reporting it gets a new layout instead of a call into freed memory. A child missing here cannot be checked, so debug builds stop on it. A wrapper that stands for its inner widget’s node visits the inner widget itself.

fn window_slot(&self, _id: String) -> Option<ToolbarAction>

This control as an action of the window’s bar, sent back as id (crate::window_toolbar::ToolbarAction): a button’s icon and name. None for anything that is not a button.

fn stands_for(&self, address: *const ()) -> bool

Whether this widget is the one at address, or stands in the tree for it: a Decorator stands for every widget it wraps, so a scroller drawn inside one is found where the decorator is (crate::scroll_copy::offer).

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

Context that should remain visible with a focused descendant, such as a form control and its validation message. Opt-in scroll containers use this block when it fits; otherwise they prioritise the control.

fn reveal_descendant(&mut self, target: *const dyn Widget) -> bool

Reveal a newly keyboard-focused descendant inside any enclosing viewport. Containers override this to scroll; ordinary widgets simply recurse toward the target and report whether it was found.

fn test_rects(&self) -> Vec<(String, Rect)>

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

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

Absolute logical clip applied to ordinary children during painting and pointer routing. Inspectors and enclosing scroll regions must respect this boundary instead of treating clipped descendants as visible extent.

fn snap_points(&self, axis: ScrollAxis, out: &mut Vec<f32>)

Offsets along axis that this widget, as a scroll view’s content, offers it to settle on, measured from its own leading edge: a board’s lanes (crate::widget::Board). None leaves a scroller stopping wherever the hand left it.

fn take_action_palette_request(&mut self) -> Option<ActionAddress>

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

fn take_search_request(&mut self) -> bool

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

fn 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 touch_claim(&self, _point: Point) -> TouchClaim

What a one-finger contact that begins at point (logical coords) means here, when a drag moves something rather than scrolling.

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

Revealed after a dwell over the widget’s rect, via the toolkit’s one tooltip mechanism (crate::widget::tooltip::TooltipHost), hit-tested like cursor_shape so containers need not forward it. An icon-only control should also use this as its accessible name.

fn tooltip_side(&self) -> TooltipSide

Which side of the control its tooltip goes: below by default, beside it for a control in a vertical rail.

fn is_default_keyboard_focus(&self) -> bool

Preferred control when its app is explicitly activated without a valid saved control. Hosts still enforce visibility, enabled state and scope.

fn keyboard_input_scope(&self) -> Option<u64>

Exact app instance whose non-text shortcuts this subtree owns when activation has no control target. Unbound desktop chrome may declare the active tab; component boundaries default to their captured owner.

fn set_full_bleed(&mut self, _full_bleed: bool)

The window holding this content fills its display (a maximized window): it has nothing beside it to round its corners against or to set it apart from, so content that frames or clips itself to the window’s shape draws edge to edge instead. A client surface drawn that way, last and unclipped, is one the display can scan out directly. Content that frames nothing ignores it.

fn 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 context_menu_anchor(&self) -> Option<Rect>

The box a context menu opened from the keyboard stands against: the item that has the keyboard, so the menu opens under it rather than under the whole widget. A widget that holds items (a list) answers for the one with the keyboard; None leaves the menu to stand under the focused widget’s own box.

fn traps_focus(&self) -> bool

While any widget answers true, the host restricts Tab/directional focus to this subtree (wrapping at the ends) and restores the prior focus once it goes back to false. Default false.

fn scopes_keyboard_focus(&self) -> bool

Whether Tab and directional focus travel stay inside this subtree while no trap holds focus: the content of the focused desktop window, so keyboard travel cycles through the app the person is in and never wanders onto the desktop’s chrome (its bars, menus and window titles), which the keyboard reaches through its own shortcuts. Unlike Self::traps_focus it moves no focus when it starts or ends, and pointer input is unaffected. Default false.

fn take_app_activation(&mut self) -> Option<u64>

One-shot (reading MUST clear it): the app instance the person just brought forward (a window they opened, clicked or switched to), whose keyboard focus the host restores, or puts on its default control, so what they type next reaches it. Default forwards the first request found among the children.

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

Self::accessibility with its synthetic children shared, for a widget that keeps them between frames: each child it did not change is handed over as the very Arc of the last frame, which the semantic tree takes as unchanged without copying or comparing it.

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

Self::accessibility’s own node with its children left empty: its role, identity (semantic_key) and state. Focus capture and focus order read only these, for every node on every frame, so a widget whose node carries a large subtree (a document exporting its every block) answers without building it. An override must equal accessibility() with children cleared.

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

Move this widget’s own immediate-mode focus to a synthetic semantic child. Retained widgets continue to use the ordinary taffy focus path.

fn accessibility_child_parent(&self, _child_index: usize) -> Option<usize>

Reparent one retained children entry beneath a synthetic child returned by accessibility. The returned index addresses AccessNode::children for this frame. Collections use this to place a real interactive row delegate inside its virtual ListItem/TreeItem instead of exporting a duplicate.

fn accessibility_child_path(&self, child_index: usize) -> Option<Vec<usize>>

Reparent one retained children entry beneath a nested path of synthetic children returned by accessibility.

fn accessibility_represents_child(&self, _child_index: usize) -> bool

Whether one retained children entry is already represented in this widget’s own synthetic accessibility tree, so the bridge must not export it a second time. A host that publishes a child’s semantics itself (to add its own controls inside the same dialog) answers true for that child; assistive technology then sees one copy, not two.

fn lays_out_child(&self, _child_index: usize) -> bool

Whether this widget lays one retained children entry out itself (an Embedded part of a painted page) rather than through the window’s layout, which then gives it no node. The accessibility walk reaches such a child, and every widget inside it, through this widget’s node.

fn accessibility_child_description(&self, _child_index: usize) -> Option<String>

What describes one retained children entry to assistive technology, when this widget holds the words for it: a row’s secondary line is its trailing switch’s description. The bridge sets it as that child’s node’s description unless the child describes itself.

fn is_enabled(&self) -> bool

A disabled (false) widget is excluded from focus traversal, must reject input in handle_event, and renders dimmed (see DISABLED_ALPHA).

fn ime_requires_deferred_ack(&self) -> bool

This field needs a host that consumes deferred receipts. Ordinary native Wayland windows must not advertise it until they have that delivery path.

fn ime_refuses_ordinary_commits(&self) -> bool

Ordinary input-method commits (a composing keyboard IME, the on-screen keyboard) cannot reach this field: its text arrives only through deferred receipts (a browser page field), so hosts keep standard text input closed outside a dictation session. A field that needs deferred receipts for dictation but turns an ordinary commit into its own acknowledged edit (Terminal’s native editor) does not refuse them.

fn start_deferred_text(&mut self) -> Option<Receipt>

Begin one bounded deferred session after explicit host consent, preserving the existing original-field fingerprint. This grants no microphone access.

fn commit_deferred_text(&mut self, text: &str) -> Option<Receipt>

A private asynchronous final. None leaves ordinary synchronous IME dispatch to the host. A receipt binds this original field and must be acknowledged before the host releases its private recovery transcript.

fn presented(&self) -> bool

Default true; false only for a widget standing in for a window’s content whose first frame has not drawn. Must latch: once true, never false again for the same content.

fn arrives_from(&self) -> Source

Where this content’s first frame comes from while it has not presented: this device (an app starting here), another device or a host. A frame from this device may hold the window’s first frame up to one frame budget; any other reserves the window’s place and says where it comes from after a while.

fn arrival_progress(&self) -> Option<Progress>

How much of what this content’s first frame waits on has come, when that measures itself (its app downloaded before it starts).

fn arrival_shape(&self) -> SkeletonShape

The shape this content declares for the placeholder standing in for its first frame. Undeclared, the placeholder is the ground alone: nothing guesses what a window will show.

fn on_external_event( &mut self, _payload: &str, _state: &mut Edits<'_>, _root: &(dyn Any + 'static), )

Delivers an out-of-band string payload from crate::app::UserEvent::External (e.g. a worker thread streaming output into a status log). Default no-op; the App redraws and re-syncs after dispatch, so mutating state here is enough.

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

Global back/forward gesture (swipe/edge-pull), recognised by crate::gesture::NavGestureRecognizer and delivered to the whole tree; return true once consumed. Default forwards to children, so a widget that owns history becomes swipe-navigable for free.

fn nav_availability(&self) -> NavAvailability

Which directions Self::on_nav_gesture would consume now. A widget that owns history overrides this beside on_nav_gesture.

fn take_focus_reset(&mut self) -> bool

One-shot (reading MUST clear it) signal to move focus to this subtree’s first focusable widget after the next rebuild. Only consulted under crate::app::App::autofocus_on_structure_change; a wizard raises it on step transitions.

fn take_accessibility_request(&mut self) -> Option<AccessibilityRequest>

One-shot (reading MUST clear it) request to change the window’s accessibility preferences, raised by a control the person used. The host applies it before the next frame. Default forwards the first request found among the children.

fn dev_route(&self) -> Option<RouteSnapshot>

Route history when this widget, or one it contains, is a Router.

fn restore_dev_route(&mut self, route: &RouteSnapshot) -> bool

Put route back. Returns whether a router in this subtree accepted it.

fn appearance_intent(&self) -> Option<AppearanceIntent>

Theme/high-contrast/reduced-motion/scale, polled under crate::app::App::appearance_reconcile — how a settings pane re-themes the running app live without a back-channel. Level-triggered; the App recurses Self::children itself, so containers need not forward it. First Some wins.

fn minimum_window_width(&self) -> Option<f64>

The narrowest this window still works at, in logical pixels: the minimum of its compact layout (a NavShell answers with one column at a time). The host states it to the window system, so the desktop stops a resize there. None: no opinion. The host walks the tree itself (minimum_window_width), so containers need not forward it; the first Some wins.

fn preferred_window_size(&self) -> Option<(f64, f64)>

The whole size this window wants, in logical pixels, when the app is the window’s only content and knows how big it must be: the on-screen keyboard parked to a strip. The host states it as the window’s minimum and maximum, so the desktop shapes the surface to it. None: the window is the user’s and the app lays itself out in whatever it gets.

fn set_motion_reduced(&mut self, reduced: bool)

Apply the effective reduced-motion preference before the host asks this subtree whether it needs another animation frame. The default forwards recursively, making the preference a framework policy instead of an optional convention that every container has to remember to implement.

fn needs_idle_sync(&self) -> bool

Whether sync still needs to run on idle frames without input or collab events — e.g. waiting out a document-adoption grace window.

fn disclosing(&self) -> Option<Disclosing>

While this widget is a band on its way in or out (motion::Disclosure: an in-window banner arriving or leaving), or a content-sized container one moves in, how far what follows it is drawn from where it is laid out. A moving band stands out of the layout; its container places it (Self::place_disclosing) and draws the widgets after it lower by transform, so they move with the band’s edge instead of being laid out again every frame. None at rest (the default).

fn place_disclosing(&mut self, _slot: Rect)

Where a band on its way (Disclosing::Band) stands while it is out of the layout: its slot’s top and width (slot’s height is zero), set by its container after each layout.

fn is_band(&self) -> bool

A band that comes and goes (an in-window banner): when its view stops building it, its column draws it leaving (widget::Disclosing). Its column leaves it out of its identity across rebuilds.

fn note_placement(&mut self, _placement: Placement)

Where a band stands in its column, set by the column after each layout: what it leaves when dropped, so the column a rebuild makes can draw it leaving.

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

Why this widget itself asks for animation frames, for diagnostics that name a desktop which keeps painting. None when it has nothing to add to its name and geometry.

fn holds_frame_until(&self, now: Instant) -> Option<Instant>

Until when the frame that would show this subtree waits for data it reads from this device (crate::arriving): a local read that has not answered and is still inside its frame budget. The host keeps the frame on screen until then, or until the data lands, so the person never sees the space empty and then filled. Containers forward (the default does).

fn serve_deadline(&mut self, _now: Instant) -> bool

A deadline this subtree asked for (Self::next_wake_deadline) is due at now: do the work it was for, and say whether anything changed. The default says it did.

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

Close every modal this subtree presents, as its own way out does (a host whose surface is a modal sheet calls it when the shell takes the sheet down). Whether any was presented; containers forward.

fn presents_modal(&self) -> bool

Whether this subtree presents a modal still drawn (arriving, open or leaving): the counterpart of Widget::dismiss_presented_modal.

fn take_structure_dirty(&mut self) -> bool

True if this subtree’s structural composition changed since the last frame; reading clears it. The default drains every retained child and reports whether any was dirty.

fn 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 remount_children(&mut self, remount: &mut Remount<'_>) -> bool

Carry out a StructureChange::Children this widget or one under it reported, in the retained layout tree, through remount (see remount). Returns false when it cannot be carried out in place: the host then rebuilds its tree, and the change is carried out by Self::build_layout. A widget reports such a change until either has carried it out. The default carries out its children’s.

fn has_pending_visual_work(&self) -> bool

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

fn has_transient_feedback(&self) -> bool

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

fn damage_covers_own_box(&self) -> bool

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

fn mark_children_drawn(&mut self)

Rest this widget’s children after a frame drew them, for a widget that keeps its own dirty flag: it clears the flag itself, then calls this.

fn release_scene_cache(&mut self)

Release retained encoded-scene storage in this subtree without marking its visual/model state dirty. Outer caches call this after a successful reuse: while the outer display list is authoritative, keeping byte-for-byte descendant encodings only duplicates memory. A later outer rebuild causes descendants to record/cache normally.

fn composition_follows_allocation(&self) -> bool

Whether this widget composes its children from the size it was last allocated (it reads its own rect while building its layout: a compact layout under a width, a count of columns, an inset from a drawer). A window resize then needs a second composition against the new allocation, as well as the re-solve every resize gets. Widgets that compose independently of their allocation, or that report take_structure_dirty themselves when a new allocation changes what they show, keep the default: a resize re-solves the retained tree in place instead of recomposing all of it.

fn paint_bounds(&self) -> Rect

Everything this widget paints, children included; draw_child skips the draw when it misses the viewport. Override for widgets that paint past their own rect.