1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! # [`ActionProxy`]
//!
//! A handle for a remote object implementing the `org.a11y.atspi.Action`
//! interface.
//!
//! The `Action` interface allows exploring and invoking the actions of a
//! user-actionable UI component.
//!
//! For example, a button may expose a "click" action - a popup menu may
//! expose an "open" action.
//!
//! Components which are not "passive" providers of UI information should
//! implement this interface, unless there is a more specialized interface for
//! interaction like [`org.a11y.atspi.Text`][TextProxy] or [`org.a11y.atspi.Value`][ValueProxy].
//!  
//! [ActionProxy]: crate::action::ActionProxy
//! [TextProxy]: crate::text::TextProxy
//! [ValueProxy]: crate::value::ValueProxy

/// A handle for a remote object implementing the `org.a11y.atspi.Action`
/// interface.
///
/// The `Action` interface allows exploring and invoking the actions of a
/// user-actionable UI component.
///
/// For example, a button may expose a "click" action - a popup menu may
/// expose an "open" action.
///
/// Components which are not "passive" providers of UI information should
/// implement this interface, unless there is a more specialized interface for
/// interaction like [`org.a11y.atspi.Text`][TextProxy] or [`org.a11y.atspi.Value`][ValueProxy].
///  
/// [TextProxy]: crate::text::TextProxy
/// [ValueProxy]: crate::value::ValueProxy
#[zbus::proxy(interface = "org.a11y.atspi.Action", assume_defaults = true)]
trait Action {
	/// Performs the specified action on the object.
	///
	/// Returns: Ok(true) on success, Ok(false) otherwise.
	///
	/// # Arguments
	///
	/// * `index` - The index of the action to perform.
	fn do_action(&self, index: i32) -> zbus::Result<bool>;

	/// Returns an array of localized name, localized
	/// description, keybinding for the actions that an object
	/// supports.
	///
	/// See [`get_key_binding`] method for a description of that
	/// field's syntax.
	///
	/// This is equivalent to using the methods [`get_localized_name`],
	/// [`get_description`] and	[`get_key_binding`] for each action,
	/// but with a single call and thus less DBus traffic.
	///
	///	By convention, if there is more than one action available,
	/// the first one is considered the "default" action of the object.
	///
	/// [`get_key_binding`]: ActionProxy#method.get_key_binding
	/// [`get_localized_name`]: ActionProxy#method.get_localized_name
	/// [`get_description`]: ActionProxy#method.get_description
	fn get_actions(&self) -> zbus::Result<Vec<(String, String, String)>>;

	/// Returns the localized description for the action at the specified
	/// index, starting at zero.
	///   
	/// For	example, a screen reader will read out this description when
	/// the user asks for extra detail on an action.
	/// For example, "Clicks the button" for the "click" action of a button.
	fn get_description(&self, index: i32) -> zbus::Result<String>;

	/// Returns the keybinding for the action, specified by a
	/// zero-based index.
	///
	/// Gets the keybinding which can be used to invoke this action,
	/// if one exists.
	///
	/// The string returned should contain localized, human-readable,
	/// key sequences as they would appear when displayed on screen.
	/// It must be in the format "mnemonic;sequence;shortcut".
	///
	/// - The mnemonic key activates the object if it is presently
	/// enabled on screen.
	/// This typically corresponds to the underlined letter within
	/// the widget. Example: "n" in a traditional "Ṉew..." menu
	/// item or the "a" in "Apply" for a button.
	///
	/// - The sequence is the full list of keys which invoke the action
	/// even if the relevant element is not currently shown on screen.
	/// For instance, for a menu item the sequence is the keybindings
	/// used to open the parent menus before invoking.
	///
	/// The sequence string is colon-delimited. Example: "Alt+F:N" in a
	/// traditional "Ṉew..." menu item.
	///
	/// - The shortcut, if it exists, will invoke the same action without
	/// showing the component or its enclosing menus or dialogs.
	/// Example: "Ctrl+N" in a traditional "Ṉew..." menu item.
	/// The shortcut string is colon-delimited. Example: "Ctrl+N" in a
	/// traditional "Ṉew..." menu item.
	///
	/// Example: For a traditional "Ṉew..." menu item, the expected return
	/// value would be: "N;Alt+F:N;Ctrl+N" for the English locale and
	/// "N;Alt+D:N;Strg+N" for the German locale.
	/// If, hypothetically, this menu item lacked a mnemonic, it would be
	/// represented by ";;Ctrl+N" and ";;Strg+N" respectively.
	///
	/// If there is no key binding for this action, "" is returned.
	fn get_key_binding(&self, index: i32) -> zbus::Result<String>;

	/// Returns a short, localized name for the action at the specified by a
	/// zero-based index.
	///
	/// This is	what screen readers will read out during normal navigation.
	/// For example, "Click" for a button.
	fn get_localized_name(&self, index: i32) -> zbus::Result<String>;

	/// Returns a machine-readable name for the action at the specified,
	/// zero-based index.
	fn get_name(&self, index: i32) -> zbus::Result<String>;

	/// Returns the number of available actions.
	///
	///	By convention, if there is more than one action available,
	/// the first one is considered the "default" action of the object.
	#[zbus(property)]
	fn nactions(&self) -> zbus::Result<i32>;
}