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(interface = "org.a11y.atspi.Application", assume_defaults = true)]
61trait Application {
62 /// Method to retrieve the application's locale.
63 ///
64 /// ## Deprecation
65 ///
66 /// This method is likely to be removed in the future.
67 ///
68 /// There is no need to call this method because there is also
69 /// [`locale`] which offers the same functionality
70 /// at the accessible object level.
71 ///
72 /// See also: [Orca issues: "Plans for per-object locale?"](<https://gitlab.gnome.org/GNOME/orca/-/issues/260>)
73 ///
74 /// member: "GetLocale", type: method
75 ///
76 /// [`locale`]: crate::accessible::AccessibleProxy#method.locale
77 fn get_locale(&self, lctype: u32) -> zbus::Result<String>;
78
79 /// retrieves AT-SPI2 version.
80 ///
81 /// Applications are advised to return "2.1" here, thus that is what
82 /// users should expect.
83 ///
84 /// This was intended to be the version of the atspi interfaces
85 /// that the application supports, but atspi will probably move to
86 /// using versioned interface names instead.
87 ///
88 /// member: "AtspiVersion", type: property
89 #[zbus(property)]
90 fn atspi_version(&self) -> zbus::Result<String>;
91
92 /// Retrieve numerical id of the application.
93 ///
94 /// The 'id' is set an arbitrary numerical id when
95 /// an application registers with the registry.
96 ///
97 /// When a freshly-started application uses the
98 /// [`org.a11y.atspi.Socket`]'s [`embed`] method to
99 /// register with the accessibility registry, the
100 /// registry will set a numerical id on the application.
101 ///
102 /// ## status
103 ///
104 /// The property has fallen in disuse.
105 ///
106 /// As per [AT-SPI2-CORE issue #82](<https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues/82>)
107 /// it may turn out that this id is not actually used subsequently.
108 /// This is a remnant of the time when registryd actually had to
109 /// make up identifiers for each application.
110 /// With DBus, however, it is the bus that assigns unique names to applications that
111 /// connect to it.
112 ///
113 /// Applications or toolkits can remember the `Id` passed when the accessibility
114 /// registry sets this property, and return it back when the property is read.
115 ///
116 /// member: "Id", type: property
117 ///
118 /// [`embed`]: crate::socket::SocketProxy#method.embed
119 /// [`org.a11y.atspi.Socket`]: crate::socket::SocketProxy
120 #[zbus(property)]
121 fn id(&self) -> zbus::Result<i32>;
122
123 /// Set ID of the application.
124 ///
125 /// This method is used by the accessibility registry to set the
126 /// application's id.
127 ///
128 /// ## status
129 ///
130 /// The property has fallen in disuse.
131 ///
132 /// See [`id`] for details.
133 ///
134 /// member: "Id", type: property
135 ///
136 /// [`id`]: crate::application::ApplicationProxy#method.id
137 #[zbus(property)]
138 fn set_id(&self, value: i32) -> zbus::Result<()>;
139
140 /// Retrieves the name of the toolkit used to implement the application's
141 /// user interface.
142 ///
143 /// member: "ToolkitName", type: property
144 #[zbus(property)]
145 fn toolkit_name(&self) -> zbus::Result<String>;
146
147 /// Returns the version of the toolkit used to implement the
148 /// application's user interface.
149 ///
150 /// member: "Version", type: property
151 #[zbus(property)]
152 fn version(&self) -> zbus::Result<String>;
153}
154