Struct Element

pub struct Element { /* private fields */ }

Expand description

A live element with lazy navigation via a provider reference.

Element dereferences to ElementData, so all properties (role, name, value, states, etc.) are accessible via field access. Navigation methods (parent(), children()) call the provider on demand.

Elements are cheap to clone (they share the provider via Arc).

Implementations§

§

impl Element

pub fn new(data: ElementData, provider: Arc<dyn Provider>) -> Element

Create an Element from raw data and a provider reference.

pub fn data(&self) -> &ElementData

Get the underlying ElementData.

pub fn provider(&self) -> &Arc<dyn Provider>

Get the provider reference.

pub fn children(&self) -> Result<Vec<Element>, Error>

Get direct children of this element.

Each call queries the provider — results are not cached.

pub fn parent(&self) -> Result<Option<Element>, Error>

Get the parent element, if any (root-level elements have no parent).

Each call queries the provider — results are not cached.

pub fn pid(&self) -> Option<u32>

Get the process ID from the element data.

pub fn tree(&self, max_depth: Option<usize>) -> Result<TreeNode, Error>

Capture the subtree rooted at this element as a recursive snapshot.

max_depth limits traversal depth: 0 = only this node (no children), 1 = node + direct children, and so on. None traverses the full subtree.

pub fn dump(&self, max_depth: Option<usize>) -> Result<String, Error>

Render the subtree rooted at this element as an indented string.

Each line is {indent}{role} "{name}" [value="{value}"]. Returns the string without printing it. Same depth semantics as Element::tree.

pub fn press(&self) -> Result<(), Error>

Click / invoke this element via the accessibility action layer.

pub fn focus(&self) -> Result<(), Error>

Set keyboard focus to this element.

pub fn blur(&self) -> Result<(), Error>

Remove keyboard focus from this element.

pub fn toggle(&self) -> Result<(), Error>

Toggle a two- or three-state control (checkbox, switch).

pub fn select(&self) -> Result<(), Error>

Select this element (list item, tab, row).

pub fn expand(&self) -> Result<(), Error>

Expand a disclosure, menu, combo box, or tree item.

pub fn collapse(&self) -> Result<(), Error>

Collapse an expanded element.

pub fn show_menu(&self) -> Result<(), Error>

Open this element’s context menu or dropdown.

pub fn increment(&self) -> Result<(), Error>

Increment a numeric control (slider, spinner) by its platform step.

pub fn decrement(&self) -> Result<(), Error>

Decrement a numeric control (slider, spinner) by its platform step.

pub fn scroll_into_view(&self) -> Result<(), Error>

Scroll this element into the visible area.

No-op on macOS — the macOS accessibility API has no equivalent.

pub fn set_value(&self, value: &str) -> Result<(), Error>

Set the text value of this element. Replaces the entire value rather than inserting at the caret — use Element::type_text for insertion.

pub fn set_numeric_value(&self, value: f64) -> Result<(), Error>

Set the numeric value of this element (slider, spinner).

Returns Error::InvalidActionData if value is NaN or infinite.

pub fn type_text(&self, text: &str) -> Result<(), Error>

Insert text at the current cursor position.

Uses the platform accessibility API — never simulates keyboard events.

pub fn select_text(&self, start: u32, end: u32) -> Result<(), Error>

Select the text range from start to end (0-based character offsets).

Returns Error::InvalidActionData if start > end.

pub fn perform_action(&self, action: &str) -> Result<(), Error>

Perform an action by its snake_case name.

Use this for actions the element advertises in its actions list that don’t have a dedicated method. Well-known names ("press", "focus", etc.) also work — providers delegate to the named methods.