1#![deny(clippy::all, clippy::pedantic, clippy::cargo, unsafe_code)]
2#![allow(clippy::module_name_repetitions)]
3
4//! # atspi-common
5//!
6//! Defines all common types, events, and data structures for `atspi-proxies` and `atspi-connection`.
7//! Since `atspi-proxies` and `atspi-connection` are downstream crates, the documentation can not link to it directly.
8//! Any type ending in `*Proxy` is in `atspi-proxies`.
9//!
10
11#[macro_use]
12extern crate static_assertions;
13#[macro_use]
14pub(crate) mod macros;
15
16pub mod accessible;
17pub use accessible::Accessible;
18pub mod interface;
19pub use interface::{Interface, InterfaceSet};
20pub mod state;
21pub use state::{State, StateSet};
22pub mod cache;
23pub use cache::{CacheItem, LegacyCacheItem};
24pub mod error;
25pub use error::AtspiError;
26pub mod events;
27pub use events::{Event, GenericEvent};
28mod role;
29pub use role::Role;
30mod relation_type;
31pub use relation_type::RelationType;
32
33use serde::{Deserialize, Serialize};
34use zvariant::Type;
35
36pub type MatchArgs<'a> = (
37 &'a [i32],
38 MatchType,
39 std::collections::HashMap<&'a str, &'a str>,
40 MatchType,
41 &'a [i32],
42 MatchType,
43 &'a [&'a str],
44 MatchType,
45 bool,
46);
47
48#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
49#[repr(u32)]
50/// Enumeration used by interface `CollectionProxy` to specify the way [`crate::accessible::Accessible`] objects should be sorted.
51pub enum SortOrder {
52 /// Invalid sort order
53 Invalid,
54 /// Canonical sort order
55 Canonical,
56 /// Flow sort order
57 Flow,
58 /// Tab sort order
59 Tab,
60 /// Reverse canonical sort order
61 ReverseCanonical,
62 /// Reverse flow sort order
63 ReverseFlow,
64 /// Reverse tab sort order
65 ReverseTab,
66}
67
68/// Method of traversing a tree in the `CollectionProxy`.
69#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
70#[repr(u32)]
71pub enum TreeTraversalType {
72 /// Restrict children tree traversal
73 RestrictChildren,
74 /// Restrict sibling tree traversal
75 RestrictSibling,
76 /// In-order tree traversal.
77 Inorder,
78}
79
80#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
81#[repr(i32)]
82/// Enumeration used by [`MatchArgs`] to specify how to interpret [`crate::accessible::Accessible`] objects.
83pub enum MatchType {
84 /// Invalid match type
85 Invalid,
86 /// true if all of the criteria are met.
87 All,
88 /// true if any of the criteria are met.
89 Any,
90 /// true if none of the criteria are met.
91 NA,
92 /// Same as [`Self::All`] if the criteria is non-empty;
93 /// for empty criteria this rule requires returned value to also have empty set.
94 Empty,
95}
96
97#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
98#[repr(u32)]
99/// The coordinate type encodes the frame of reference.
100pub enum CoordType {
101 /// In relation to the entire screen.
102 Screen,
103 /// In relation to only the window.
104 Window,
105 /// In relation to the parent of the element being checked.
106 Parent,
107}
108
109#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, Serialize, Deserialize, Type)]
110#[repr(u32)]
111/// Enumeration used by `TextProxy` to indicate how to treat characters intersecting bounding boxes.
112pub enum ClipType {
113 /// No characters/glyphs are omitted.
114 Neither,
115 /// Characters/glyphs clipped by the minimum coordinate are omitted.
116 Min,
117 /// Characters/glyphs which intersect the maximum coordinate are omitted.
118 Max,
119 /// Only glyphs falling entirely within the region bounded by min and max are retained.
120 Both,
121}
122
123#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, Serialize, Deserialize, Type)]
124#[repr(u32)]
125/// Level of granularity to get text of, in relation to a cursor position.
126pub enum Granularity {
127 /// Gives the character at the index of the cursor. With a line-style cursor (which is standard) this will get the character that appears after the cursor.
128 Char,
129 /// Gives the entire word in front of, or which contains, the cursor. TODO: confirm that it always chooses the word in front of the cursor.
130 Word,
131 /// Gives entire sentence in front of, or which contains, the cursor. TODO: confirm that it always chooses the sentence after the cursor.
132 Sentence,
133 /// Gives the line, as seen visually of which the cursor is situated within.
134 Line,
135 /// Gives the entire block of text, regardless of where the cursor lies within it.
136 Paragraph,
137}
138
139/// Indicates relative stacking order of a `atspi_proxies::component::ComponentProxy` with respect to the
140/// onscreen visual representation of the UI.
141///
142/// The layer index, in combination with the component's extents,
143/// can be used to compute the visibility of all or part of a component.
144/// This is important in programmatic determination of region-of-interest for magnification,
145/// and in flat screen review models of the screen, as well as for other uses.
146/// Objects residing in two of the `Layer` categories support further z-ordering information,
147/// with respect to their peers in the same layer:
148/// namely, [`Layer::Window`] and [`Layer::Mdi`].
149/// Relative stacking order for other objects within the same layer is not available;
150/// the recommended heuristic is first child paints first. In other words,
151/// assume that the first siblings in the child list are subject to being
152/// overpainted by later siblings if their bounds intersect.
153#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
154pub enum Layer {
155 /// Indicates an error condition or uninitialized value.
156 Invalid,
157 /// Reserved for the desktop background; this is the bottom-most layer,
158 /// over which everything else is painted.
159 Background,
160 /// The 'background' layer for most content renderers and
161 /// UI `atspi_proxies::component::ComponentProxy` containers.
162 Canvas,
163 /// The layer in which the majority of ordinary 'foreground' widgets reside.
164 Widget,
165 /// A special layer between [`Layer::Canvas`] and [`Layer::Widget`], in which the
166 /// 'pseudo windows' (e.g. the Multiple-Document Interface frames) reside.
167 ///
168 /// See `atspi_proxies::component::ComponentProxy::get_mdizorder`.
169 Mdi,
170 /// A layer for popup window content, above [`Layer::Widget`].
171 Popup,
172 /// The topmost layer.
173 Overlay,
174 /// The layer in which a toplevel window background usually resides.
175 Window,
176}
177
178/// Enumeration used by interface the [`crate::interface::Interface::Accessible`] to specify where an object should be placed on the screen when using `scroll_to`.
179#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
180pub enum ScrollType {
181 /// Scroll the object to the top left corner of the window.
182 TopLeft,
183 /// Scroll the object to the bottom right corner of the window.
184 BottomRight,
185 /// Scroll the object to the top edge of the window.
186 TopEdge,
187 /// Scroll the object to the bottom edge of the window.
188 BottomEdge,
189 /// Scroll the object to the left edge of the window.
190 LeftEdge,
191 /// Scroll the object to the right edge of the window.
192 RightEdge,
193 /// Scroll the object to application-dependent position on the window.
194 Anywhere,
195}
196
197/// Enumeration used to indicate a type of live region and how assertive it
198/// should be in terms of speaking notifications. Currently, this is only used
199/// for "announcement" events, but it may be used for additional purposes
200/// in the future.
201#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, Type)]
202#[repr(u32)]
203pub enum Live {
204 /// No live region.
205 None,
206 /// This live region should be considered polite.
207 Polite,
208 /// This live region should be considered assertive.
209 Assertive,
210}
211
212impl Default for Live {
213 fn default() -> Self {
214 Self::None
215 }
216}
217
218impl TryFrom<i32> for Live {
219 type Error = AtspiError;
220
221 fn try_from(value: i32) -> Result<Self, Self::Error> {
222 match value {
223 0 => Ok(Live::None),
224 1 => Ok(Live::Polite),
225 2 => Ok(Live::Assertive),
226 _ => Err(AtspiError::Conversion("Unknown Live variant")),
227 }
228 }
229}
230
231#[cfg(test)]
232mod tests {
233 use super::*;
234
235 #[test]
236 fn convert_i32_to_live() {
237 assert_eq!(Live::None, Live::try_from(0).unwrap());
238 assert_eq!(Live::Polite, Live::try_from(1).unwrap());
239 assert_eq!(Live::Assertive, Live::try_from(2).unwrap());
240 assert!(Live::try_from(3).is_err());
241 assert!(Live::try_from(-1).is_err());
242 }
243}
244