Struct AccessNodeBuilder 

pub struct AccessNodeBuilder { /* private fields */ }

Builder wrapper around accesskit::Node for widget accessibility declarations.

Implementations

impl AccessNodeBuilder

pub fn new() -> Self

pub fn for_widget(owner: WidgetId) -> Self

Construct a builder with a known owner WidgetId. Used by the tree walker when invoking Widget::accessibility; the owner id drives synthetic NodeId derivation in the sub-tree API.

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

pub fn set_name(&mut self, name: impl Into<String>)

pub fn set_disabled(&mut self)

pub fn clear_disabled(&mut self)

Clear the disabled flag set by an earlier set_disabled() call. Used by the override layer to un-set state a widget emitted unconditionally (e.g. a Panel that always calls set_hidden/set_disabled).

pub fn add_action(&mut self, action: Action)

pub fn remove_action(&mut self, action: Action)

Remove a previously-advertised action. Used by the override layer (access_remove_action) to suppress an action a widget emitted but that doesn’t apply in this composition.

pub fn set_value(&mut self, value: impl Into<String>)

pub fn set_color_value(&mut self, color: Color)

Advertise a color value on this node — typically paired with accesskit::Role::ColorWell. Takes a teksilo_tokens::Color (f32 channels) and quantizes to AccessKit’s 8-bit Color representation.

pub fn set_description(&mut self, description: impl Into<String>)

pub fn set_live(&mut self, live: Live)

pub fn set_described_by(&mut self, ids: impl Into<Vec<NodeId>>)

pub fn push_described_by(&mut self, id: NodeId)

Append one node to the described_by relationship list. Mirror of the existing push_controlled; used by the override layer’s access_described_by builder method and by the framework’s tooltip wiring.

pub fn push_labelled_by(&mut self, id: NodeId)

Append one node to the labelled_by relationship list. Used by access_labelled_by to point at an external label widget.

pub fn set_details(&mut self, ids: impl Into<Vec<NodeId>>)

Replace the details relationship list — AccessKit’s analogue of aria-details.

Distinct from described_by, and deliberately so: a description is text a screen reader appends when announcing the element, while details points at a structured node the user can navigate into. The W3C annotations pattern is built on that difference — an annotated run carries aria-details to a role="comment" node, so the reader can say “has comment” and let the user go read it, rather than reciting a whole thread inline every time the caret crosses the span.

pub fn push_detail(&mut self, id: NodeId)

Append one node to the details relationship list.

It is a list, not a single id, because overlapping annotations are normal: one run of text can carry several comments, and each gets its own entry.

pub fn set_author_id(&mut self, id: impl Into<String>)

Stable author-supplied identifier (test/debug id, equivalent to aria-label-style data-testid). Maps to accesskit::Node::set_author_id.

pub fn set_custom_actions(&mut self, actions: Vec<CustomAction>)

Replace the node’s custom-action list with actions. Used by the override layer’s access_custom_action builder method.

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

pub fn set_expanded(&mut self, expanded: bool)

pub fn set_has_popup(&mut self, kind: HasPopup)

pub fn set_placeholder(&mut self, placeholder: impl Into<String>)

Placeholder text displayed when the widget has no user-entered value yet. Screen readers treat this distinctly from value — they’ll announce the placeholder as hint text rather than as the current value. Used by ComboBox when selection is None, by TextInput before the user types, etc.

pub fn set_url(&mut self, url: impl Into<String>)

Target URL for link-like widgets. Maps to aria-url / platform link metadata so screen readers can announce the destination (e.g. “link, https://example.com”). Informational only — does not navigate when activated.

pub fn set_keyboard_shortcut(&mut self, shortcut: impl Into<String>)

Keyboard shortcut announcement (e.g. "Ctrl+S"). Maps to aria-keyshortcuts. Used by menu items and buttons whose chord is shown visually but must also be exposed to assistive tech so shortcut users discover it.

pub fn set_auto_complete(&mut self, kind: AutoComplete)

Autocomplete behavior for combobox / text input widgets. Maps to ARIA aria-autocomplete: Inline completes within the field, List shows a popup of matching values, Both does both.

pub fn set_selected(&mut self, selected: bool)

Selection state — used by RadioButton, Tab, ListBoxOption, TreeItem, menu items in radio/check groups, etc. This is the correct property for “this option in a mutually exclusive group is the active one”; don’t confuse with set_toggled, which models checkbox/switch on-off state.

pub fn set_orientation(&mut self, orientation: Orientation)

pub fn set_position_in_set(&mut self, position: usize)

1-based index of this item in its parent set — maps to ARIA aria-posinset. Pair with set_size_of_set on every item in the set so AT can announce “tab 3 of 5”, “row 12 of 200”, etc. Use on Role::Tab, Role::ListBoxOption, Role::Row, Role::MenuItem, and similar collection items.

pub fn set_size_of_set(&mut self, size: usize)

Total number of items in this item’s parent set — maps to ARIA aria-setsize. Set on every collection item alongside set_position_in_set; the value should reflect the logical set size, not the visible window (e.g. report 200 for a virtualized 200-row list even when only 20 rows are realized).

pub fn set_row_count(&mut self, count: usize)

Total logical row count on a grid/table container (aria-rowcount).

pub fn set_column_count(&mut self, count: usize)

Total logical column count on a grid/table container (aria-colcount).

pub fn set_row_index(&mut self, index: usize)

1-based row index of a cell / row (aria-rowindex).

pub fn set_column_index(&mut self, index: usize)

1-based column index of a cell (aria-colindex).

pub fn set_row_span(&mut self, span: usize)

Number of rows a cell spans (aria-rowspan).

pub fn set_column_span(&mut self, span: usize)

Number of columns a cell spans (aria-colspan).

pub fn set_multiselectable(&mut self, value: bool)

Whether the container allows multiple selected items (aria-multiselectable). Set on the Role::Grid / Role::ListBox container in multi-select mode.

pub fn set_active_descendant(&mut self, id: NodeId)

The currently-active descendant (aria-activedescendant) — the roving-focus pattern where focus stays on a composite container and this points at the focused child (e.g. the focused grid cell).

pub fn set_modal(&mut self)

Flag the node as a modal dialog. Use on Role::Dialog / Role::AlertDialog when input is blocked outside the dialog.

pub fn set_aria_current(&mut self, current: AriaCurrent)

Mark this node as the current item within its container (e.g. the “current page” crumb inside a Navigation, the current step in a wizard). Maps to ARIA aria-current.

pub fn set_numeric_value_step(&mut self, step: f64)

Single-step delta for Slider / SpinButton — how much the value changes per keyboard arrow or Action::Increment tick.

pub fn set_numeric_value_jump(&mut self, jump: f64)

Page-step delta for Slider / SpinButton — how much the value changes per PgUp/PgDown or coarse adjustment.

pub fn push_controlled(&mut self, id: NodeId)

Append a controlled-node relationship — e.g. a Tab pointing at its matching TabPanel, a ComboBox pointing at its listbox popup. AccessKit / ARIA equivalent of aria-controls.

pub fn push_to_radio_group(&mut self, id: NodeId)

Declare this radio button’s membership in a radio group. Each RadioButton node should push every sibling in its group (including itself); screen readers use this to announce positional info like “2 of 3”.

pub fn set_numeric_value(&mut self, value: f64)

pub fn set_min_numeric_value(&mut self, value: f64)

pub fn set_max_numeric_value(&mut self, value: f64)

pub fn set_hidden(&mut self)

Hide this node from all assistive technologies (equivalent to aria-hidden="true"). The node is still in the widget tree but is invisible to screen readers and other ATs. Use for purely decorative elements — e.g. scrollbars (AT scrolls via the parent ScrollView’s scroll actions instead).

pub fn clear_hidden(&mut self)

Clear the hidden flag set by an earlier set_hidden() call. Used by the override layer to re-expose a widget that marked itself presentational. AccessKit’s Node hidden is local — un-hiding this node does not propagate to descendants, but descendants are not transitively hidden by their ancestor’s hidden either.

pub fn is_hidden(&self) -> bool

pub fn role(&self) -> Role

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

pub fn actions(&self) -> &[Action]

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

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

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

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

pub fn build(self, id: WidgetId) -> (NodeId, Node, Vec<(NodeId, Node)>)

Build the AccessKit Node with the given ID. Resolves any pending_self_selection recorded via set_caret_position_on_self or set_text_selection_on_self — at this point we know the widget’s NodeId and can inject it into the text selection. Returns the primary (NodeId, Node) pair plus any synthetic child nodes emitted by the widget via push_paragraph_child / push_text_run_child. The tree walker is responsible for merging these into the final TreeUpdate.

pub fn inner_mut(&mut self) -> &mut Node

Get a reference to the inner node for advanced use.

pub fn owner_id(&self) -> Option<WidgetId>

The widget id this builder was constructed for, if any. Set by AccessNodeBuilder::for_widget; used by the scene-tree walker to derive synthetic NodeIds for items / groups outside the closure form (push_scene_child*).

pub fn with_collected_node<F: FnOnce(&mut Node)>( &mut self, node_id: NodeId, f: F, ) -> bool

Run a mutator over a synthetic child node previously pushed via push_scene_child (or its _under variant). Used by the scene walker to apply cross-tree decorations (relations / live regions / landmarks) after the initial hierarchy emit. Returns true if the node was found.

Cannot be used to mutate widget-derived NodeIds — those live in the global TreeUpdate and are owned by other widgets.

pub fn set_read_only(&mut self)

Mark this node as read-only. Used by RichTextEditor::read_only so screen readers announce the widget as a document rather than a form field.

pub fn set_text_selection( &mut self, node_id: NodeId, anchor: usize, focus: usize, )

Declare the current text selection. anchor and focus are character indices into the widget’s flat text representation; pass equal indices for a collapsed caret. Uses the same NodeId for both positions (typical for single-node text widgets that expose the document as one run, which is what the first milestone of RichTextEditor does).

pub fn set_caret_position(&mut self, node_id: NodeId, character_index: usize)

Convenience for exposing a caret position as a collapsed selection.

pub fn set_text_selection_on_self(&mut self, anchor: usize, focus: usize)

Declare a text selection whose anchor and focus live on the widget’s own AccessKit node. The widget doesn’t know its own NodeId inside accessibility(&self, builder) — it’s only resolved when the tree walker calls builder.build(widget_id). This method stashes the character indices and defers the set_text_selection call until build() knows the ID.

pub fn set_caret_position_on_self(&mut self, character_index: usize)

Convenience wrapper for a collapsed caret on the widget’s own node.

pub fn push_paragraph_child(&mut self, element_id: u64) -> NodeId

Push a Role::Paragraph child on the current node and return its NodeId. The NodeId is synthetic (bit 63 set) and deterministic given the owning widget + element_id.

The owning WidgetId comes from the builder’s owner field, set by AccessNodeBuilder::for_widget. Returns NodeId(0) (a no-op placeholder) if the builder has no owner, which can only happen when a widget constructs a builder manually via new() instead of going through the tree walker. That’s a programming error worth catching in debug.

pub fn push_annotation_child( &mut self, group_id: u64, text: impl Into<String>, ) -> NodeId

Push a Role::Comment child carrying an annotation’s text, and return its NodeId so the annotated run can point at it via Self::push_detail.

group_id must be the annotation’s own durable identity (a comment’s uid, never a store id), so the node keeps the same NodeId across rebuilds and a screen reader’s cursor is not thrown out of the thread by an unrelated edit elsewhere in the document.

Per the W3C annotations pattern the body carries the name; the annotated span itself must NOT be given an accessible name (role="mark" forbids it) — naming the span would make the reader announce the comment’s text in place of the prose.

pub fn push_detail_on_child(&mut self, child: NodeId, detail: NodeId)

Add a details target to an already-pushed child node.

The sub-tree API builds children eagerly into children_collected, so a relation between two synthetic siblings (a TextRun and its annotation body) cannot go through the current node’s own setters — it has to reach back into the collected child. A no-op if child was never pushed, which keeps a caller that emitted spans for a run it then skipped from panicking.

pub fn push_link_child( &mut self, element_id: u64, label: impl Into<String>, url: impl Into<String>, ) -> NodeId

Push a Role::Link child on the current node. Used by label widgets (e.g. TextWidget with .markup(true) enabled) to expose inline [label](url) links as individual accessible nodes alongside the parent’s own text.

element_id should be a stable identifier for the link inside the parent widget (typically the byte offset of the [ in the original markup source, so the NodeId survives identical re-layouts).

The returned NodeId is synthetic (bit 63 set) and deterministic given (owner, element_id).

pub fn push_scene_child( &mut self, element_id: u64, kind: SyntheticKind, customize: impl FnOnce(&mut AccessNodeBuilder), ) -> NodeId

Push a synthetic child node representing a lightweight SceneItem (or SceneGroup) emitted by teksilo_scene::SceneView. The caller customizes a sub-AccessNodeBuilder (mirroring the Widget::accessibility shape) and gets back the deterministic synthetic NodeId allocated for the (owner, element_id, kind) tuple.

kind must be SyntheticKind::SceneItem or SyntheticKind::SceneGroup; passing any other variant panics in debug.

Any further synthetic children the closure pushes (a SceneGroup containing nested SceneItems) are forwarded into the parent’s children_collected and re-parented under the just-pushed node via the closure’s own inner.push_child calls — same convention as push_paragraph_child → push_text_run_child.

pub fn attach_scene_child_under( &mut self, parent: NodeId, child: NodeId, ) -> bool

Append an existing synthetic node id as a child of a previously-pushed SceneGroup (or SceneItem) child. Used by the scene logical-tree walker to re-parent items under their declared logical group rather than as direct children of the SceneView.

Returns true if the parent was found (and the child was attached), false if the parent isn’t in children_collected — the caller misordered the pushes.

pub fn push_scene_child_under( &mut self, parent: Option<NodeId>, element_id: u64, kind: SyntheticKind, customize: impl FnOnce(&mut AccessNodeBuilder), ) -> NodeId

Like push_scene_child but lets the caller pick the parent. parent = None attaches to the widget’s own node (same behavior as push_scene_child); parent = Some(...) attaches to the previously-pushed scene-child with that id. The scene logical-tree walker uses this to nest scene items under declared A11yGroup parents.

Returns the deterministic synthetic NodeId for the new child. If parent was Some but the parent wasn’t found in children_collected, the child still gets created and recorded but ends up attached to the widget’s own node as a fallback (and a debug-assert fires).

pub fn set_paragraph_as_heading(&mut self, node_id: NodeId, level: u8) -> bool

Override a previously-pushed paragraph child’s role to Role::Heading with the given hierarchical level. Used by the rich text editor when a block carries a BlockFormat::heading_level. Returns true if the node was found and updated, false otherwise (caller misused the api — the paragraph must have been pushed earlier).

pub fn set_child_position_in_set( &mut self, node_id: NodeId, position: usize, size: usize, ) -> bool

Set 1-based position-in-set / size-of-set on a previously-pushed synthetic child (a paragraph, “line 42 of 200”).

AccessKit exposes position_in_set / size_of_set on every node, but set_position_in_set / set_size_of_set only touch the widget’s own node. This reaches a collected child by NodeId, the same way set_paragraph_as_heading does. Returns whether the child was found.

pub fn link_runs_on_line(&mut self, run_ids: &[NodeId])

Link a run of Role::TextRun children as one visual line, so assistive technology navigating by line treats them as a continuous line rather than fracturing at each formatting or chunk boundary.

Sets each run’s next_on_line to its successor and each successor’s previous_on_line to its predecessor (AccessKit’s doubly-linked same-line chain); the first run keeps no previous_on_line and the last no next_on_line, which is how the consumer detects the line’s ends. A slice of zero or one is a no-op. Every id must be a run pushed earlier via push_text_run_child.

pub fn push_text_run_child( &mut self, parent_node: NodeId, element_id: u64, fragment_offset: usize, value: String, character_lengths: Vec<u8>, word_starts: Option<Vec<u8>>, character_positions: Option<Vec<f32>>, character_widths: Option<Vec<f32>>, attrs: TextRunAttributes, ) -> NodeId

Push a Role::TextRun child under parent_node (usually a paragraph NodeId returned from push_paragraph_child, but may also be the widget’s own node for inline editors).

element_id is the stable id of the underlying text-document inline element; combined with parent_widget and a disambiguator it produces a synthetic NodeId that survives edits. fragment_offset is the block-relative character offset of this run — used as the disambiguator so two highlight-split sub-runs sharing one source element don’t collide.

character_lengths must be the UTF-8 byte length of each character in value, per AccessKit’s contract. Optional word_starts, character_positions, and character_widths populate the corresponding AccessKit properties.

Returns the allocated synthetic NodeId so the caller can reference it later when attaching a TextSelection via set_text_selection_to.

pub fn push_text_run_child_on_self( &mut self, element_id: u64, value: String, character_lengths: Vec<u8>, word_starts: Option<Vec<u8>>, ) -> NodeId

Push a single Role::TextRun child attached directly to the widget’s own node (no intervening Role::Paragraph). This is the single-line text-input shape: Role::TextInput → one Role::TextRun.

Required for screen-reader typing echo. accesskit_consumer’s supports_text_ranges() returns false for a text input that only sets character_lengths on its own node — it needs a Role::TextRun child. Without it the macOS adapter never emits AXSelectedTextChanged, so VoiceOver reads the value once on focus but never echoes characters/words while typing. Emit this even when value / character_lengths are empty so supports_text_ranges() is already true before the first keystroke (the change-diff’s old node must also support ranges for the notification to fire). Target the caret/selection at the returned NodeId via set_text_selection_to.

pub fn set_text_selection_to( &mut self, anchor: (NodeId, usize), focus: (NodeId, usize), )

Declare a text selection that references TextRun children previously emitted via push_text_run_child. Both the anchor and the focus are expressed as (NodeId, character_index) pairs where the character index is an index into the target TextRun’s character_lengths (NOT a document-absolute offset — per AccessKit’s contract).

Trait Implementations

impl Default for AccessNodeBuilder

fn default() -> Self

Returns the “default value” for a type.