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