Struct Locator 

pub struct Locator { /* private fields */ }

A lazy, re-resolving handle to one or more AT-SPI elements.

See the module-level documentation for the resolution model.

Implementations

impl Locator

pub fn xpath(&self) -> &str

The XPath expression this locator resolves with.

pub fn with_timeout(&self, timeout: Duration) -> Locator

Return a new locator with a per-call timeout override for auto-wait and wait_for_* methods. Duration::ZERO means “try once, don’t wait,” useful for negative assertions (“this element should NOT exist right now”).

pub fn locate(&self, sub: &str) -> Locator

Scope a sub-expression to the nodes matched by this locator.

If sub is absolute (starts with /), it replaces the current selector entirely. Otherwise it’s evaluated as descendants of the current matches: (self)//sub.

pub fn nth(&self, n: usize) -> Locator

Return a locator pinned to the n-th (0-indexed) match of this one.

pub fn first(&self) -> Locator

Shorthand for nth(0).

pub fn last(&self) -> Locator

Locator for the last match of this selector.

pub fn parent(&self) -> Locator

Locator for the parent of the matched element(s).

pub async fn count(&self) -> Result<usize>

Number of elements matched by this selector. Does not auto-wait — returns the current count, which may be zero.

pub async fn all(&self) -> Result<Vec<Locator>>

Enumerate each match as a locator pinned by ordinal.

Each returned locator still re-resolves (so ordinal pins are evaluated on each use, not frozen to the AT-SPI identity observed at all() time).

pub async fn inspect_all(&self) -> Result<Vec<ElementInfo>>

Take one AT-SPI snapshot and return full metadata for every match.

More efficient than calling all() and then metadata methods on each returned locator, which would re-snapshot per match.

pub async fn name(&self) -> Result<Option<String>>

Accessible name of the matched element, or None when the element has no accessible name set.

pub async fn role(&self) -> Result<String>

Raw AT-SPI role name (e.g. "push button", "menu item").

Falls back to the PascalCase XML element tag only when the snapshot lacks a role attribute — which shouldn’t happen for live snapshots, but can in hand-crafted test XML.

pub async fn attribute(&self, key: &str) -> Result<Option<String>>

Read a single toolkit attribute by key.

pub async fn attributes(&self) -> Result<HashMap<String, String>>

All toolkit attributes as a map.

pub async fn is_showing(&self) -> Result<bool>

Whether the matched element currently has the Showing state.

pub async fn is_enabled(&self) -> Result<bool>

Whether the matched element is currently interactable.

Returns true when the element has either the AT-SPI Enabled state or the Sensitive state — GTK reports the latter, Qt/others the former. Both mean “user can interact with this widget right now.”

pub async fn text(&self) -> Result<String>

Text contents of the matched element via the AT-SPI Text interface. Unlike other metadata, text isn’t captured in the snapshot — each call makes a live read through the Text proxy after auto-waiting for the element to exist.

pub async fn click(&self) -> Result<()>

Invoke the primary action (index 0) on the matched element.

Auto-waits for the element to be resolvable, showing, and enabled within the effective timeout. Requires exactly one match.

pub async fn set_text(&self, text: &str) -> Result<()>

Replace the contents of an editable text element.

Auto-waits for the element to be resolvable, showing, and enabled.

pub async fn focus(&self) -> Result<()>

Give keyboard focus to the matched element.

Auto-waits for the element to be resolvable, showing, and focusable — the last is a weaker check than “actionable” because some widgets accept focus without accepting activation (read-only text boxes, scroll regions, etc.). Uses AT-SPI’s Component::grab_focus under the hood.

Toolkit caveats

This relies on the target widget implementing the AT-SPI Component interface. Some toolkits (notably GTK4 in its current form) don’t expose Component on all widgets — you may see Error::Atspi("NotSupported") from grab_focus even when the widget is visibly focusable on screen. When that happens the fallback is to drive focus via keyboard navigation (Tab / Shift+Tab) or synthesize a pointer click.

pub async fn wait_for_visible(&self) -> Result<()>

Poll until the element exists and has the Showing state. Returns Ok(()) on success or the last encountered retriable error (or a Timeout error if the element existed but never became showing).

pub async fn wait_for_hidden(&self) -> Result<()>

Poll until the element either doesn’t exist or doesn’t have the Showing state. The inverse of wait_for_visible.

pub async fn wait_for_enabled(&self) -> Result<()>

Poll until the element exists and is interactable (has either the Enabled or Sensitive state — see Locator::is_enabled for why both are treated as equivalent).

pub async fn wait_for_count(&self, n: usize) -> Result<()>

Poll until the selector matches exactly n elements. Useful for lists that populate asynchronously after a user action.

pub async fn wait_for_text<F>(&self, pred: F) -> Result<String>

where F: Fn(&str) -> bool,

Poll until the element’s text contents satisfy pred. Returns the matching text on success so the caller can inspect it further.

Trait Implementations

impl Clone for Locator

fn clone(&self) -> Locator

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.