xa11y_core/
provider.rs

1use crate::action::{Action, ActionData};
2use crate::element::ElementData;
3use crate::error::Result;
4use crate::event_provider::Subscription;
5use crate::selector::Selector;
6
7/// Platform backend trait for accessibility tree access.
8///
9/// Providers implement lazy, on-demand tree navigation. Elements are identified
10/// by their [`ElementData`] (which contains a provider-specific `handle` for
11/// looking up the underlying platform object).
12///
13/// Providers should check platform permissions in their constructor (`new()`)
14/// and return [`Error::PermissionDenied`](crate::Error::PermissionDenied) if
15/// required permissions are not granted.
16pub trait Provider: Send + Sync {
17    /// Get direct children of an element.
18    ///
19    /// If `element` is `None`, returns top-level application elements.
20    fn get_children(&self, element: Option<&ElementData>) -> Result<Vec<ElementData>>;
21
22    /// Get the parent of an element.
23    ///
24    /// Returns `None` for top-level (application) elements.
25    fn get_parent(&self, element: &ElementData) -> Result<Option<ElementData>>;
26
27    /// Search for elements matching a selector.
28    ///
29    /// The selector is already parsed by the core — providers match against it
30    /// during traversal and can prune subtrees that can't match.
31    ///
32    /// If `root` is `None`, searches from the system root (all applications).
33    /// If `limit` is `Some(n)`, stops after finding `n` matches.
34    /// If `max_depth` is `Some(d)`, does not descend deeper than `d` levels.
35    ///
36    /// The default implementation traverses via [`get_children`](Self::get_children).
37    fn find_elements(
38        &self,
39        root: Option<&ElementData>,
40        selector: &Selector,
41        limit: Option<usize>,
42        max_depth: Option<u32>,
43    ) -> Result<Vec<ElementData>> {
44        crate::selector::find_elements_in_tree(
45            |el| self.get_children(el),
46            root,
47            selector,
48            limit,
49            max_depth,
50        )
51    }
52
53    /// Perform an action on an element.
54    ///
55    /// `Ok(())` means the platform API accepted the request without error.
56    /// It does **not** guarantee the action had an observable effect — use
57    /// `Locator::wait_*` methods to verify state changes.
58    fn perform_action(
59        &self,
60        element: &ElementData,
61        action: Action,
62        data: Option<ActionData>,
63    ) -> Result<()>;
64
65    /// Subscribe to all accessibility events for an application.
66    ///
67    /// The element should be an application-level element (role=Application).
68    /// The provider extracts the PID from `element.pid`.
69    ///
70    /// Returns a [`Subscription`] that receives events until dropped.
71    fn subscribe(&self, element: &ElementData) -> Result<Subscription>;
72}
xa11y_core/provider.rs

xa11y_core/
provider.rs
