atspi_proxies/application.rs
1//! # [`ApplicationProxy`]
2//!
3//! A handle for a remote object implementing the `org.a11y.atspi.Application`
4//! interface.
5//!
6//! `Application` is the interface which is implemented by each accessible application.
7//! It is implemented for the root object of an application.
8//!
9//! It provides information about the application itself.
10//!
11//! ## Status
12//!
13//! A number of methods and properties of this interface have fallen in disuse or
14//! are / may be deprecated in the future.
15//!
16//! * [`id`]
17//! * [`set_id`]
18//! * [`atspi_version`]
19//! * [`get_locale`]
20//!
21//! [`toolkit_name`] and [`version`] are still in use.
22//!
23//! See the documentation of the individual methods and properties for details.
24//!
25//! [`ApplicationProxy`]: crate::application::ApplicationProxy
26//! [`id`]: ApplicationProxy#method.id
27//! [`set_id`]: ApplicationProxy#method.set_id
28//! [`atspi_version`]: ApplicationProxy#method.atspi_version
29//! [`get_locale`]: ApplicationProxy#method.get_locale
30//! [`toolkit_name`]: ApplicationProxy#method.toolkit_name
31//! [`version`]: ApplicationProxy#method.version
32//!
33
34/// `Application` is the interface which is implemented by each accessible application.
35/// It is implemented for the root object of an application.
36///
37/// It provides information about the application itself.
38///
39/// ## Status
40///
41/// A number of methods and properties of this interface have fallen in disuse or
42/// are / may be deprecated in the future.
43///
44/// * [`id`]
45/// * [`set_id`]
46/// * [`atspi_version`]
47/// * [`get_locale`]
48///
49/// [`toolkit_name`] and [`version`] are still in use.
50///
51/// See the documentation of the individual methods and properties for details.
52///
53/// [`id`]: ApplicationProxy#method.id
54/// [`set_id`]: ApplicationProxy#method.set_id
55/// [`atspi_version`]: ApplicationProxy#method.atspi_version
56/// [`get_locale`]: ApplicationProxy#method.get_locale
57/// [`toolkit_name`]: ApplicationProxy#method.toolkit_name
58/// [`version`]: ApplicationProxy#method.version
59///
60#[zbus::proxy(
61 interface = "org.a11y.atspi.Application",
62 default_path = "/org/a11y/atspi/accessible/root",
63 assume_defaults = true
64)]
65pub trait Application {
66 /// Method to retrieve the application's locale.
67 ///
68 /// ## Deprecation
69 ///
70 /// This method is likely to be removed in the future.
71 ///
72 /// There is no need to call this method because there is also
73 /// [`locale`] which offers the same functionality
74 /// at the accessible object level.
75 ///
76 /// See also: [Orca issues: "Plans for per-object locale?"](<https://gitlab.gnome.org/GNOME/orca/-/issues/260>)
77 ///
78 /// member: `GetLocale`, type: method
79 ///
80 /// [`locale`]: crate::accessible::AccessibleProxy#method.locale
81 fn get_locale(&self, lctype: u32) -> zbus::Result<String>;
82
83 /// retrieves AT-SPI2 version.
84 ///
85 /// Applications are advised to return "2.1" here, thus that is what
86 /// users should expect.
87 ///
88 /// This was intended to be the version of the atspi interfaces
89 /// that the application supports, but atspi will probably move to
90 /// using versioned interface names instead.
91 ///
92 /// member: `AtspiVersion`, type: property
93 #[zbus(property)]
94 fn atspi_version(&self) -> zbus::Result<String>;
95
96 /// Retrieve numerical id of the application.
97 ///
98 /// The 'id' is set an arbitrary numerical id when
99 /// an application registers with the registry.
100 ///
101 /// When a freshly-started application uses the
102 /// [`org.a11y.atspi.Socket`]'s [`embed`] method to
103 /// register with the accessibility registry, the
104 /// registry will set a numerical id on the application.
105 ///
106 /// ## status
107 ///
108 /// The property has fallen in disuse.
109 ///
110 /// As per [AT-SPI2-CORE issue #82](<https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues/82>)
111 /// it may turn out that this id is not actually used subsequently.
112 /// This is a remnant of the time when registryd actually had to
113 /// make up identifiers for each application.
114 /// With `DBus`, however, it is the bus that assigns unique names to applications that
115 /// connect to it.
116 ///
117 /// Applications or toolkits can remember the `Id` passed when the accessibility
118 /// registry sets this property, and return it back when the property is read.
119 ///
120 /// member: `Id`, type: property
121 ///
122 /// [`embed`]: crate::socket::SocketProxy#method.embed
123 /// [`org.a11y.atspi.Socket`]: crate::socket::SocketProxy
124 #[zbus(property)]
125 fn id(&self) -> zbus::Result<i32>;
126
127 /// Set ID of the application.
128 ///
129 /// This method is used by the accessibility registry to set the
130 /// application's id.
131 ///
132 /// ## status
133 ///
134 /// The property has fallen in disuse.
135 ///
136 /// See [`id`] for details.
137 ///
138 /// member: `Id`, type: property
139 ///
140 /// [`id`]: crate::application::ApplicationProxy#method.id
141 #[zbus(property)]
142 fn set_id(&self, value: i32) -> zbus::Result<()>;
143
144 /// Retrieves the name of the toolkit used to implement the application's
145 /// user interface.
146 ///
147 /// member: `ToolkitName`, type: property
148 #[zbus(property)]
149 fn toolkit_name(&self) -> zbus::Result<String>;
150
151 /// Returns the version of the toolkit used to implement the
152 /// application's user interface.
153 ///
154 /// member: `Version`, type: property
155 #[zbus(property)]
156 fn version(&self) -> zbus::Result<String>;
157
158 /// Method to obtain the unix socket address.
159 /// The unix socket can be used to setup a connection, to perform peer-to-peer (P2P) method calls.
160 ///
161 /// Known implementors include `Gtk3` and `Firefox`.
162 fn get_application_bus_address(&self) -> zbus::Result<String>;
163}