atspi_proxies/
collection.rs

1//! # [`CollectionProxy`]
2//!
3//! A handle to a remote object implementing the `org.a11y.atspi.Collection`
4//! interface.
5//!
6//! `Collection` is the interface which is implemented by objects that contain
7//! other objects, such as a window or a table.
8//!
9//! See the documentation on the individual methods for details:
10//!
11//! * [`get_matches`](struct.CollectionProxy.html#method.get_matches)
12//! * [`get_matches_from`](struct.CollectionProxy.html#method.get_matches_from)
13//! * [`get_matches_to`](struct.CollectionProxy.html#method.get_matches_to)
14//!
15//! [`CollectionProxy`]: crate::collection::CollectionProxy
16
17use atspi_common::object_ref::ObjectRefOwned;
18
19use crate::common::{ObjectMatchRule, SortOrder, TreeTraversalType};
20
21#[zbus::proxy(interface = "org.a11y.atspi.Collection", assume_defaults = true)]
22pub trait Collection {
23	/// The active descendant of the given object.
24	///
25	/// May not be implemented by any known toolkit or private implementation.
26	///
27	/// See [atspi/collection.c](https://gitlab.gnome.org/GNOME/at-spi2-core/-/blob/main/atspi/atspi-collection.c?ref_type=heads#L272)
28	///
29	fn get_active_descendant(&self) -> zbus::Result<ObjectRefOwned>;
30
31	/// Retrieves a list of objects that match the specified `ObjectMatchRule`, ordered according to `SortOrder` and limited by the count parameter.
32	///
33	/// # Arguments
34	///
35	/// * `rule` - An [`ObjectMatchRule`] describing the match criteria.
36	/// * `sortby` - A [`SortOrder`] specifying the way the results are to be sorted.
37	/// * `count` - The maximum number of results to return, or 0 for no limit.
38	/// * `traverse` - Not supported.
39	///
40	/// [`ObjectMatchRule`]: [`atspi_common::object_match::ObjectMatchRule`]
41	/// [`SortOrder`]: [`atspi_common::SortOrder`]
42	fn get_matches(
43		&self,
44		rule: ObjectMatchRule,
45		sortby: SortOrder,
46		count: i32,
47		traverse: bool,
48	) -> zbus::Result<Vec<ObjectRefOwned>>;
49
50	/// Retrieves objects from the collection, after `current_object`, matching a given `rule`.
51	///
52	/// # Arguments
53	///
54	/// * `current_object` - The object at which to start searching.
55	/// * `rule` - An [`ObjectMatchRule`] describing the match criteria.
56	/// * `sortby` - A [`SortOrder`] specifying the way the results are to be sorted.
57	/// * `tree` - A [`TreeTraversalType`] specifying restrictions on the objects to be traversed.
58	/// * `count` - The maximum number of results to return, or 0 for no limit.
59	/// * `traverse` - Not supported by the known implementation (atk-collection).
60	///
61	/// [`ObjectMatchRule`]: atspi_common::object_match::ObjectMatchRule
62	/// [`SortOrder`]: atspi_common::SortOrder
63	/// [`TreeTraversalType`]: atspi_common::TreeTraversalType
64	fn get_matches_from(
65		&self,
66		current_object: &zbus::zvariant::ObjectPath<'_>,
67		rule: ObjectMatchRule,
68		sortby: SortOrder,
69		tree: TreeTraversalType,
70		count: i32,
71		traverse: bool,
72	) -> zbus::Result<Vec<ObjectRefOwned>>;
73
74	/// Retrieves objects from the collection, before `current_object`, matching a given `rule`.
75	///
76	/// # Arguments
77	///
78	/// * `current_object` - The object at which to start searching.
79	/// * `rule` - An [`ObjectMatchRule`] describing the match criteria.
80	/// * `sortby` - A [`SortOrder`] specifying the way the results are to be sorted.
81	/// * `tree` - A [`TreeTraversalType`] specifying restrictions on the objects to be traversed.
82	/// * `limit_scope` - If `true`, only descendants of `current_object`'s parent will be returned.
83	///    Otherwise (if `false`), any accessible may be returned if it would preceed `current_object` in a flattened hierarchy.
84	/// * `count` - The maximum number of results to return, or 0 for no limit.
85	/// * `traverse` - Not supported by the known implementation (atk-collection).
86	///
87	/// [`ObjectMatchRule`]: atspi_common::object_match::ObjectMatchRule
88	/// [`SortOrder`]: atspi_common::SortOrder
89	/// [`TreeTraversalType`]: atspi_common::TreeTraversalType
90	#[allow(clippy::too_many_arguments)]
91	fn get_matches_to(
92		&self,
93		current_object: &zbus::zvariant::ObjectPath<'_>,
94		rule: ObjectMatchRule,
95		sortby: SortOrder,
96		tree: TreeTraversalType,
97		limit_scope: bool,
98		count: i32,
99		traverse: bool,
100	) -> zbus::Result<Vec<ObjectRefOwned>>;
101}
atspi_proxies/collection.rs

atspi_proxies/
collection.rs
