atspi_proxies/
action.rs

1//! # [`ActionProxy`]
2//!
3//! A handle for a remote object implementing the `org.a11y.atspi.Action`
4//! interface.
5//!
6//! The `Action` interface allows exploring and invoking the actions of a
7//! user-actionable UI component.
8//!
9//! For example, a button may expose a "click" action - a popup menu may
10//! expose an "open" action.
11//!
12//! Components which are not "passive" providers of UI information should
13//! implement this interface, unless there is a more specialized interface for
14//! interaction like [`org.a11y.atspi.Text`][TextProxy] or [`org.a11y.atspi.Value`][ValueProxy].
15//!  
16//! [ActionProxy]: crate::action::ActionProxy
17//! [TextProxy]: crate::text::TextProxy
18//! [ValueProxy]: crate::value::ValueProxy
19
20use atspi_common::Action;
21
22/// A handle for a remote object implementing the `org.a11y.atspi.Action`
23/// interface.
24///
25/// The `Action` interface allows exploring and invoking the actions of a
26/// user-actionable UI component.
27///
28/// For example, a button may expose a "click" action - a popup menu may
29/// expose an "open" action.
30///
31/// Components which are not "passive" providers of UI information should
32/// implement this interface, unless there is a more specialized interface for
33/// interaction like [`org.a11y.atspi.Text`][TextProxy] or [`org.a11y.atspi.Value`][ValueProxy].
34///  
35/// [TextProxy]: crate::text::TextProxy
36/// [ValueProxy]: crate::value::ValueProxy
37#[zbus::proxy(interface = "org.a11y.atspi.Action", assume_defaults = true)]
38pub trait Action {
39	/// Performs the specified action on the object.
40	///
41	/// Returns: Ok(true) on success, Ok(false) otherwise.
42	///
43	/// # Arguments
44	///
45	/// * `index` - The index of the action to perform.
46	fn do_action(&self, index: i32) -> zbus::Result<bool>;
47
48	/// Returns an array of localized name, localized
49	/// description, keybinding for the actions that an object
50	/// supports.
51	///
52	/// See [`get_key_binding`] method for a description of that
53	/// field's syntax.
54	///
55	/// This is equivalent to using the methods [`get_localized_name`],
56	/// [`get_description`] and	[`get_key_binding`] for each action,
57	/// but with a single call and thus less DBus traffic.
58	///
59	///	By convention, if there is more than one action available,
60	/// the first one is considered the "default" action of the object.
61	///
62	/// [`get_key_binding`]: ActionProxy#method.get_key_binding
63	/// [`get_localized_name`]: ActionProxy#method.get_localized_name
64	/// [`get_description`]: ActionProxy#method.get_description
65	fn get_actions(&self) -> zbus::Result<Vec<Action>>;
66
67	/// Returns the localized description for the action at the specified
68	/// index, starting at zero.
69	///   
70	/// For	example, a screen reader will read out this description when
71	/// the user asks for extra detail on an action.
72	/// For example, "Clicks the button" for the "click" action of a button.
73	fn get_description(&self, index: i32) -> zbus::Result<String>;
74
75	/// Returns the keybinding for the action, specified by a
76	/// zero-based index.
77	///
78	/// Gets the keybinding which can be used to invoke this action,
79	/// if one exists.
80	///
81	/// The string returned should contain localized, human-readable,
82	/// key sequences as they would appear when displayed on screen.
83	/// It must be in the format "mnemonic;sequence;shortcut".
84	///
85	/// - The mnemonic key activates the object if it is presently
86	/// enabled on screen.
87	/// This typically corresponds to the underlined letter within
88	/// the widget. Example: "n" in a traditional "Ṉew..." menu
89	/// item or the "a" in "Apply" for a button.
90	///
91	/// - The sequence is the full list of keys which invoke the action
92	/// even if the relevant element is not currently shown on screen.
93	/// For instance, for a menu item the sequence is the keybindings
94	/// used to open the parent menus before invoking.
95	///
96	/// The sequence string is colon-delimited. Example: "Alt+F:N" in a
97	/// traditional "Ṉew..." menu item.
98	///
99	/// - The shortcut, if it exists, will invoke the same action without
100	/// showing the component or its enclosing menus or dialogs.
101	/// Example: "Ctrl+N" in a traditional "Ṉew..." menu item.
102	/// The shortcut string is colon-delimited. Example: "Ctrl+N" in a
103	/// traditional "Ṉew..." menu item.
104	///
105	/// Example: For a traditional "Ṉew..." menu item, the expected return
106	/// value would be: "N;Alt+F:N;Ctrl+N" for the English locale and
107	/// "N;Alt+D:N;Strg+N" for the German locale.
108	/// If, hypothetically, this menu item lacked a mnemonic, it would be
109	/// represented by ";;Ctrl+N" and ";;Strg+N" respectively.
110	///
111	/// If there is no key binding for this action, "" is returned.
112	fn get_key_binding(&self, index: i32) -> zbus::Result<String>;
113
114	/// Returns a short, localized name for the action at the specified by a
115	/// zero-based index.
116	///
117	/// This is	what screen readers will read out during normal navigation.
118	/// For example, "Click" for a button.
119	fn get_localized_name(&self, index: i32) -> zbus::Result<String>;
120
121	/// Returns a machine-readable name for the action at the specified,
122	/// zero-based index.
123	fn get_name(&self, index: i32) -> zbus::Result<String>;
124
125	/// Returns the number of available actions.
126	///
127	///	By convention, if there is more than one action available,
128	/// the first one is considered the "default" action of the object.
129	#[zbus(property)]
130	fn nactions(&self) -> zbus::Result<i32>;
131}
atspi_proxies/action.rs

atspi_proxies/
action.rs
