Mir
toolkit_event.h
Go to the documentation of this file.
1 /*
2  * Copyright © 2020 Canonical Ltd.
3  *
4  * This program is free software: you can redistribute it and/or modify it
5  * under the terms of the GNU General Public License version 2 or 3 as
6  * published by the Free Software Foundation.
7  *
8  * This program is distributed in the hope that it will be useful,
9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11  * GNU General Public License for more details.
12  *
13  * You should have received a copy of the GNU General Public License
14  * along with this program. If not, see <http://www.gnu.org/licenses/>.
15  */
16 
17 #ifndef MIRAL_TOOLKIT_EVENT_H_
18 #define MIRAL_TOOLKIT_EVENT_H_
19 
20 #include <mir_toolkit/events/enums.h>
21 
22 #include <xkbcommon/xkbcommon.h>
23 
24 struct MirEvent;
25 struct MirKeyboardEvent;
26 struct MirTouchEvent;
27 struct MirPointerEvent;
28 struct MirInputEvent;
29 
30 /**
31  * An identifier for a touch-point. TouchId's are unique per-gesture.
32  * That is to say, once a touch has gone down at time T, no other touch will
33  * use that touch's ID until all touches at time T have come up.
34  */
35 typedef int32_t MirTouchId;
36 
37 namespace miral
38 {
39 namespace toolkit
40 {
41 /**
42  * Retrieves the type of a MirEvent. Now preferred over direct access to ev->type.
43  * In particular ev->type will never be mir_event_type_input and mir_event_get_type
44  * is the only way to ensure mir_event_get_input_event will succeed.
45  *
46  * \param [in] event The event
47  * \return The event type
48  */
49 MirEventType mir_event_get_type(MirEvent const* event);
50 
51 /**
52  * Retrieve the MirInputEvent associated with a MirEvent of
53  * type mir_event_type_input. See <mir_toolkit/events/input/input_event.h>
54  * for accessors.
55  *
56  * \param [in] event The event
57  * \return The associated MirInputEvent
58  */
59 MirInputEvent const* mir_event_get_input_event(MirEvent const* event);
60 
61 ///**
62 // * Retrieves the device id responsible for generating an input event.
63 // *
64 // * \param [in] event The input event
65 // * \return The id of the generating device
66 // */
67 //MirInputDeviceId mir_input_event_get_device_id(MirInputEvent const* event);
68 
69 /**
70  * Retrieve the time at which an input event occurred.
71  *
72  * \param [in] event The input event
73  * \return A timestamp in nanoseconds-since-epoch
74  */
75 int64_t mir_input_event_get_event_time(MirInputEvent const* event);
76 
77 /**
78  * Retrieve the type of an input event. E.g. key, touch...
79  *
80  * \param [in] event The input event
81  * \return The input event type
82  */
83 MirInputEventType mir_input_event_get_type(MirInputEvent const* event);
84 
85 /**
86  * Retrieve the MirKeyboardEvent associated with a given input event.
87  *
88  * \param[in] event The input event
89  * \return The MirKeyboardEvent or NULL if event type is not
90  * mir_input_event_type_key
91  */
92 MirKeyboardEvent const* mir_input_event_get_keyboard_event(MirInputEvent const* event);
93 
94 /**
95  * Retrieve the MirTouchEvent associated with a given input event.
96  *
97  * \param[in] event The input event
98  * \return The MirTouchEvent or NULL if event type is not
99  * mir_input_event_type_touch
100  */
101 MirTouchEvent const* mir_input_event_get_touch_event(MirInputEvent const* event);
102 
103 /**
104  * Retrieve the MirPointerEvent associated with a given input event.
105  *
106  * \param[in] event The input event
107  * \return The MirPointerEvent or NULL if event type is not
108  * mir_input_event_type_pointer
109  */
110 MirPointerEvent const* mir_input_event_get_pointer_event(MirInputEvent const* event);
111 
112 /**
113  * Query if an input event contains a cookie
114  *
115  * \param [in] ev The input event
116  * \return True if the input event contains a cookie
117  */
118 bool mir_input_event_has_cookie(MirInputEvent const* ev);
119 
120 ///**
121 // * Returns the cookie associated with an input event.
122 // *
123 // * \pre The input event must have a MirCookie
124 // * \param [in] ev An input event
125 // * \return The cookie associated with the given input event
126 // * The cookie must be released by calling mir_cookie_release
127 // */
128 //MirCookie const* mir_input_event_get_cookie(MirInputEvent const* ev);
129 
130 /**
131  * Retrieve the MirEvent associated with a given input event.
132  *
133  * \param[in] event The input event
134  * \return The MirEvent
135  */
136 MirEvent const* mir_input_event_get_event(MirInputEvent const* event);
137 
138 /**
139  * Retrieve the action which triggered a given key event.
140  *
141  * \param [in] event The key event
142  * \return The associated action
143  */
144 MirKeyboardAction mir_keyboard_event_action(MirKeyboardEvent const* event);
145 
146 /**
147  * Retrieve the xkb mapped keysym associated with the key acted on.. May
148  * be interpreted as per <xkbcommon/xkbcommon-keysyms.h>
149  *
150  * \param [in] event The key event
151  * \return The xkb_keysym
152  * \remark Since MirAL 3.3
153  */
154 xkb_keysym_t mir_keyboard_event_keysym(MirKeyboardEvent const* event);
155 
156 /**
157  * \deprecated Returns the same thing as mir_keyboard_event_keysym(), which should be used instead.
158  */
159 xkb_keysym_t mir_keyboard_event_key_code(MirKeyboardEvent const* event);
160 
161 /**
162  * Retrieve the raw hardware scan code associated with the key acted on. May
163  * be interpreted as per <linux/input.h>
164  *
165  * \param [in] event The key event
166  * \return The scancode
167  */
168 int mir_keyboard_event_scan_code(MirKeyboardEvent const* event);
169 
170 /**
171  * Retrieve the text the key press would emit as null terminated utf8 string.
172  *
173  * The text will only be available to key down and key repeat events.
174  * For mir_keyboard_action_up or key presses that do produce text an empty
175  * string will be returned.
176  *
177  * \param [in] event The key event
178  * \return The text
179  */
180 char const* mir_keyboard_event_key_text(MirKeyboardEvent const* event);
181 
182 /**
183  * Retrieve the modifier keys pressed when the key action occured.
184  *
185  * \param [in] event The key event
186  * \return The modifier mask
187  */
189 
190 /**
191  * Retrieve the corresponding input event.
192  *
193  * \param [in] event The keyboard event
194  * \return The input event
195  */
196 MirInputEvent const* mir_keyboard_event_input_event(MirKeyboardEvent const* event);
197 
198 /**
199  * Retrieve the modifier keys pressed when the touch action occured.
200  *
201  * \param [in] event The key event
202  * \return The modifier mask
203  */
205 
206 /**
207  * Retrieve the number of touches reported for a given touch event. Each touch
208  * is said to be index in the event and may be accessed by index 0, 1, ... , (touch_count - 1)
209  *
210  * \param [in] event The touch event
211  * \return The number of touches
212  */
213 unsigned int mir_touch_event_point_count(MirTouchEvent const* event);
214 
215 /**
216  * Retrieve the TouchID for a touch at given index.
217  *
218  * \param [in] event The touch event
219  * \param [in] touch_index The touch index. Must be less than (touch_count - 1).
220  * \return ID of the touch at index
221  */
222 MirTouchId mir_touch_event_id(MirTouchEvent const* event, unsigned int touch_index);
223 
224 /**
225  * Retrieve the action which occured for a touch at given index.
226  *
227  * \param [in] event The touch event
228  * \param [in] touch_index The touch index. Must be less than (touch_count - 1).
229  * \return Action performed for the touch at index.
230  */
231 MirTouchAction mir_touch_event_action(MirTouchEvent const* event, unsigned int touch_index);
232 
233 /**
234  * Retrieve the tooltype for touch at given index.
235  *
236  * \param [in] event The touch event
237  * \param [in] touch_index The touch index. Must be less than (touch_count - 1).
238  * \return Tooltype used for the touch at index
239  */
240 MirTouchTooltype mir_touch_event_tooltype(MirTouchEvent const* event, unsigned int touch_index);
241 
242 
243 /**
244  * Retrieve the axis value for a given axis on an indexed touch.
245  *
246  * \param [in] event The touch event
247  * \param [in] touch_index The touch index. Must be less than (touch_count - 1).
248  * \param [in] axis The axis to retreive a value from
249  * \return The value of the given axis
250  */
251 float mir_touch_event_axis_value(MirTouchEvent const* event, unsigned int touch_index, MirTouchAxis axis);
252 
253 /**
254  * Retrieve the corresponding input event.
255  *
256  * \param [in] event The touch event
257  * \return The input event
258  */
259 MirInputEvent const* mir_touch_event_input_event(MirTouchEvent const* event);
260 
261 
262 /**
263  * Retrieve the modifier keys pressed when the pointer action occured.
264  *
265  * \param [in] event The pointer event
266  * \return The modifier mask
267  */
269 
270 /**
271  * Retrieve the action which occured to generate a given pointer event.
272  *
273  * \param [in] event The pointer event
274  * \return Action performed by the pointer
275  */
276 MirPointerAction mir_pointer_event_action(MirPointerEvent const* event);
277 
278 /**
279  * Retrieve the state of a given pointer button when the action occurred.
280  *
281  * \param [in] event The pointer event
282  * \param [in] button The button to check
283  *
284  * \return Whether the given button is depressed
285  */
286 bool mir_pointer_event_button_state(MirPointerEvent const* event,
287  MirPointerButton button);
288 
289 /**
290  * Retreive the pointer button state as a masked set of values.
291  *
292  * \param [in] event The pointer event
293  *
294  * \return The button state
295  */
296 MirPointerButtons mir_pointer_event_buttons(MirPointerEvent const* event);
297 
298 /**
299  * Retrieve the axis value reported by a given pointer event.
300  *
301  * \param [in] event The pointer event
302  * \param [in] axis The axis to retreive a value from
303  * \return The value of the given axis
304  */
305 float mir_pointer_event_axis_value(MirPointerEvent const* event,
306  MirPointerAxis axis);
307 
308 /**
309  * Retrieve the corresponding input event.
310  *
311  * \param [in] event The pointer event
312  * \return The input event
313  */
314 MirInputEvent const* mir_pointer_event_input_event(MirPointerEvent const* event);
315 }
316 }
317 
318 #endif //MIRAL_TOOLKIT_EVENT_H_

Copyright © 2012-2022 Canonical Ltd.
Generated on Thu Sep 8 12:37:23 UTC 2022
This documentation is licensed under the GPL version 2 or 3.