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

atspi_proxies/
collection.rs
