Struct LinuxProvider 

pub struct LinuxProvider { /* private fields */ }

Linux accessibility provider using AT-SPI2 over D-Bus.

Implementations

impl LinuxProvider

pub fn new() -> Result<Self>

Create a new Linux accessibility provider.

Connects to the AT-SPI2 bus. Falls back to the session bus if the dedicated AT-SPI bus is unavailable.

Trait Implementations

impl Provider for LinuxProvider

fn list_shell_surfaces(&self) -> Result<Vec<(ShellSurfaceKind, ElementData)>>

Enumerate desktop panels and docks.

A Linux shell surface is a top-level AT-SPI frame whose attribute set carries window-type:dock — how panels self-identify, from xfce4-panel’s panel and dock rows to GNOME’s and KDE’s shells. One surface per such frame, so a panel process that owns two rows yields two ShellSurfaceKind::Panel entries, each with the panel process’s pid. Panels are commonly unnamed; the frame’s name is then None and the core falls back to the kind.

Panel is the only kind Linux vends: the desktop has no menu bar, taskbar, or dock object of its own, and StatusNotifierItem menus live on com.canonical.dbusmenu, a different subsystem from AT-SPI. Their absence from the listing is honest scope, not failure.

The scan runs over list_apps rather than its own registry walk, so it inherits that enumeration’s empty-name filter: a panel that registers on the bus without a name is invisible here for the same reason it is invisible to App::list.

Errors

A top-level that was just enumerated but will not answer GetRole or GetAttributes fails the listing (tenet 1). Those two calls are how a frame is classified, and Panel is the only kind Linux vends — so treating a D-Bus failure as “not a panel” turns one broken process into an empty listing that reads exactly like a desktop with no panels. The error names the app and object path that would not answer.

An object that answers GetAttributes with UnknownMethod is the one exception, and it is absence rather than failure — see the call site.

Enumerating one app’s top-levels is the one step that still skips: get_atspi_children failing is how a process that has left the bus presents, and focused_app already treats it that way.

fn splits_app_across_entries(&self) -> bool

A single process can register several AT-SPI Application entries (per-process instance plus per-event-loop pieces), so App::windows must merge their window children by pid. The same-pid merge and the stable identities it deduplicates by live in xa11y-core.

fn list_apps(&self) -> Result<Vec<ElementData>>

Enumerate top-level applications by listing direct children of the AT-SPI registry root — every running accessibility-enabled app registers a child accessible there. Apps with empty names are filtered out (toolkits sometimes register transient/system accessibles before the real app appears). PID resolution uses the AT-SPI Application interface, falling back to the D-Bus owner.

fn app_by_pid(&self, pid: u32) -> Result<ElementData>

Find an application by pid directly against the AT-SPI registry.

Differs from filtering list_apps() in two ways that matter for a freshly launched process:

• No empty-name filter — toolkits can register on the bus before the app name is set, and a pid match is precise enough on its own.
• The not-matched error reports how many registry entries were examined and how many had no resolvable pid (the misreported-pid bridge quirk get_app_pid documents), so a timeout on CI says why the app was invisible instead of just “not found”.

fn focused_app(&self) -> Result<ElementData>

Identify the foreground application via the active top-level window.

AT-SPI has no registry-level “focused application” call, and the Application accessibles themselves don’t carry an active/focused state across toolkits. The portable signal is the ACTIVE state (AtspiStateType::ACTIVE) set on the foreground window (frame): we enumerate each registered application’s top-level children and return the first application that owns a window reporting ACTIVE.

Returns Error::SelectorNotMatched when no window is active (no app has the foreground — e.g. focus is on the shell or a non-AT-SPI surface). The core reads that as “nothing focused”, not a failure.

fn get_children( &self, element: Option<&ElementData>, ) -> Result<Vec<ElementData>>

Get direct children of an element.

fn find_elements_group( &self, root: &ElementData, group: &SelectorGroup, limit: Option<usize>, max_depth: Option<u32>, ) -> Result<Vec<ElementData>>

Search for elements matching any clause of a comma-separated selector group, scoped to root’s subtree.

fn get_parent(&self, element: &ElementData) -> Result<Option<ElementData>>

Get the parent of an element.

fn app_roots(&self, app: &ElementData) -> Result<Vec<ElementData>>

Return every native application root that belongs to the same process as app.

fn press(&self, element: &ElementData) -> Result<()>

Click / tap / invoke the element.

fn focus(&self, element: &ElementData) -> Result<()>

Set keyboard focus to the element.

fn blur(&self, element: &ElementData) -> Result<()>

Remove keyboard focus from the element.

fn toggle(&self, element: &ElementData) -> Result<()>

Toggle a checkbox or switch.

fn select(&self, element: &ElementData) -> Result<()>

Select an item in a list, tab group, or menu.

fn expand(&self, element: &ElementData) -> Result<()>

Expand a collapsible element (combo box, tree item, disclosure).

fn collapse(&self, element: &ElementData) -> Result<()>

Collapse an expanded element.

fn show_menu(&self, element: &ElementData) -> Result<()>

Show the element’s context menu or dropdown.

fn increment(&self, element: &ElementData) -> Result<()>

Increment a slider or spinner by one step.

fn decrement(&self, element: &ElementData) -> Result<()>

Decrement a slider or spinner by one step.

fn scroll_into_view(&self, element: &ElementData) -> Result<()>

Scroll the element into the visible area.

fn activate(&self, element: &ElementData) -> Result<()>

App::windows filters app_windows to Role::Window | Role::Dialog. By default app_windows returns the Application node’s children. Windows overrides it because native dialogs can be UIA descendants of another window; listing them does not make them separate roots for an app-wide tree walk.

fn minimize(&self, element: &ElementData) -> Result<()>

Minimize the window.

fn maximize(&self, element: &ElementData) -> Result<()>

Maximize the window.

fn enter_fullscreen(&self, element: &ElementData) -> Result<()>

Put the window in native fullscreen.

fn restore(&self, element: &ElementData) -> Result<()>

Restore the window to its normal state (from minimized/maximized/fullscreen).

fn close(&self, element: &ElementData) -> Result<()>

Close the window.

fn move_to(&self, element: &ElementData, x: i32, y: i32) -> Result<()>

Move the window in the coordinates of ElementData::bounds (physical pixels on Windows, logical points elsewhere).

fn resize_to(&self, element: &ElementData, w: u32, h: u32) -> Result<()>

Resize the window in the units of ElementData::bounds.

fn set_value(&self, element: &ElementData, value: &str) -> Result<()>

Set the text value of the element.

fn set_numeric_value(&self, element: &ElementData, value: f64) -> Result<()>

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

fn type_text(&self, element: &ElementData, text: &str) -> Result<()>

Insert text at the current cursor position.

fn set_text_selection( &self, element: &ElementData, start: u32, end: u32, ) -> Result<()>

Select a text range (0-based character offsets).

fn perform_action(&self, element: &ElementData, action: &str) -> Result<()>

Perform an action by snake_case name.

fn subscribe(&self, element: &ElementData) -> Result<Subscription>

Subscribe to all accessibility events for an application.

fn app_windows(&self, app: &ElementData) -> Result<Vec<ElementData>, Error>

List an application’s windows. Backends whose native window list is wider than their accessibility tree roots can override this.

fn find_elements( &self, root: &ElementData, selector: &Selector, limit: Option<usize>, max_depth: Option<u32>, ) -> Result<Vec<ElementData>, Error>

Search for elements matching a selector.

fn narrow_multi_segment( &self, candidates: Vec<ElementData>, segments: &[SelectorSegment], max_depth: u32, limit: Option<usize>, ) -> Result<Vec<ElementData>, Error>

Narrow candidates through remaining selector segments (Child/Descendant combinators), deduplicate, apply final :nth and limit.