1	/*
2	* Copyright © 2013 Jonas Ådahl
3	* Copyright © 2013-2015 Red Hat, Inc.
4	*
5	* Permission is hereby granted, free of charge, to any person obtaining a
6	* copy of this software and associated documentation files (the "Software"),
7	* to deal in the Software without restriction, including without limitation
8	* the rights to use, copy, modify, merge, publish, distribute, sublicense,
9	* and/or sell copies of the Software, and to permit persons to whom the
10	* Software is furnished to do so, subject to the following conditions:
11	*
12	* The above copyright notice and this permission notice (including the next
13	* paragraph) shall be included in all copies or substantial portions of the
14	* Software.
15	*
16	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19	* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21	* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22	* DEALINGS IN THE SOFTWARE.
23	*/
24
25	#ifndef LIBINPUT_H
26	#define LIBINPUT_H
27
28	#ifdef __cplusplus
29	extern "C" {
30	#endif
31
32	#include <stdlib.h>
33	#include <stdint.h>
34	#include <stdarg.h>
35	#include <libudev.h>
36
37	#define LIBINPUT_ATTRIBUTE_PRINTF(_format, _args) \
38	__attribute__ ((format (printf, _format, _args)))
39	#define LIBINPUT_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated))
40
41	/**
42	* @ingroup base
43	* @struct libinput
44	*
45	* A handle for accessing libinput. This struct is refcounted, use
46	* libinput_ref() and libinput_unref().
47	*/
48	struct libinput;
49
50	/**
51	* @ingroup device
52	* @struct libinput_device
53	*
54	* A base handle for accessing libinput devices. This struct is
55	* refcounted, use libinput_device_ref() and libinput_device_unref().
56	*/
57	struct libinput_device;
58
59	/**
60	* @ingroup device
61	* @struct libinput_device_group
62	*
63	* A base handle for accessing libinput device groups. This struct is
64	* refcounted, use libinput_device_group_ref() and
65	* libinput_device_group_unref().
66	*/
67	struct libinput_device_group;
68
69	/**
70	* @ingroup seat
71	* @struct libinput_seat
72	*
73	* The base handle for accessing libinput seats. This struct is
74	* refcounted, use libinput_seat_ref() and libinput_seat_unref().
75	*/
76	struct libinput_seat;
77
78	/**
79	* @ingroup device
80	* @struct libinput_tablet_tool
81	*
82	* An object representing a tool being used by a device with the @ref
83	* LIBINPUT_DEVICE_CAP_TABLET_TOOL capability.
84	*
85	* Tablet events generated by such a device are bound to a specific tool
86	* rather than coming from the device directly. Depending on the hardware it
87	* is possible to track the same physical tool across multiple
88	* struct libinput_device devices.
89	* See libinput_tablet_tool_get_serial() for more details.
90	*
91	* This struct is refcounted, use libinput_tablet_tool_ref() and
92	* libinput_tablet_tool_unref().
93	*
94	* @since 1.2
95	*/
96	struct libinput_tablet_tool;
97
98	/**
99	* @ingroup event
100	* @struct libinput_event
101	*
102	* The base event type. Use libinput_event_get_pointer_event() or similar to
103	* get the actual event type.
104	*
105	* @warning Unlike other structs events are considered transient and
106	* <b>not</b> refcounted.
107	*/
108	struct libinput_event;
109
110	/**
111	* @ingroup event
112	* @struct libinput_event_device_notify
113	*
114	* An event notifying the caller of a device being added or removed.
115	*/
116	struct libinput_event_device_notify;
117
118	/**
119	* @ingroup event_keyboard
120	* @struct libinput_event_keyboard
121	*
122	* A keyboard event representing a key press/release.
123	*/
124	struct libinput_event_keyboard;
125
126	/**
127	* @ingroup event_pointer
128	* @struct libinput_event_pointer
129	*
130	* A pointer event representing relative or absolute pointer movement,
131	* a button press/release or scroll axis events.
132	*/
133	struct libinput_event_pointer;
134
135	/**
136	* @ingroup event_touch
137	* @struct libinput_event_touch
138	*
139	* Touch event representing a touch down, move or up, as well as a touch
140	* cancel and touch frame events. Valid event types for this event are @ref
141	* LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
142	* LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
143	* LIBINPUT_EVENT_TOUCH_FRAME.
144	*/
145	struct libinput_event_touch;
146
147	/**
148	* @ingroup event_tablet
149	* @struct libinput_event_tablet_tool
150	*
151	* Tablet tool event representing an axis update, button press, or tool
152	* update. Valid event types for this event are @ref
153	* LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
154	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY and @ref
155	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
156	*
157	* @since 1.2
158	*/
159	struct libinput_event_tablet_tool;
160
161	/**
162	* @ingroup event_tablet_pad
163	* @struct libinput_event_tablet_pad
164	*
165	* Tablet pad event representing a button press, or ring/strip update on
166	* the tablet pad itself. Valid event types for this event are @ref
167	* LIBINPUT_EVENT_TABLET_PAD_BUTTON, @ref LIBINPUT_EVENT_TABLET_PAD_RING and
168	* @ref LIBINPUT_EVENT_TABLET_PAD_STRIP.
169	*
170	* @since 1.3
171	*/
172	struct libinput_event_tablet_pad;
173
174	/**
175	* @ingroup base
176	*
177	* Log priority for internal logging messages.
178	*/
179	enum libinput_log_priority {
180	LIBINPUT_LOG_PRIORITY_DEBUG = 10,
181	LIBINPUT_LOG_PRIORITY_INFO = 20,
182	LIBINPUT_LOG_PRIORITY_ERROR = 30,
183	};
184
185	/**
186	* @ingroup device
187	*
188	* Capabilities on a device. A device may have one or more capabilities
189	* at a time, capabilities remain static for the lifetime of the device.
190	*/
191	enum libinput_device_capability {
192	LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
193	LIBINPUT_DEVICE_CAP_POINTER = 1,
194	LIBINPUT_DEVICE_CAP_TOUCH = 2,
195	LIBINPUT_DEVICE_CAP_TABLET_TOOL = 3,
196	LIBINPUT_DEVICE_CAP_TABLET_PAD = 4,
197	LIBINPUT_DEVICE_CAP_GESTURE = 5,
198	LIBINPUT_DEVICE_CAP_SWITCH = 6,
199	};
200
201	/**
202	* @ingroup device
203	*
204	* Logical state of a key. Note that the logical state may not represent
205	* the physical state of the key.
206	*/
207	enum libinput_key_state {
208	LIBINPUT_KEY_STATE_RELEASED = 0,
209	LIBINPUT_KEY_STATE_PRESSED = 1
210	};
211
212	/**
213	* @ingroup device
214	*
215	* Mask reflecting LEDs on a device.
216	*/
217	enum libinput_led {
218	LIBINPUT_LED_NUM_LOCK = (1 << 0),
219	LIBINPUT_LED_CAPS_LOCK = (1 << 1),
220	LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
221	};
222
223	/**
224	* @ingroup device
225	*
226	* Logical state of a physical button. Note that the logical state may not
227	* represent the physical state of the button.
228	*/
229	enum libinput_button_state {
230	LIBINPUT_BUTTON_STATE_RELEASED = 0,
231	LIBINPUT_BUTTON_STATE_PRESSED = 1
232	};
233
234	/**
235	* @ingroup device
236	*
237	* Axes on a device with the capability @ref LIBINPUT_DEVICE_CAP_POINTER
238	* that are not x or y coordinates.
239	*
240	* The two scroll axes @ref LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
241	* @ref LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL are engaged separately,
242	* depending on the device. libinput provides some scroll direction locking
243	* but it is up to the caller to determine which axis is needed and
244	* appropriate in the current interaction
245	*/
246	enum libinput_pointer_axis {
247	LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0,
248	LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1,
249	};
250
251	/**
252	* @ingroup device
253	*
254	* The source for a libinput_pointer_axis event. See
255	* libinput_event_pointer_get_axis_source() for details.
256	*
257	* @note Pointer axis sources are deprecated, the source is now encoded in
258	* the event types
259	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
260	* @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and
261	* @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS.
262	*/
263	enum libinput_pointer_axis_source {
264	/**
265	* The event is caused by the rotation of a wheel.
266	*/
267	LIBINPUT_POINTER_AXIS_SOURCE_WHEEL = 1,
268	/**
269	* The event is caused by the movement of one or more fingers on a
270	* device.
271	*/
272	LIBINPUT_POINTER_AXIS_SOURCE_FINGER,
273	/**
274	* The event is caused by the motion of some device.
275	*/
276	LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS,
277	/**
278	* The event is caused by the tilting of a mouse wheel rather than
279	* its rotation. This method is commonly used on mice without
280	* separate horizontal scroll wheels.
281	*
282	* @deprecated This axis source is deprecated as of libinput 1.16.
283	* It was never used by any device before libinput 1.16. All wheel
284	* tilt devices use @ref LIBINPUT_POINTER_AXIS_SOURCE_WHEEL instead.
285	*/
286	LIBINPUT_POINTER_AXIS_SOURCE_WHEEL_TILT,
287	};
288
289	/**
290	* @ingroup event_tablet_pad
291	*
292	* The source for a @ref LIBINPUT_EVENT_TABLET_PAD_RING event. See
293	* libinput_event_tablet_pad_get_ring_source() for details.
294	*
295	* @since 1.3
296	*/
297	enum libinput_tablet_pad_ring_axis_source {
298	LIBINPUT_TABLET_PAD_RING_SOURCE_UNKNOWN = 1,
299	/**
300	* The event is caused by the movement of one or more fingers on
301	* the ring.
302	*/
303	LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER,
304	};
305
306	/**
307	* @ingroup event_tablet_pad
308	*
309	* The source for a @ref LIBINPUT_EVENT_TABLET_PAD_STRIP event. See
310	* libinput_event_tablet_pad_get_strip_source() for details.
311	*
312	* @since 1.3
313	*/
314	enum libinput_tablet_pad_strip_axis_source {
315	LIBINPUT_TABLET_PAD_STRIP_SOURCE_UNKNOWN = 1,
316	/**
317	* The event is caused by the movement of one or more fingers on
318	* the strip.
319	*/
320	LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER,
321	};
322
323	/**
324	* @ingroup device
325	*
326	* Available tool types for a device with the @ref
327	* LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. The tool type defines the default
328	* usage of the tool as advertised by the manufacturer. Multiple different
329	* physical tools may share the same tool type, e.g. a Wacom Classic Pen,
330	* Wacom Pro Pen and a Wacom Grip Pen are all of type @ref
331	* LIBINPUT_TABLET_TOOL_TYPE_PEN.
332	* Use libinput_tablet_tool_get_tool_id() to get a specific model where applicable.
333	*
334	* Note that on some device, the eraser tool is on the tail end of a pen
335	* device. On other devices, e.g. MS Surface 3, the eraser is the pen tip
336	* while a button is held down.
337	*
338	* @note The @ref libinput_tablet_tool_type can only describe the default physical
339	* type of the device. For devices with adjustable physical properties
340	* the tool type remains the same, i.e. putting a Wacom stroke nib into a
341	* classic pen leaves the tool type as @ref LIBINPUT_TABLET_TOOL_TYPE_PEN.
342	*
343	* @since 1.2
344	*/
345	enum libinput_tablet_tool_type {
346	LIBINPUT_TABLET_TOOL_TYPE_PEN = 1, /**< A generic pen */
347	LIBINPUT_TABLET_TOOL_TYPE_ERASER, /**< Eraser */
348	LIBINPUT_TABLET_TOOL_TYPE_BRUSH, /**< A paintbrush-like tool */
349	LIBINPUT_TABLET_TOOL_TYPE_PENCIL, /**< Physical drawing tool, e.g.
350	Wacom Inking Pen */
351	LIBINPUT_TABLET_TOOL_TYPE_AIRBRUSH, /**< An airbrush-like tool */
352	LIBINPUT_TABLET_TOOL_TYPE_MOUSE, /**< A mouse bound to the tablet */
353	LIBINPUT_TABLET_TOOL_TYPE_LENS, /**< A mouse tool with a lens */
354	LIBINPUT_TABLET_TOOL_TYPE_TOTEM, /**< A rotary device with
355	positional and rotation
356	data */
357	};
358
359	/**
360	* @ingroup device
361	*
362	* The state of proximity for a tool on a device. The device must have the @ref
363	* LIBINPUT_DEVICE_CAP_TABLET_TOOL capability.
364	*
365	* The proximity of a tool is a binary state signalling whether the tool is
366	* within a detectable distance of the tablet device. A tool that is out of
367	* proximity cannot generate events.
368	*
369	* On some hardware a tool goes out of proximity when it ceases to touch the
370	* surface. On other hardware, the tool is still detectable within a short
371	* distance (a few cm) off the surface.
372	*
373	* @since 1.2
374	*/
375	enum libinput_tablet_tool_proximity_state {
376	LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_OUT = 0,
377	LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_IN = 1,
378	};
379
380	/**
381	* @ingroup device
382	*
383	* The tip contact state for a tool on a device. The device must have
384	* the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability.
385	*
386	* The tip contact state of a tool is a binary state signalling whether the tool is
387	* touching the surface of the tablet device.
388	*
389	* @since 1.2
390	*/
391	enum libinput_tablet_tool_tip_state {
392	LIBINPUT_TABLET_TOOL_TIP_UP = 0,
393	LIBINPUT_TABLET_TOOL_TIP_DOWN = 1,
394	};
395
396	/**
397	* @defgroup tablet_pad_modes Tablet pad modes
398	*
399	* Handling the virtual mode groups of buttons, strips and rings on tablet
400	* pad devices. See the libinput documentation for more details.
401	*/
402
403	/**
404	* @ingroup tablet_pad_modes
405	* @struct libinput_tablet_pad_mode_group
406	*
407	* A mode on a tablet pad is a virtual grouping of functionality, usually
408	* based on some visual feedback like LEDs on the pad. The set of buttons,
409	* rings and strips that share the same mode are a "mode group". Whenever
410	* the mode changes, all buttons, rings and strips within this mode group
411	* are affected.
412	*
413	* Most tablets only have a single mode group, some tablets provide multiple
414	* mode groups through independent banks of LEDs (e.g. the Wacom Cintiq
415	* 24HD). libinput guarantees that at least one mode group is always
416	* available.
417	*
418	* This struct is refcounted, use libinput_tablet_pad_mode_group_ref() and
419	* libinput_tablet_pad_mode_group_unref().
420	*
421	* @since 1.4
422	*/
423	struct libinput_tablet_pad_mode_group;
424
425	/**
426	* @ingroup tablet_pad_modes
427	*
428	* Most devices only provide a single mode group, however devices such as
429	* the Wacom Cintiq 22HD provide two mode groups. If multiple mode groups
430	* are available, a caller should use
431	* libinput_tablet_pad_mode_group_has_button(),
432	* libinput_tablet_pad_mode_group_has_ring() and
433	* libinput_tablet_pad_mode_group_has_strip() to associate each button,
434	* ring and strip with the correct mode group.
435	*
436	* @return the number of mode groups available on this device
437	*
438	* @since 1.4
439	*/
440	int
441	libinput_device_tablet_pad_get_num_mode_groups(struct libinput_device *device);
442
443	/**
444	* @ingroup tablet_pad_modes
445	*
446	* The returned mode group is not refcounted and may become invalid after
447	* the next call to libinput. Use libinput_tablet_pad_mode_group_ref() and
448	* libinput_tablet_pad_mode_group_unref() to continue using the handle
449	* outside of the immediate scope.
450	*
451	* While at least one reference is kept by the caller, the returned mode
452	* group will be identical for each subsequent call of this function with
453	* the same index and that same struct is returned from
454	* libinput_event_tablet_pad_get_mode_group(), provided the event was
455	* generated by this mode group.
456	*
457	* @param device A device with the @ref LIBINPUT_DEVICE_CAP_TABLET_PAD
458	* capability
459	* @param index A mode group index
460	* @return the mode group with the given index or NULL if an invalid index
461	* is given.
462	*
463	* @since 1.4
464	*/
465	struct libinput_tablet_pad_mode_group*
466	libinput_device_tablet_pad_get_mode_group(struct libinput_device *device,
467	unsigned int index);
468
469	/**
470	* @ingroup tablet_pad_modes
471	*
472	* The returned number is the same index as passed to
473	* libinput_device_tablet_pad_get_mode_group(). For tablets with only one
474	* mode this number is always 0.
475	*
476	* @param group A previously obtained mode group
477	* @return the numeric index this mode group represents, starting at 0
478	*
479	* @since 1.4
480	*/
481	unsigned int
482	libinput_tablet_pad_mode_group_get_index(struct libinput_tablet_pad_mode_group *group);
483
484	/**
485	* @ingroup tablet_pad_modes
486	*
487	* Query the mode group for the number of available modes. The number of
488	* modes is usually decided by the number of physical LEDs available on the
489	* device. Different mode groups may have a different number of modes. Use
490	* libinput_tablet_pad_mode_group_get_mode() to get the currently active
491	* mode.
492	*
493	* libinput guarantees that at least one mode is available. A device without
494	* mode switching capability has a single mode group and a single mode.
495	*
496	* @param group A previously obtained mode group
497	* @return the number of modes available in this mode group
498	*
499	* @since 1.4
500	*/
501	unsigned int
502	libinput_tablet_pad_mode_group_get_num_modes(struct libinput_tablet_pad_mode_group *group);
503
504	/**
505	* @ingroup tablet_pad_modes
506	*
507	* Return the current mode this mode group is in. Note that the returned
508	* mode is the mode valid as of completing the last libinput_dispatch().
509	* The returned mode may thus be different than the mode returned by
510	* libinput_event_tablet_pad_get_mode().
511	*
512	* For example, if the mode was toggled three times between the call to
513	* libinput_dispatch(), this function returns the third mode but the events
514	* in the event queue will return the modes 1, 2 and 3, respectively.
515	*
516	* @param group A previously obtained mode group
517	* @return the numeric index of the current mode in this group, starting at 0
518	*
519	* @see libinput_event_tablet_pad_get_mode
520	*
521	* @since 1.4
522	*/
523	unsigned int
524	libinput_tablet_pad_mode_group_get_mode(struct libinput_tablet_pad_mode_group *group);
525
526	/**
527	* @ingroup tablet_pad_modes
528	*
529	* Devices without mode switching capabilities return true for every button.
530	*
531	* @param group A previously obtained mode group
532	* @param button A button index, starting at 0
533	* @return true if the given button index is part of this mode group or
534	* false otherwise
535	*
536	* @since 1.4
537	*/
538	int
539	libinput_tablet_pad_mode_group_has_button(struct libinput_tablet_pad_mode_group *group,
540	unsigned int button);
541
542	/**
543	* @ingroup tablet_pad_modes
544	*
545	* Devices without mode switching capabilities return true for every ring.
546	*
547	* @param group A previously obtained mode group
548	* @param ring A ring index, starting at 0
549	* @return true if the given ring index is part of this mode group or
550	* false otherwise
551	*
552	* @since 1.4
553	*/
554	int
555	libinput_tablet_pad_mode_group_has_ring(struct libinput_tablet_pad_mode_group *group,
556	unsigned int ring);
557
558	/**
559	* @ingroup tablet_pad_modes
560	*
561	* Devices without mode switching capabilities return true for every strip.
562	*
563	* @param group A previously obtained mode group
564	* @param strip A strip index, starting at 0
565	* @return true if the given strip index is part of this mode group or
566	* false otherwise
567	*
568	* @since 1.4
569	*/
570	int
571	libinput_tablet_pad_mode_group_has_strip(struct libinput_tablet_pad_mode_group *group,
572	unsigned int strip);
573
574	/**
575	* @ingroup tablet_pad_modes
576	*
577	* The toggle button in a mode group is the button assigned to cycle to or
578	* directly assign a new mode when pressed. Not all devices have a toggle
579	* button and some devices may have more than one toggle button. For
580	* example, the Wacom Cintiq 24HD has six toggle buttons in two groups, each
581	* directly selecting one of the three modes per group.
582	*
583	* Devices without mode switching capabilities return false for every button.
584	*
585	* @param group A previously obtained mode group
586	* @param button A button index, starting at 0
587	* @retval non-zero if the button is a mode toggle button for this group, or
588	* zero otherwise
589	*
590	* @since 1.4
591	*/
592	int
593	libinput_tablet_pad_mode_group_button_is_toggle(struct libinput_tablet_pad_mode_group *group,
594	unsigned int button);
595
596	/**
597	* @ingroup tablet_pad_modes
598	*
599	* Increase the refcount of the mode group. A mode group will be
600	* freed whenever the refcount reaches 0.
601	*
602	* @param group A previously obtained mode group
603	* @return The passed mode group
604	*
605	* @since 1.4
606	*/
607	struct libinput_tablet_pad_mode_group *
608	libinput_tablet_pad_mode_group_ref(
609	struct libinput_tablet_pad_mode_group *group);
610
611	/**
612	* @ingroup tablet_pad_modes
613	*
614	* Decrease the refcount of the mode group. A mode group will be
615	* freed whenever the refcount reaches 0.
616	*
617	* @param group A previously obtained mode group
618	* @return NULL if the group was destroyed, otherwise the passed mode group
619	*
620	* @since 1.4
621	*/
622	struct libinput_tablet_pad_mode_group *
623	libinput_tablet_pad_mode_group_unref(
624	struct libinput_tablet_pad_mode_group *group);
625
626	/**
627	* @ingroup tablet_pad_modes
628	*
629	* Set caller-specific data associated with this mode group. libinput does
630	* not manage, look at, or modify this data. The caller must ensure the
631	* data is valid.
632	*
633	* @param group A previously obtained mode group
634	* @param user_data Caller-specific data pointer
635	* @see libinput_tablet_pad_mode_group_get_user_data
636	*
637	* @since 1.4
638	*/
639	void
640	libinput_tablet_pad_mode_group_set_user_data(
641	struct libinput_tablet_pad_mode_group *group,
642	void *user_data);
643
644	/**
645	* @ingroup tablet_pad_modes
646	*
647	* Get the caller-specific data associated with this mode group, if any.
648	*
649	* @param group A previously obtained mode group
650	* @return Caller-specific data pointer or NULL if none was set
651	* @see libinput_tablet_pad_mode_group_set_user_data
652	*
653	* @since 1.4
654	*/
655	void *
656	libinput_tablet_pad_mode_group_get_user_data(
657	struct libinput_tablet_pad_mode_group *group);
658
659	/**
660	* @ingroup device
661	*
662	* The state of a switch. The default state of a switch is @ref
663	* LIBINPUT_SWITCH_STATE_OFF and no event is sent to confirm a switch in the
664	* off position. If a switch is logically on during initialization, libinput
665	* sends an event of type @ref LIBINPUT_EVENT_SWITCH_TOGGLE with a state
666	* @ref LIBINPUT_SWITCH_STATE_ON.
667	*
668	* @since 1.7
669	*/
670	enum libinput_switch_state {
671	LIBINPUT_SWITCH_STATE_OFF = 0,
672	LIBINPUT_SWITCH_STATE_ON = 1,
673	};
674
675	/**
676	* @ingroup device
677	*
678	* The type of a switch.
679	*
680	* @since 1.7
681	*/
682	enum libinput_switch {
683	/**
684	* The laptop lid was closed when the switch state is @ref
685	* LIBINPUT_SWITCH_STATE_ON, or was opened when it is @ref
686	* LIBINPUT_SWITCH_STATE_OFF.
687	*/
688	LIBINPUT_SWITCH_LID = 1,
689
690	/**
691	* This switch indicates whether the device is in normal laptop mode
692	* or behaves like a tablet-like device where the primary
693	* interaction is usually a touch screen. When in tablet mode, the
694	* keyboard and touchpad are usually inaccessible.
695	*
696	* If the switch is in state @ref LIBINPUT_SWITCH_STATE_OFF, the
697	* device is in laptop mode. If the switch is in state @ref
698	* LIBINPUT_SWITCH_STATE_ON, the device is in tablet mode and the
699	* keyboard or touchpad may not be accessible.
700	*
701	* It is up to the caller to identify which devices are inaccessible
702	* in tablet mode.
703	*/
704	LIBINPUT_SWITCH_TABLET_MODE,
705	};
706
707	/**
708	* @ingroup event_switch
709	* @struct libinput_event_switch
710	*
711	* A switch event representing a changed state in a switch.
712	*
713	* @since 1.7
714	*/
715	struct libinput_event_switch;
716
717	/**
718	* @ingroup base
719	*
720	* Event type for events returned by libinput_get_event().
721	*/
722	enum libinput_event_type {
723	/**
724	* This is not a real event type, and is only used to tell the user that
725	* no new event is available in the queue. See
726	* libinput_next_event_type().
727	*/
728	LIBINPUT_EVENT_NONE = 0,
729
730	/**
731	* Signals that a device has been added to the context. The device will
732	* not be read until the next time the user calls libinput_dispatch()
733	* and data is available.
734	*
735	* This allows setting up initial device configuration before any events
736	* are created.
737	*/
738	LIBINPUT_EVENT_DEVICE_ADDED,
739
740	/**
741	* Signals that a device has been removed. No more events from the
742	* associated device will be in the queue or be queued after this event.
743	*/
744	LIBINPUT_EVENT_DEVICE_REMOVED,
745
746	LIBINPUT_EVENT_KEYBOARD_KEY = 300,
747
748	LIBINPUT_EVENT_POINTER_MOTION = 400,
749	LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
750	LIBINPUT_EVENT_POINTER_BUTTON,
751	/**
752	* A scroll event from various sources.
753	*
754	* This event is deprecated as of libinput 1.19. Use
755	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
756	* @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and
757	* @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS instead.
758	*
759	* Use libinput_event_pointer_get_axis_source() to determine the
760	* source of a scroll event. For libinput versions 1.19 and later,
761	* the source is encoded in the event type.
762	*
763	* This event is sent **in addition** to events of type
764	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
765	* @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and
766	* @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS.
767	* Do not mix and match, either use the old event or the new events.
768	* libinput makes no guarantee about the relation between
769	* @ref LIBINPUT_EVENT_POINTER_AXIS and the new event types
770	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
771	* @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and
772	* @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS. You may receive
773	* multiple zero, one or more new events per legacy event.
774	*
775	* @warning Ignore this event if you are processing
776	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
777	* @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and
778	* @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS.
779	*/
780	LIBINPUT_EVENT_POINTER_AXIS,
781
782	/**
783	* A scroll event from a wheel. This event is sent is sent **in
784	* addition** to the @ref LIBINPUT_EVENT_POINTER_AXIS
785	* event for all events with a
786	* libinput_event_pointer_get_axis_source() of @ref
787	* LIBINPUT_POINTER_AXIS_SOURCE_WHEEL. Ignore @ref
788	* LIBINPUT_EVENT_POINTER_AXIS if you are processing this event.
789	*
790	* See the libinput documentation for details.
791	*
792	* @since 1.19
793	*/
794	LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
795
796	/**
797	* A scroll event caused by the movement of one or more fingers on a
798	* device. This event is sent is sent **in addition** to the @ref
799	* LIBINPUT_EVENT_POINTER_AXIS event for all events with a
800	* libinput_event_pointer_get_axis_source() of @ref
801	* LIBINPUT_POINTER_AXIS_SOURCE_FINGER. Ignore @ref
802	* LIBINPUT_EVENT_POINTER_AXIS if you are processing this event.
803	*
804	* See the libinput documentation for details.
805	*
806	* @since 1.19
807	*/
808	LIBINPUT_EVENT_POINTER_SCROLL_FINGER,
809
810	/**
811	* A scroll event from a continuous scroll source, e.g. button
812	* scrolling. This event is sent is sent **in
813	* addition** to the @ref LIBINPUT_EVENT_POINTER_AXIS
814	* event for all events with a
815	* libinput_event_pointer_get_axis_source() of @ref
816	* LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS. Ignore @ref
817	* LIBINPUT_EVENT_POINTER_AXIS if you are processing this event.
818	*
819	* See the libinput documentation for details.
820	*
821	* @since 1.19
822	*/
823	LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS,
824
825	LIBINPUT_EVENT_TOUCH_DOWN = 500,
826	LIBINPUT_EVENT_TOUCH_UP,
827	LIBINPUT_EVENT_TOUCH_MOTION,
828	LIBINPUT_EVENT_TOUCH_CANCEL,
829	/**
830	* Signals the end of a set of touchpoints at one device sample
831	* time. This event has no coordinate information attached.
832	*/
833	LIBINPUT_EVENT_TOUCH_FRAME,
834
835	/**
836	* One or more axes have changed state on a device with the @ref
837	* LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. This event is only sent
838	* when the tool is in proximity, see @ref
839	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY for details.
840	*
841	* The proximity event contains the initial state of the axis as the
842	* tool comes into proximity. An event of type @ref
843	* LIBINPUT_EVENT_TABLET_TOOL_AXIS is only sent when an axis value
844	* changes from this initial state. It is possible for a tool to
845	* enter and leave proximity without sending an event of type @ref
846	* LIBINPUT_EVENT_TABLET_TOOL_AXIS.
847	*
848	* An event of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS is sent
849	* when the tip state does not change. See the documentation for
850	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP for more details.
851	*
852	* @since 1.2
853	*/
854	LIBINPUT_EVENT_TABLET_TOOL_AXIS = 600,
855	/**
856	* Signals that a tool has come in or out of proximity of a device with
857	* the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability.
858	*
859	* Proximity events contain each of the current values for each axis,
860	* and these values may be extracted from them in the same way they are
861	* with @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS events.
862	*
863	* Some tools may always be in proximity. For these tools, events of
864	* type @ref LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_IN are sent only once after @ref
865	* LIBINPUT_EVENT_DEVICE_ADDED, and events of type @ref
866	* LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_OUT are sent only once before @ref
867	* LIBINPUT_EVENT_DEVICE_REMOVED.
868	*
869	* If the tool that comes into proximity supports x/y coordinates,
870	* libinput guarantees that both x and y are set in the proximity
871	* event.
872	*
873	* When a tool goes out of proximity, the value of every axis should be
874	* assumed to have an undefined state and any buttons that are currently held
875	* down on the stylus are marked as released. Button release events for
876	* each button that was held down on the stylus are sent before the
877	* proximity out event.
878	*
879	* @since 1.2
880	*/
881	LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY,
882	/**
883	* Signals that a tool has come in contact with the surface of a
884	* device with the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability.
885	*
886	* On devices without distance proximity detection, the @ref
887	* LIBINPUT_EVENT_TABLET_TOOL_TIP is sent immediately after @ref
888	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY for the tip down event, and
889	* immediately before for the tip up event.
890	*
891	* The decision when a tip touches the surface is device-dependent
892	* and may be derived from pressure data or other means. If the tip
893	* state is changed by axes changing state, the
894	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP event includes the changed
895	* axes and no additional axis event is sent for this state change.
896	* In other words, a caller must look at both @ref
897	* LIBINPUT_EVENT_TABLET_TOOL_AXIS and @ref
898	* LIBINPUT_EVENT_TABLET_TOOL_TIP events to know the current state
899	* of the axes.
900	*
901	* If a button state change occurs at the same time as a tip state
902	* change, the order of events is device-dependent.
903	*
904	* @since 1.2
905	*/
906	LIBINPUT_EVENT_TABLET_TOOL_TIP,
907	/**
908	* Signals that a tool has changed a logical button state on a
909	* device with the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability.
910	*
911	* Button state changes occur on their own and do not include axis
912	* state changes. If button and axis state changes occur within the
913	* same logical hardware event, the order of the @ref
914	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON and @ref
915	* LIBINPUT_EVENT_TABLET_TOOL_AXIS event is device-specific.
916	*
917	* This event is not to be confused with the button events emitted
918	* by the tablet pad. See @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON.
919	*
920	* @see LIBINPUT_EVENT_TABLET_PAD_BUTTON
921	*
922	* @since 1.2
923	*/
924	LIBINPUT_EVENT_TABLET_TOOL_BUTTON,
925
926	/**
927	* A button pressed on a device with the @ref
928	* LIBINPUT_DEVICE_CAP_TABLET_PAD capability.
929	*
930	* A button differs from @ref LIBINPUT_EVENT_TABLET_PAD_KEY in that
931	* buttons are sequentially indexed from 0 and do not carry any
932	* other information. Keys have a specific functionality assigned
933	* to them. The key code thus carries a semantic meaning, a button
934	* number does not.
935	*
936	* This event is not to be confused with the button events emitted
937	* by tools on a tablet (@ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON).
938	*
939	* @since 1.3
940	*/
941	LIBINPUT_EVENT_TABLET_PAD_BUTTON = 700,
942	/**
943	* A status change on a tablet ring with the @ref
944	* LIBINPUT_DEVICE_CAP_TABLET_PAD capability.
945	*
946	* @since 1.3
947	*/
948	LIBINPUT_EVENT_TABLET_PAD_RING,
949
950	/**
951	* A status change on a strip on a device with the @ref
952	* LIBINPUT_DEVICE_CAP_TABLET_PAD capability.
953	*
954	* @since 1.3
955	*/
956	LIBINPUT_EVENT_TABLET_PAD_STRIP,
957
958	/**
959	* A key pressed on a device with the @ref
960	* LIBINPUT_DEVICE_CAP_TABLET_PAD capability.
961	*
962	* A key differs from @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON in that
963	* keys have a specific functionality assigned to them (buttons are
964	* sequentially ordered). The key code thus carries a semantic
965	* meaning, a button number does not.
966	*
967	* @since 1.15
968	*/
969	LIBINPUT_EVENT_TABLET_PAD_KEY,
970
971	LIBINPUT_EVENT_GESTURE_SWIPE_BEGIN = 800,
972	LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE,
973	LIBINPUT_EVENT_GESTURE_SWIPE_END,
974	LIBINPUT_EVENT_GESTURE_PINCH_BEGIN,
975	LIBINPUT_EVENT_GESTURE_PINCH_UPDATE,
976	LIBINPUT_EVENT_GESTURE_PINCH_END,
977	/**
978	* @since 1.19
979	*/
980	LIBINPUT_EVENT_GESTURE_HOLD_BEGIN,
981	LIBINPUT_EVENT_GESTURE_HOLD_END,
982
983	/**
984	* @since 1.7
985	*/
986	LIBINPUT_EVENT_SWITCH_TOGGLE = 900,
987	};
988
989	/**
990	* @defgroup event Accessing and destruction of events
991	*/
992
993	/**
994	* @ingroup event
995	*
996	* Destroy the event, freeing all associated resources. Resources obtained
997	* from this event must be considered invalid after this call.
998	*
999	* @warning Unlike other structs events are considered transient and
1000	* <b>not</b> refcounted. Calling libinput_event_destroy() <b>will</b>
1001	* destroy the event.
1002	*
1003	* @param event An event retrieved by libinput_get_event().
1004	*/
1005	void
1006	libinput_event_destroy(struct libinput_event *event);
1007
1008	/**
1009	* @ingroup event
1010	*
1011	* Get the type of the event.
1012	*
1013	* @param event An event retrieved by libinput_get_event().
1014	*/
1015	enum libinput_event_type
1016	libinput_event_get_type(struct libinput_event *event);
1017
1018	/**
1019	* @ingroup event
1020	*
1021	* Get the libinput context from the event.
1022	*
1023	* @param event The libinput event
1024	* @return The libinput context for this event.
1025	*/
1026	struct libinput *
1027	libinput_event_get_context(struct libinput_event *event);
1028
1029	/**
1030	* @ingroup event
1031	*
1032	* Return the device associated with this event. For device added/removed
1033	* events this is the device added or removed. For all other device events,
1034	* this is the device that generated the event.
1035	*
1036	* This device is not refcounted and its lifetime is that of the event. Use
1037	* libinput_device_ref() before using the device outside of this scope.
1038	*
1039	* @return The device associated with this event
1040	*/
1041
1042	struct libinput_device *
1043	libinput_event_get_device(struct libinput_event *event);
1044
1045	/**
1046	* @ingroup event
1047	*
1048	* Return the pointer event that is this input event. If the event type does
1049	* not match the pointer event types, this function returns NULL.
1050	*
1051	* The inverse of this function is libinput_event_pointer_get_base_event().
1052	*
1053	* @return A pointer event, or NULL for other events
1054	*/
1055	struct libinput_event_pointer *
1056	libinput_event_get_pointer_event(struct libinput_event *event);
1057
1058	/**
1059	* @ingroup event
1060	*
1061	* Return the keyboard event that is this input event. If the event type does
1062	* not match the keyboard event types, this function returns NULL.
1063	*
1064	* The inverse of this function is libinput_event_keyboard_get_base_event().
1065	*
1066	* @return A keyboard event, or NULL for other events
1067	*/
1068	struct libinput_event_keyboard *
1069	libinput_event_get_keyboard_event(struct libinput_event *event);
1070
1071	/**
1072	* @ingroup event
1073	*
1074	* Return the touch event that is this input event. If the event type does
1075	* not match the touch event types, this function returns NULL.
1076	*
1077	* The inverse of this function is libinput_event_touch_get_base_event().
1078	*
1079	* @return A touch event, or NULL for other events
1080	*/
1081	struct libinput_event_touch *
1082	libinput_event_get_touch_event(struct libinput_event *event);
1083
1084	/**
1085	* @ingroup event
1086	*
1087	* Return the gesture event that is this input event. If the event type does
1088	* not match the gesture event types, this function returns NULL.
1089	*
1090	* A gesture's lifetime has three distinct stages: begin, update and end, each
1091	* with their own event types. Begin is sent when the fingers are first set
1092	* down or libinput decides that the gesture begins. For @ref
1093	* LIBINPUT_EVENT_GESTURE_PINCH_BEGIN this sets the initial scale. Any
1094	* events changing properties of the gesture are sent as update events. On
1095	* termination of the gesture, an end event is sent.
1096	*
1097	* The inverse of this function is libinput_event_gesture_get_base_event().
1098	*
1099	* @return A gesture event, or NULL for other events
1100	*/
1101	struct libinput_event_gesture *
1102	libinput_event_get_gesture_event(struct libinput_event *event);
1103
1104	/**
1105	* @ingroup event
1106	*
1107	* Return the tablet tool event that is this input event. If the event type
1108	* does not match the tablet tool event types, this function returns NULL.
1109	*
1110	* The inverse of this function is libinput_event_tablet_tool_get_base_event().
1111	*
1112	* @return A tablet tool event, or NULL for other events
1113	*
1114	* @since 1.2
1115	*/
1116	struct libinput_event_tablet_tool *
1117	libinput_event_get_tablet_tool_event(struct libinput_event *event);
1118
1119	/**
1120	* @ingroup event
1121	*
1122	* Return the tablet pad event that is this input event. If the event type does not
1123	* match the tablet pad event types, this function returns NULL.
1124	*
1125	* The inverse of this function is libinput_event_tablet_pad_get_base_event().
1126	*
1127	* @return A tablet pad event, or NULL for other events
1128	*/
1129	struct libinput_event_tablet_pad *
1130	libinput_event_get_tablet_pad_event(struct libinput_event *event);
1131
1132	/**
1133	* @ingroup event
1134	*
1135	* Return the switch event that is this input event. If the event type does
1136	* not match the switch event types, this function returns NULL.
1137	*
1138	* The inverse of this function is libinput_event_switch_get_base_event().
1139	*
1140	* @return A switch event, or NULL for other events
1141	*
1142	* @since 1.7
1143	*/
1144	struct libinput_event_switch *
1145	libinput_event_get_switch_event(struct libinput_event *event);
1146
1147	/**
1148	* @ingroup event
1149	*
1150	* Return the device event that is this input event. If the event type does
1151	* not match the device event types, this function returns NULL.
1152	*
1153	* The inverse of this function is
1154	* libinput_event_device_notify_get_base_event().
1155	*
1156	* @return A device event, or NULL for other events
1157	*/
1158	struct libinput_event_device_notify *
1159	libinput_event_get_device_notify_event(struct libinput_event *event);
1160
1161	/**
1162	* @ingroup event
1163	*
1164	* @return The generic libinput_event of this event
1165	*/
1166	struct libinput_event *
1167	libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
1168
1169	/**
1170	* @defgroup event_keyboard Keyboard events
1171	*
1172	* Key events are generated when a key changes its logical state, usually by
1173	* being pressed or released.
1174	*/
1175
1176	/**
1177	* @ingroup event_keyboard
1178	*
1179	* @note Timestamps may not always increase. See the libinput documentation
1180	* for more details.
1181	*
1182	* @return The event time for this event
1183	*/
1184	uint32_t
1185	libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
1186
1187	/**
1188	* @ingroup event_keyboard
1189	*
1190	* @note Timestamps may not always increase. See the libinput documentation
1191	* for more details.
1192	*
1193	* @return The event time for this event in microseconds
1194	*/
1195	uint64_t
1196	libinput_event_keyboard_get_time_usec(struct libinput_event_keyboard *event);
1197
1198	/**
1199	* @ingroup event_keyboard
1200	*
1201	* @return The keycode that triggered this key event
1202	*/
1203	uint32_t
1204	libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
1205
1206	/**
1207	* @ingroup event_keyboard
1208	*
1209	* @return The state change of the key
1210	*/
1211	enum libinput_key_state
1212	libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
1213
1214	/**
1215	* @ingroup event_keyboard
1216	*
1217	* @return The generic libinput_event of this event
1218	*/
1219	struct libinput_event *
1220	libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
1221
1222	/**
1223	* @ingroup event_keyboard
1224	*
1225	* For the key of a @ref LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
1226	* of keys pressed on all devices on the associated seat after the event was
1227	* triggered.
1228	*
1229	* @note It is an application bug to call this function for events other than
1230	* @ref LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
1231	*
1232	* @return The seat wide pressed key count for the key of this event
1233	*/
1234	uint32_t
1235	libinput_event_keyboard_get_seat_key_count(
1236	struct libinput_event_keyboard *event);
1237
1238	/**
1239	* @defgroup event_pointer Pointer events
1240	*
1241	* Pointer events reflect motion, button and scroll events, as well as
1242	* events from other axes.
1243	*/
1244
1245	/**
1246	* @ingroup event_pointer
1247	*
1248	* @note Timestamps may not always increase. See the libinput documentation
1249	* for more details.
1250	*
1251	* @return The event time for this event
1252	*/
1253	uint32_t
1254	libinput_event_pointer_get_time(struct libinput_event_pointer *event);
1255
1256	/**
1257	* @ingroup event_pointer
1258	*
1259	* @note Timestamps may not always increase. See the libinput documentation
1260	* for more details.
1261	*
1262	* @return The event time for this event in microseconds
1263	*/
1264	uint64_t
1265	libinput_event_pointer_get_time_usec(struct libinput_event_pointer *event);
1266
1267	/**
1268	* @ingroup event_pointer
1269	*
1270	* Return the delta between the last event and the current event. For pointer
1271	* events that are not of type @ref LIBINPUT_EVENT_POINTER_MOTION, this
1272	* function returns 0.
1273	*
1274	* If a device employs pointer acceleration, the delta returned by this
1275	* function is the accelerated delta.
1276	*
1277	* Relative motion deltas are to be interpreted as pixel movement of a
1278	* standardized mouse. See the libinput documentation for more details.
1279	*
1280	* @note It is an application bug to call this function for events other than
1281	* @ref LIBINPUT_EVENT_POINTER_MOTION.
1282	*
1283	* @return The relative x movement since the last event
1284	*/
1285	double
1286	libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
1287
1288	/**
1289	* @ingroup event_pointer
1290	*
1291	* Return the delta between the last event and the current event. For pointer
1292	* events that are not of type @ref LIBINPUT_EVENT_POINTER_MOTION, this
1293	* function returns 0.
1294	*
1295	* If a device employs pointer acceleration, the delta returned by this
1296	* function is the accelerated delta.
1297	*
1298	* Relative motion deltas are to be interpreted as pixel movement of a
1299	* standardized mouse. See the libinput documentation for more details.
1300	*
1301	* @note It is an application bug to call this function for events other than
1302	* @ref LIBINPUT_EVENT_POINTER_MOTION.
1303	*
1304	* @return The relative y movement since the last event
1305	*/
1306	double
1307	libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
1308
1309	/**
1310	* @ingroup event_pointer
1311	*
1312	* Return the relative delta of the unaccelerated motion vector of the
1313	* current event. For pointer events that are not of type @ref
1314	* LIBINPUT_EVENT_POINTER_MOTION, this function returns 0.
1315	*
1316	* Relative unaccelerated motion deltas are raw device coordinates.
1317	* Note that these coordinates are subject to the device's native
1318	* resolution. Touchpad coordinates represent raw device coordinates in the
1319	* X resolution of the touchpad. See the libinput documentation for more
1320	* details.
1321	*
1322	* Any rotation applied to the device also applies to unaccelerated motion
1323	* (see libinput_device_config_rotation_set_angle()).
1324	*
1325	* @note It is an application bug to call this function for events other than
1326	* @ref LIBINPUT_EVENT_POINTER_MOTION.
1327	*
1328	* @return The unaccelerated relative x movement since the last event
1329	*/
1330	double
1331	libinput_event_pointer_get_dx_unaccelerated(
1332	struct libinput_event_pointer *event);
1333
1334	/**
1335	* @ingroup event_pointer
1336	*
1337	* Return the relative delta of the unaccelerated motion vector of the
1338	* current event. For pointer events that are not of type @ref
1339	* LIBINPUT_EVENT_POINTER_MOTION, this function returns 0.
1340	*
1341	* Relative unaccelerated motion deltas are raw device coordinates.
1342	* Note that these coordinates are subject to the device's native
1343	* resolution. Touchpad coordinates represent raw device coordinates in the
1344	* X resolution of the touchpad. See the libinput documentation for more
1345	* details.
1346	*
1347	* Any rotation applied to the device also applies to unaccelerated motion
1348	* (see libinput_device_config_rotation_set_angle()).
1349	*
1350	* @note It is an application bug to call this function for events other than
1351	* @ref LIBINPUT_EVENT_POINTER_MOTION.
1352	*
1353	* @return The unaccelerated relative y movement since the last event
1354	*/
1355	double
1356	libinput_event_pointer_get_dy_unaccelerated(
1357	struct libinput_event_pointer *event);
1358
1359	/**
1360	* @ingroup event_pointer
1361	*
1362	* Return the current absolute x coordinate of the pointer event, in mm from
1363	* the top left corner of the device. To get the corresponding output screen
1364	* coordinate, use libinput_event_pointer_get_absolute_x_transformed().
1365	*
1366	* For pointer events that are not of type
1367	* @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
1368	*
1369	* @note It is an application bug to call this function for events other than
1370	* @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
1371	*
1372	* @return The current absolute x coordinate
1373	*/
1374	double
1375	libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
1376
1377	/**
1378	* @ingroup event_pointer
1379	*
1380	* Return the current absolute y coordinate of the pointer event, in mm from
1381	* the top left corner of the device. To get the corresponding output screen
1382	* coordinate, use libinput_event_pointer_get_absolute_y_transformed().
1383	*
1384	* For pointer events that are not of type
1385	* @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
1386	*
1387	* @note It is an application bug to call this function for events other than
1388	* @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
1389	*
1390	* @return The current absolute y coordinate
1391	*/
1392	double
1393	libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
1394
1395	/**
1396	* @ingroup event_pointer
1397	*
1398	* Return the current absolute x coordinate of the pointer event, transformed to
1399	* screen coordinates.
1400	*
1401	* For pointer events that are not of type
1402	* @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this
1403	* function is undefined.
1404	*
1405	* @note It is an application bug to call this function for events other than
1406	* @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
1407	*
1408	* @param event The libinput pointer event
1409	* @param width The current output screen width
1410	* @return The current absolute x coordinate transformed to a screen coordinate
1411	*/
1412	double
1413	libinput_event_pointer_get_absolute_x_transformed(
1414	struct libinput_event_pointer *event,
1415	uint32_t width);
1416
1417	/**
1418	* @ingroup event_pointer
1419	*
1420	* Return the current absolute y coordinate of the pointer event, transformed to
1421	* screen coordinates.
1422	*
1423	* For pointer events that are not of type
1424	* @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
1425	* undefined.
1426	*
1427	* @note It is an application bug to call this function for events other than
1428	* @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
1429	*
1430	* @param event The libinput pointer event
1431	* @param height The current output screen height
1432	* @return The current absolute y coordinate transformed to a screen coordinate
1433	*/
1434	double
1435	libinput_event_pointer_get_absolute_y_transformed(
1436	struct libinput_event_pointer *event,
1437	uint32_t height);
1438
1439	/**
1440	* @ingroup event_pointer
1441	*
1442	* Return the button that triggered this event.
1443	* For pointer events that are not of type @ref
1444	* LIBINPUT_EVENT_POINTER_BUTTON, this function returns 0.
1445	*
1446	* @note It is an application bug to call this function for events other than
1447	* @ref LIBINPUT_EVENT_POINTER_BUTTON.
1448	*
1449	* @return The button triggering this event
1450	*/
1451	uint32_t
1452	libinput_event_pointer_get_button(struct libinput_event_pointer *event);
1453
1454	/**
1455	* @ingroup event_pointer
1456	*
1457	* Return the button state that triggered this event.
1458	* For pointer events that are not of type @ref
1459	* LIBINPUT_EVENT_POINTER_BUTTON, this function returns 0.
1460	*
1461	* @note It is an application bug to call this function for events other than
1462	* @ref LIBINPUT_EVENT_POINTER_BUTTON.
1463	*
1464	* @return The button state triggering this event
1465	*/
1466	enum libinput_button_state
1467	libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
1468
1469	/**
1470	* @ingroup event_pointer
1471	*
1472	* For the button of a @ref LIBINPUT_EVENT_POINTER_BUTTON event, return the
1473	* total number of buttons pressed on all devices on the associated seat
1474	* after the event was triggered.
1475	*
1476	* @note It is an application bug to call this function for events other than
1477	* @ref LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function
1478	* returns 0.
1479	*
1480	* @return The seat wide pressed button count for the key of this event
1481	*/
1482	uint32_t
1483	libinput_event_pointer_get_seat_button_count(
1484	struct libinput_event_pointer *event);
1485
1486	/**
1487	* @ingroup event_pointer
1488	*
1489	* Check if the event has a valid value for the given axis.
1490	*
1491	* If this function returns non-zero for an axis and
1492	* libinput_event_pointer_get_axis_value() returns a value of 0, the event
1493	* is a scroll stop event.
1494	*
1495	* For pointer events that are not of type @ref LIBINPUT_EVENT_POINTER_AXIS,
1496	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, @ref
1497	* LIBINPUT_EVENT_POINTER_SCROLL_FINGER, or @ref
1498	* LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS this function returns 0.
1499	*
1500	* @note It is an application bug to call this function for events other than
1501	* @ref LIBINPUT_EVENT_POINTER_AXIS,
1502	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
1503	* @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, or
1504	* @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS.
1505	*
1506	* @return Non-zero if this event contains a value for this axis
1507	*/
1508	int
1509	libinput_event_pointer_has_axis(struct libinput_event_pointer *event,
1510	enum libinput_pointer_axis axis);
1511
1512	/**
1513	* @ingroup event_pointer
1514	*
1515	* Return the axis value of the given axis. The interpretation of the value
1516	* depends on the axis. For the two scrolling axes
1517	* @ref LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
1518	* @ref LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in
1519	* relative scroll units, with the positive direction being down or right,
1520	* respectively. For the interpretation of the value, see
1521	* libinput_event_pointer_get_axis_source().
1522	*
1523	* If libinput_event_pointer_has_axis() returns 0 for an axis, this function
1524	* returns 0 for that axis.
1525	*
1526	* For pointer events that are not of type @ref LIBINPUT_EVENT_POINTER_AXIS,
1527	* this function returns 0.
1528	*
1529	* @note It is an application bug to call this function for events other than
1530	* @ref LIBINPUT_EVENT_POINTER_AXIS.
1531	*
1532	* @return The axis value of this event
1533	*
1534	* @see libinput_event_pointer_get_axis_value_discrete
1535	*/
1536	double
1537	libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event,
1538	enum libinput_pointer_axis axis);
1539
1540	/**
1541	* @ingroup event_pointer
1542	*
1543	* Return the source for a given axis event. Axis events (scroll events) can
1544	* be caused by a hardware item such as a scroll wheel or emulated from
1545	* other input sources, such as two-finger or edge scrolling on a
1546	* touchpad.
1547	*
1548	* If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_FINGER, libinput
1549	* guarantees that a scroll sequence is terminated with a scroll value of 0.
1550	* A caller may use this information to decide on whether kinetic scrolling
1551	* should be triggered on this scroll sequence.
1552	* The coordinate system is identical to the cursor movement, i.e. a
1553	* scroll value of 1 represents the equivalent relative motion of 1.
1554	*
1555	* If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_WHEEL, no terminating
1556	* event is guaranteed (though it may happen).
1557	* Scrolling is in discrete steps, the value is the angle the wheel moved
1558	* in degrees. The default is 15 degrees per wheel click, but some mice may
1559	* have differently grained wheels. It is up to the caller how to interpret
1560	* such different step sizes. Callers should use
1561	* libinput_event_pointer_get_scroll_value_v120() for a simpler API of
1562	* handling scroll wheel events of different step sizes.
1563	*
1564	* If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS, libinput
1565	* guarantees that a scroll sequence is terminated with a scroll value of 0.
1566	* The coordinate system is identical to the cursor movement, i.e. a
1567	* scroll value of 1 represents the equivalent relative motion of 1.
1568	*
1569	* @deprecated The source @ref LIBINPUT_POINTER_AXIS_SOURCE_WHEEL_TILT is
1570	* deprecated as of libinput 1.16. No device has ever sent this source.
1571	*
1572	* For pointer events that are not of type @ref LIBINPUT_EVENT_POINTER_AXIS,
1573	* this function returns 0.
1574	*
1575	* @note It is an application bug to call this function for events other than
1576	* @ref LIBINPUT_EVENT_POINTER_AXIS.
1577	*
1578	* @note This function is superfluous as of libinput 1.19. The event
1579	* codes for @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, @ref
1580	* LIBINPUT_EVENT_POINTER_SCROLL_FINGER and @ref
1581	* LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS have the axis source encoded in
1582	* the event type.
1583	*
1584	* @return The source for this axis event
1585	*/
1586	enum libinput_pointer_axis_source
1587	libinput_event_pointer_get_axis_source(struct libinput_event_pointer *event);
1588
1589	/**
1590	* @ingroup event_pointer
1591	*
1592	* Return the axis value in discrete steps for a given axis event. How a
1593	* value translates into a discrete step depends on the source.
1594	*
1595	* @note This function does not support high-resolution mouse wheels and
1596	* should be considered deprecated as of libinput 1.19. Callers should use
1597	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL and
1598	* libinput_event_pointer_get_scroll_value_v120() instead.
1599	*
1600	* If the event is not of type @ref LIBINPUT_EVENT_POINTER_AXIS, this
1601	* function returns 0.
1602	*
1603	* If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_WHEEL, the discrete
1604	* value correspond to the number of physical mouse wheel clicks.
1605	*
1606	* If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS or @ref
1607	* LIBINPUT_POINTER_AXIS_SOURCE_FINGER, the discrete value is always 0.
1608	*
1609	* @return The discrete value for the given event.
1610	*
1611	* @see libinput_event_pointer_get_axis_value
1612	* @see libinput_event_pointer_get_scroll_value_v120
1613	*/
1614	double
1615	libinput_event_pointer_get_axis_value_discrete(struct libinput_event_pointer *event,
1616	enum libinput_pointer_axis axis);
1617
1618	/**
1619	* @ingroup event_pointer
1620	*
1621	* Return the axis value of the given axis. The interpretation of the value
1622	* depends on the axis. For the two scrolling axes
1623	* @ref LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
1624	* @ref LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in
1625	* relative scroll units, with the positive direction being down or right,
1626	* respectively. If libinput_event_pointer_has_axis() returns 0 for an axis,
1627	* this function returns 0 for that axis.
1628	*
1629	* If the event is @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, libinput
1630	* guarantees that a scroll sequence is terminated with a scroll value of 0.
1631	* A caller may use this information to decide on whether kinetic scrolling
1632	* should be triggered on this scroll sequence.
1633	* The coordinate system is identical to the cursor movement, i.e. a
1634	* scroll value of 1 represents the equivalent relative motion of 1.
1635	*
1636	* If the event is @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, no terminating
1637	* event is guaranteed (though it may happen).
1638	* Scrolling is in discrete steps, the value is the angle the wheel moved
1639	* in degrees. The default is 15 degrees per wheel click, but some mice may
1640	* have differently grained wheels. It is up to the caller how to interpret
1641	* such different step sizes. Callers should use
1642	* libinput_event_pointer_get_scroll_value_v120() for a simpler API of
1643	* handling scroll wheel events of different step sizes.
1644	*
1645	* If the event is @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS, libinput
1646	* guarantees that a scroll sequence is terminated with a scroll value of 0.
1647	* The coordinate system is identical to the cursor movement, i.e. a
1648	* scroll value of 1 represents the equivalent relative motion of 1.
1649	*
1650	* For pointer events that are not of type
1651	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
1652	* @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, or
1653	* @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS, this function returns zero.
1654	*
1655	* @note It is an application bug to call this function for events other than
1656	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL,
1657	* @ref LIBINPUT_EVENT_POINTER_SCROLL_FINGER, or
1658	* @ref LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS.
1659	*
1660	* @return The axis value of this event
1661	*
1662	* @see libinput_event_pointer_get_scroll_value_v120
1663	*
1664	* @since 1.19
1665	*/
1666	double
1667	libinput_event_pointer_get_scroll_value(struct libinput_event_pointer *event,
1668	enum libinput_pointer_axis axis);
1669
1670	/**
1671	* @ingroup event_pointer
1672	*
1673	* For events of type @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL
1674	* the v120-normalized value represents the movement in logical mouse wheel
1675	* clicks, normalized to the -120..+120 range.
1676	*
1677	* A value that is a fraction of ±120 indicates a wheel movement less than
1678	* one logical click, a caller should either scroll by the respective
1679	* fraction of the normal scroll distance or accumulate that value until a
1680	* multiple of 120 is reached.
1681	*
1682	* For most callers, this is the preferred way of handling high-resolution
1683	* scroll events.
1684	*
1685	* The normalized v120 value does not take device-specific physical angles
1686	* or distances into account, i.e. a wheel with a click angle of 20 degrees
1687	* produces only 18 logical clicks per 360 degree rotation, a wheel with a
1688	* click angle of 15 degrees produces 24 logical clicks per 360 degree
1689	* rotation. Where the physical angle matters, use
1690	* libinput_event_pointer_get_axis_value() instead.
1691	*
1692	* The magic number 120 originates from the <a
1693	* href="http://download.microsoft.com/download/b/d/1/bd1f7ef4-7d72-419e-bc5c-9f79ad7bb66e/wheel.docx">
1694	* Windows Vista Mouse Wheel design document</a>.
1695	*
1696	* @note It is an application bug to call this function for events other than
1697	* @ref LIBINPUT_EVENT_POINTER_SCROLL_WHEEL.
1698	*
1699	* @return A value normalized to the 0-±120 range
1700	*
1701	* @see libinput_event_pointer_get_axis_value
1702	* @see libinput_event_pointer_get_axis_value_discrete
1703	*
1704	* @since 1.19
1705	*/
1706	double
1707	libinput_event_pointer_get_scroll_value_v120(struct libinput_event_pointer *event,
1708	enum libinput_pointer_axis axis);
1709
1710	/**
1711	* @ingroup event_pointer
1712	*
1713	* @return The generic libinput_event of this event
1714	*/
1715	struct libinput_event *
1716	libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
1717
1718	/**
1719	* @defgroup event_touch Touch events
1720	*
1721	* Events from absolute touch devices.
1722	*/
1723
1724	/**
1725	* @ingroup event_touch
1726	*
1727	* @note Timestamps may not always increase. See the libinput documentation
1728	* for more details.
1729	*
1730	* @return The event time for this event
1731	*/
1732	uint32_t
1733	libinput_event_touch_get_time(struct libinput_event_touch *event);
1734
1735	/**
1736	* @ingroup event_touch
1737	*
1738	* @note Timestamps may not always increase. See the libinput documentation
1739	* for more details.
1740	*
1741	* @return The event time for this event in microseconds
1742	*/
1743	uint64_t
1744	libinput_event_touch_get_time_usec(struct libinput_event_touch *event);
1745
1746	/**
1747	* @ingroup event_touch
1748	*
1749	* Get the slot of this touch event. See the kernel's multitouch
1750	* protocol B documentation for more information.
1751	*
1752	* If the touch event has no assigned slot, for example if it is from a
1753	* single touch device, this function returns -1.
1754	*
1755	* For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref
1756	* LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_MOTION or @ref
1757	* LIBINPUT_EVENT_TOUCH_CANCEL, this function returns 0.
1758	*
1759	* @note It is an application bug to call this function for events of type
1760	* other than @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_UP,
1761	* @ref LIBINPUT_EVENT_TOUCH_MOTION or @ref LIBINPUT_EVENT_TOUCH_CANCEL.
1762	*
1763	* @return The slot of this touch event
1764	*/
1765	int32_t
1766	libinput_event_touch_get_slot(struct libinput_event_touch *event);
1767
1768	/**
1769	* @ingroup event_touch
1770	*
1771	* Get the seat slot of the touch event. A seat slot is a non-negative seat
1772	* wide unique identifier of an active touch point.
1773	*
1774	* Events from single touch devices will be represented as one individual
1775	* touch point per device.
1776	*
1777	* For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref
1778	* LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_MOTION or @ref
1779	* LIBINPUT_EVENT_TOUCH_CANCEL, this function returns 0.
1780	*
1781	* @note It is an application bug to call this function for events of type
1782	* other than @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_UP,
1783	* @ref LIBINPUT_EVENT_TOUCH_MOTION or @ref LIBINPUT_EVENT_TOUCH_CANCEL.
1784	*
1785	* @return The seat slot of the touch event
1786	*/
1787	int32_t
1788	libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
1789
1790	/**
1791	* @ingroup event_touch
1792	*
1793	* Return the current absolute x coordinate of the touch event, in mm from
1794	* the top left corner of the device. To get the corresponding output screen
1795	* coordinate, use libinput_event_touch_get_x_transformed().
1796	*
1797	* For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref
1798	* LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0.
1799	*
1800	* @note It is an application bug to call this function for events of type
1801	* other than @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref
1802	* LIBINPUT_EVENT_TOUCH_MOTION.
1803	*
1804	* @param event The libinput touch event
1805	* @return The current absolute x coordinate
1806	*/
1807	double
1808	libinput_event_touch_get_x(struct libinput_event_touch *event);
1809
1810	/**
1811	* @ingroup event_touch
1812	*
1813	* Return the current absolute y coordinate of the touch event, in mm from
1814	* the top left corner of the device. To get the corresponding output screen
1815	* coordinate, use libinput_event_touch_get_y_transformed().
1816	*
1817	* For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref
1818	* LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0.
1819	*
1820	* @note It is an application bug to call this function for events of type
1821	* other than @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref
1822	* LIBINPUT_EVENT_TOUCH_MOTION.
1823	*
1824	* @param event The libinput touch event
1825	* @return The current absolute y coordinate
1826	*/
1827	double
1828	libinput_event_touch_get_y(struct libinput_event_touch *event);
1829
1830	/**
1831	* @ingroup event_touch
1832	*
1833	* Return the current absolute x coordinate of the touch event, transformed to
1834	* screen coordinates.
1835	*
1836	* For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref
1837	* LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0.
1838	*
1839	* @note It is an application bug to call this function for events of type
1840	* other than @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref
1841	* LIBINPUT_EVENT_TOUCH_MOTION.
1842	*
1843	* @param event The libinput touch event
1844	* @param width The current output screen width
1845	* @return The current absolute x coordinate transformed to a screen coordinate
1846	*/
1847	double
1848	libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
1849	uint32_t width);
1850
1851	/**
1852	* @ingroup event_touch
1853	*
1854	* Return the current absolute y coordinate of the touch event, transformed to
1855	* screen coordinates.
1856	*
1857	* For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref
1858	* LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0.
1859	*
1860	* @note It is an application bug to call this function for events of type
1861	* other than @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref
1862	* LIBINPUT_EVENT_TOUCH_MOTION.
1863	*
1864	* @param event The libinput touch event
1865	* @param height The current output screen height
1866	* @return The current absolute y coordinate transformed to a screen coordinate
1867	*/
1868	double
1869	libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
1870	uint32_t height);
1871
1872	/**
1873	* @ingroup event_touch
1874	*
1875	* @return The generic libinput_event of this event
1876	*/
1877	struct libinput_event *
1878	libinput_event_touch_get_base_event(struct libinput_event_touch *event);
1879
1880	/**
1881	* @defgroup event_gesture Gesture events
1882	*
1883	* Gesture events are generated when a gesture is recognized on a touchpad.
1884	*
1885	* Gesture sequences always start with a LIBINPUT_EVENT_GESTURE_FOO_START
1886	* event. All following gesture events will be of the
1887	* LIBINPUT_EVENT_GESTURE_FOO_UPDATE type until a
1888	* LIBINPUT_EVENT_GESTURE_FOO_END is generated which signals the end of the
1889	* gesture.
1890	*
1891	* See the libinput documentation for details on gesture handling.
1892	*/
1893
1894	/**
1895	* @ingroup event_gesture
1896	*
1897	* @note Timestamps may not always increase. See the libinput documentation
1898	* for more details.
1899	*
1900	* @return The event time for this event
1901	*/
1902	uint32_t
1903	libinput_event_gesture_get_time(struct libinput_event_gesture *event);
1904
1905	/**
1906	* @ingroup event_gesture
1907	*
1908	* @note Timestamps may not always increase. See the libinput documentation
1909	* for more details.
1910	*
1911	* @return The event time for this event in microseconds
1912	*/
1913	uint64_t
1914	libinput_event_gesture_get_time_usec(struct libinput_event_gesture *event);
1915
1916	/**
1917	* @ingroup event_gesture
1918	*
1919	* @return The generic libinput_event of this event
1920	*/
1921	struct libinput_event *
1922	libinput_event_gesture_get_base_event(struct libinput_event_gesture *event);
1923
1924	/**
1925	* @ingroup event_gesture
1926	*
1927	* Return the number of fingers used for a gesture. This can be used e.g.
1928	* to differentiate between 3 or 4 finger swipes.
1929	*
1930	* This function can be called on all gesture events and the returned finger
1931	* count value remains the same for the lifetime of a gesture. Thus, if a
1932	* user puts down a fourth finger during a three-finger swipe gesture,
1933	* libinput will end the three-finger gesture and, if applicable, start a
1934	* four-finger swipe gesture. A caller may decide that those gestures are
1935	* semantically identical and continue the two gestures as one single gesture.
1936	*
1937	* @return the number of fingers used for a gesture
1938	*/
1939	int
1940	libinput_event_gesture_get_finger_count(struct libinput_event_gesture *event);
1941
1942	/**
1943	* @ingroup event_gesture
1944	*
1945	* Return if the gesture ended normally, or if it was cancelled.
1946	* For gesture events that are not of type
1947	* @ref LIBINPUT_EVENT_GESTURE_SWIPE_END or
1948	* @ref LIBINPUT_EVENT_GESTURE_PINCH_END, this function returns 0.
1949	*
1950	* @note It is an application bug to call this function for events other than
1951	* @ref LIBINPUT_EVENT_GESTURE_SWIPE_END or
1952	* @ref LIBINPUT_EVENT_GESTURE_PINCH_END.
1953	*
1954	* @return 0 or 1, with 1 indicating that the gesture was cancelled.
1955	*/
1956	int
1957	libinput_event_gesture_get_cancelled(struct libinput_event_gesture *event);
1958
1959	/**
1960	* @ingroup event_gesture
1961	*
1962	* Return the delta between the last event and the current event. For gesture
1963	* events that are not of type @ref LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE or
1964	* @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this function returns 0.
1965	*
1966	* If a device employs pointer acceleration, the delta returned by this
1967	* function is the accelerated delta.
1968	*
1969	* Relative motion deltas are normalized to represent those of a device with
1970	* 1000dpi resolution. See the libinput documentation for more details.
1971	*
1972	* @return the relative x movement since the last event
1973	*/
1974	double
1975	libinput_event_gesture_get_dx(struct libinput_event_gesture *event);
1976
1977	/**
1978	* @ingroup event_gesture
1979	*
1980	* Return the delta between the last event and the current event. For gesture
1981	* events that are not of type @ref LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE or
1982	* @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this function returns 0.
1983	*
1984	* If a device employs pointer acceleration, the delta returned by this
1985	* function is the accelerated delta.
1986	*
1987	* Relative motion deltas are normalized to represent those of a device with
1988	* 1000dpi resolution. See the libinput documentation for more details.
1989	*
1990	* @return the relative y movement since the last event
1991	*/
1992	double
1993	libinput_event_gesture_get_dy(struct libinput_event_gesture *event);
1994
1995	/**
1996	* @ingroup event_gesture
1997	*
1998	* Return the relative delta of the unaccelerated motion vector of the
1999	* current event. For gesture events that are not of type
2000	* @ref LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE or
2001	* @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this function returns 0.
2002	*
2003	* Relative unaccelerated motion deltas are normalized to represent those of a
2004	* device with 1000dpi resolution. See the libinput documentation for more
2005	* details. Note that unaccelerated events are not equivalent to 'raw' events
2006	* as read from the device.
2007	*
2008	* Any rotation applied to the device also applies to gesture motion
2009	* (see libinput_device_config_rotation_set_angle()).
2010	*
2011	* @return the unaccelerated relative x movement since the last event
2012	*/
2013	double
2014	libinput_event_gesture_get_dx_unaccelerated(
2015	struct libinput_event_gesture *event);
2016
2017	/**
2018	* @ingroup event_gesture
2019	*
2020	* Return the relative delta of the unaccelerated motion vector of the
2021	* current event. For gesture events that are not of type
2022	* @ref LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE or
2023	* @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this function returns 0.
2024	*
2025	* Relative unaccelerated motion deltas are normalized to represent those of a
2026	* device with 1000dpi resolution. See the libinput documentation for more
2027	* details. Note that unaccelerated events are not equivalent to 'raw' events
2028	* as read from the device.
2029	*
2030	* Any rotation applied to the device also applies to gesture motion
2031	* (see libinput_device_config_rotation_set_angle()).
2032	*
2033	* @return the unaccelerated relative y movement since the last event
2034	*/
2035	double
2036	libinput_event_gesture_get_dy_unaccelerated(
2037	struct libinput_event_gesture *event);
2038
2039	/**
2040	* @ingroup event_gesture
2041	*
2042	* Return the absolute scale of a pinch gesture, the scale is the division
2043	* of the current distance between the fingers and the distance at the start
2044	* of the gesture. The scale begins at 1.0, and if e.g. the fingers moved
2045	* together by 50% then the scale will become 0.5, if they move twice as far
2046	* apart as initially the scale becomes 2.0, etc.
2047	*
2048	* For gesture events that are of type @ref
2049	* LIBINPUT_EVENT_GESTURE_PINCH_BEGIN, this function returns 1.0.
2050	*
2051	* For gesture events that are of type @ref
2052	* LIBINPUT_EVENT_GESTURE_PINCH_END, this function returns the scale value
2053	* of the most recent @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE event (if
2054	* any) or 1.0 otherwise.
2055	*
2056	* For all other events this function returns 0.
2057	*
2058	* @note It is an application bug to call this function for events other than
2059	* @ref LIBINPUT_EVENT_GESTURE_PINCH_BEGIN, @ref
2060	* LIBINPUT_EVENT_GESTURE_PINCH_END or
2061	* @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE.
2062	*
2063	* @return the absolute scale of a pinch gesture
2064	*/
2065	double
2066	libinput_event_gesture_get_scale(struct libinput_event_gesture *event);
2067
2068	/**
2069	* @ingroup event_gesture
2070	*
2071	* Return the angle delta in degrees between the last and the current @ref
2072	* LIBINPUT_EVENT_GESTURE_PINCH_UPDATE event. For gesture events that
2073	* are not of type @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this
2074	* function returns 0.
2075	*
2076	* The angle delta is defined as the change in angle of the line formed by
2077	* the 2 fingers of a pinch gesture. Clockwise rotation is represented
2078	* by a positive delta, counter-clockwise by a negative delta. If e.g. the
2079	* fingers are on the 12 and 6 location of a clock face plate and they move
2080	* to the 1 resp. 7 location in a single event then the angle delta is
2081	* 30 degrees.
2082	*
2083	* If more than two fingers are present, the angle represents the rotation
2084	* around the center of gravity. The calculation of the center of gravity is
2085	* implementation-dependent.
2086	*
2087	* @return the angle delta since the last event
2088	*/
2089	double
2090	libinput_event_gesture_get_angle_delta(struct libinput_event_gesture *event);
2091
2092	/**
2093	* @defgroup event_tablet Tablet events
2094	*
2095	* Events that come from tools on tablet devices. For events from the pad,
2096	* see @ref event_tablet_pad.
2097	*
2098	* Events from tablet devices are exposed by two interfaces, tools and pads.
2099	* Tool events originate (usually) from a stylus-like device, pad events
2100	* reflect any events originating from the physical tablet itself.
2101	*
2102	* Note that many tablets support touch events. These are exposed through
2103	* the @ref LIBINPUT_DEVICE_CAP_POINTER interface (for external touchpad-like
2104	* devices such as the Wacom Intuos series) or @ref
2105	* LIBINPUT_DEVICE_CAP_TOUCH interface (for built-in touchscreen-like
2106	* devices such as the Wacom Cintiq series).
2107	*/
2108
2109	/**
2110	* @ingroup event_tablet
2111	*
2112	* @return The generic libinput_event of this event
2113	*
2114	* @since 1.2
2115	*/
2116	struct libinput_event *
2117	libinput_event_tablet_tool_get_base_event(struct libinput_event_tablet_tool *event);
2118
2119	/**
2120	* @ingroup event_tablet
2121	*
2122	* Check if the x axis was updated in this event.
2123	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2124	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2125	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2126	*
2127	* @note It is an application bug to call this function for events other
2128	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2129	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2130	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2131	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2132	*
2133	* @param event The libinput tablet tool event
2134	* @return 1 if the axis was updated or 0 otherwise
2135	*
2136	* @since 1.2
2137	*/
2138	int
2139	libinput_event_tablet_tool_x_has_changed(
2140	struct libinput_event_tablet_tool *event);
2141
2142	/**
2143	* @ingroup event_tablet
2144	*
2145	* Check if the y axis was updated in this event.
2146	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2147	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2148	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2149	*
2150	* @note It is an application bug to call this function for events other
2151	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2152	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2153	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2154	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2155	*
2156	* @param event The libinput tablet tool event
2157	* @return 1 if the axis was updated or 0 otherwise
2158	*
2159	* @since 1.2
2160	*/
2161	int
2162	libinput_event_tablet_tool_y_has_changed(
2163	struct libinput_event_tablet_tool *event);
2164
2165	/**
2166	* @ingroup event_tablet
2167	*
2168	* Check if the pressure axis was updated in this event.
2169	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2170	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2171	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2172	*
2173	* @note It is an application bug to call this function for events other
2174	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2175	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2176	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2177	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2178	*
2179	* @param event The libinput tablet tool event
2180	* @return 1 if the axis was updated or 0 otherwise
2181	*
2182	* @since 1.2
2183	*/
2184	int
2185	libinput_event_tablet_tool_pressure_has_changed(
2186	struct libinput_event_tablet_tool *event);
2187
2188	/**
2189	* @ingroup event_tablet
2190	*
2191	* Check if the distance axis was updated in this event.
2192	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2193	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2194	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2195	* For tablet tool events of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY,
2196	* this function always returns 1.
2197	*
2198	* @note It is an application bug to call this function for events other
2199	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2200	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2201	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2202	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2203	*
2204	* @param event The libinput tablet tool event
2205	* @return 1 if the axis was updated or 0 otherwise
2206	*
2207	* @since 1.2
2208	*/
2209	int
2210	libinput_event_tablet_tool_distance_has_changed(
2211	struct libinput_event_tablet_tool *event);
2212
2213	/**
2214	* @ingroup event_tablet
2215	*
2216	* Check if the tilt x axis was updated in this event.
2217	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2218	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2219	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2220	*
2221	* @note It is an application bug to call this function for events other
2222	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2223	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2224	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2225	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2226	*
2227	* @param event The libinput tablet tool event
2228	* @return 1 if the axis was updated or 0 otherwise
2229	*
2230	* @since 1.2
2231	*/
2232	int
2233	libinput_event_tablet_tool_tilt_x_has_changed(
2234	struct libinput_event_tablet_tool *event);
2235
2236	/**
2237	* @ingroup event_tablet
2238	*
2239	* Check if the tilt y axis was updated in this event.
2240	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2241	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2242	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2243	*
2244	* @note It is an application bug to call this function for events other
2245	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2246	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2247	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2248	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2249	*
2250	* @param event The libinput tablet tool event
2251	* @return 1 if the axis was updated or 0 otherwise
2252	*
2253	* @since 1.2
2254	*/
2255	int
2256	libinput_event_tablet_tool_tilt_y_has_changed(
2257	struct libinput_event_tablet_tool *event);
2258	/**
2259	* @ingroup event_tablet
2260	*
2261	* Check if the z-rotation axis was updated in this event.
2262	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2263	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2264	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2265	*
2266	* @note It is an application bug to call this function for events other
2267	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2268	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2269	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2270	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2271	*
2272	* @param event The libinput tablet tool event
2273	* @return 1 if the axis was updated or 0 otherwise
2274	*
2275	* @since 1.2
2276	*/
2277	int
2278	libinput_event_tablet_tool_rotation_has_changed(
2279	struct libinput_event_tablet_tool *event);
2280	/**
2281	* @ingroup event_tablet
2282	*
2283	* Check if the slider axis was updated in this event.
2284	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2285	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2286	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2287	*
2288	* @note It is an application bug to call this function for events other
2289	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2290	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2291	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2292	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2293	*
2294	* @param event The libinput tablet tool event
2295	* @return 1 if the axis was updated or 0 otherwise
2296	*
2297	* @since 1.2
2298	*/
2299	int
2300	libinput_event_tablet_tool_slider_has_changed(
2301	struct libinput_event_tablet_tool *event);
2302
2303	/**
2304	* @ingroup event_tablet
2305	*
2306	* Check if the size major axis was updated in this event.
2307	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2308	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2309	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2310	*
2311	* @note It is an application bug to call this function for events other
2312	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2313	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2314	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2315	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2316	*
2317	* @param event The libinput tablet tool event
2318	* @return 1 if the axis was updated or 0 otherwise
2319	*/
2320	int
2321	libinput_event_tablet_tool_size_major_has_changed(
2322	struct libinput_event_tablet_tool *event);
2323
2324	/**
2325	* @ingroup event_tablet
2326	*
2327	* Check if the size minor axis was updated in this event.
2328	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2329	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2330	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2331	*
2332	* @note It is an application bug to call this function for events other
2333	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2334	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2335	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2336	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2337	*
2338	* @param event The libinput tablet tool event
2339	* @return 1 if the axis was updated or 0 otherwise
2340	*/
2341	int
2342	libinput_event_tablet_tool_size_minor_has_changed(
2343	struct libinput_event_tablet_tool *event);
2344
2345	/**
2346	* @ingroup event_tablet
2347	*
2348	* Check if the wheel axis was updated in this event.
2349	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS,
2350	* @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or
2351	* @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0.
2352	*
2353	* @note It is an application bug to call this function for events other
2354	* than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
2355	* LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref
2356	* LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref
2357	* LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2358	*
2359	* @param event The libinput tablet tool event
2360	* @return 1 if the axis was updated or 0 otherwise
2361	*
2362	* @since 1.2
2363	*/
2364	int
2365	libinput_event_tablet_tool_wheel_has_changed(
2366	struct libinput_event_tablet_tool *event);
2367
2368	/**
2369	* @ingroup event_tablet
2370	*
2371	* Returns the X coordinate of the tablet tool, in mm from the top left
2372	* corner of the tablet in its current logical orientation. Use
2373	* libinput_event_tablet_tool_get_x_transformed() for transforming the axis
2374	* value into a different coordinate space.
2375	*
2376	* @note On some devices, returned value may be negative or larger than the
2377	* width of the device. See the libinput documentation for more details.
2378	*
2379	* @param event The libinput tablet tool event
2380	* @return The current value of the the axis
2381	*
2382	* @since 1.2
2383	*/
2384	double
2385	libinput_event_tablet_tool_get_x(struct libinput_event_tablet_tool *event);
2386
2387	/**
2388	* @ingroup event_tablet
2389	*
2390	* Returns the Y coordinate of the tablet tool, in mm from the top left
2391	* corner of the tablet in its current logical orientation. Use
2392	* libinput_event_tablet_tool_get_y_transformed() for transforming the axis
2393	* value into a different coordinate space.
2394	*
2395	* @note On some devices, returned value may be negative or larger than the
2396	* width of the device. See the libinput documentation for more details.
2397	*
2398	* @param event The libinput tablet tool event
2399	* @return The current value of the the axis
2400	*
2401	* @since 1.2
2402	*/
2403	double
2404	libinput_event_tablet_tool_get_y(struct libinput_event_tablet_tool *event);
2405
2406	/**
2407	* @ingroup event_tablet
2408	*
2409	* Return the delta between the last event and the current event.
2410	* If the tool employs pointer acceleration, the delta returned by this
2411	* function is the accelerated delta.
2412	*
2413	* This value is in screen coordinate space, the delta is to be interpreted
2414	* like the return value of libinput_event_pointer_get_dx().
2415	* See the libinput documentation for more details.
2416	*
2417	* @param event The libinput tablet event
2418	* @return The relative x movement since the last event
2419	*
2420	* @since 1.2
2421	*/
2422	double
2423	libinput_event_tablet_tool_get_dx(struct libinput_event_tablet_tool *event);
2424
2425	/**
2426	* @ingroup event_tablet
2427	*
2428	* Return the delta between the last event and the current event.
2429	* If the tool employs pointer acceleration, the delta returned by this
2430	* function is the accelerated delta.
2431	*
2432	* This value is in screen coordinate space, the delta is to be interpreted
2433	* like the return value of libinput_event_pointer_get_dx().
2434	* See the libinput documentation for more details.
2435	*
2436	* @param event The libinput tablet event
2437	* @return The relative y movement since the last event
2438	*
2439	* @since 1.2
2440	*/
2441	double
2442	libinput_event_tablet_tool_get_dy(struct libinput_event_tablet_tool *event);
2443
2444	/**
2445	* @ingroup event_tablet
2446	*
2447	* Returns the current pressure being applied on the tool in use, normalized
2448	* to the range [0, 1].
2449	*
2450	* If this axis does not exist on the current tool, this function returns 0.
2451	*
2452	* @param event The libinput tablet tool event
2453	* @return The current value of the the axis
2454	*
2455	* @since 1.2
2456	*/
2457	double
2458	libinput_event_tablet_tool_get_pressure(struct libinput_event_tablet_tool *event);
2459
2460	/**
2461	* @ingroup event_tablet
2462	*
2463	* Returns the current distance from the tablet's sensor, normalized to the
2464	* range [0, 1].
2465	*
2466	* If this axis does not exist on the current tool, this function returns 0.
2467	*
2468	* @param event The libinput tablet tool event
2469	* @return The current value of the the axis
2470	*
2471	* @since 1.2
2472	*/
2473	double
2474	libinput_event_tablet_tool_get_distance(struct libinput_event_tablet_tool *event);
2475
2476	/**
2477	* @ingroup event_tablet
2478	*
2479	* Returns the current tilt along the X axis of the tablet's current logical
2480	* orientation, in degrees off the tablet's z axis. That is, if the tool is
2481	* perfectly orthogonal to the tablet, the tilt angle is 0. When the top
2482	* tilts towards the logical top/left of the tablet, the x/y tilt angles are
2483	* negative, if the top tilts towards the logical bottom/right of the
2484	* tablet, the x/y tilt angles are positive.
2485	*
2486	* If this axis does not exist on the current tool, this function returns 0.
2487	*
2488	* @param event The libinput tablet tool event
2489	* @return The current value of the axis in degrees
2490	*
2491	* @since 1.2
2492	*/
2493	double
2494	libinput_event_tablet_tool_get_tilt_x(struct libinput_event_tablet_tool *event);
2495
2496	/**
2497	* @ingroup event_tablet
2498	*
2499	* Returns the current tilt along the Y axis of the tablet's current logical
2500	* orientation, in degrees off the tablet's z axis. That is, if the tool is
2501	* perfectly orthogonal to the tablet, the tilt angle is 0. When the top
2502	* tilts towards the logical top/left of the tablet, the x/y tilt angles are
2503	* negative, if the top tilts towards the logical bottom/right of the
2504	* tablet, the x/y tilt angles are positive.
2505	*
2506	* If this axis does not exist on the current tool, this function returns 0.
2507	*
2508	* @param event The libinput tablet tool event
2509	* @return The current value of the the axis in degrees
2510	*
2511	* @since 1.2
2512	*/
2513	double
2514	libinput_event_tablet_tool_get_tilt_y(struct libinput_event_tablet_tool *event);
2515
2516	/**
2517	* @ingroup event_tablet
2518	*
2519	* Returns the current z rotation of the tool in degrees, clockwise from the
2520	* tool's logical neutral position.
2521	*
2522	* For tools of type @ref LIBINPUT_TABLET_TOOL_TYPE_MOUSE and @ref
2523	* LIBINPUT_TABLET_TOOL_TYPE_LENS the logical neutral position is
2524	* pointing to the current logical north of the tablet. For tools of type @ref
2525	* LIBINPUT_TABLET_TOOL_TYPE_BRUSH, the logical neutral position is with the
2526	* buttons pointing up.
2527	*
2528	* If this axis does not exist on the current tool, this function returns 0.
2529	*
2530	* @param event The libinput tablet tool event
2531	* @return The current value of the the axis
2532	*
2533	* @since 1.2
2534	*/
2535	double
2536	libinput_event_tablet_tool_get_rotation(struct libinput_event_tablet_tool *event);
2537
2538	/**
2539	* @ingroup event_tablet
2540	*
2541	* Returns the current position of the slider on the tool, normalized to the
2542	* range [-1, 1]. The logical zero is the neutral position of the slider, or
2543	* the logical center of the axis. This axis is available on e.g. the Wacom
2544	* Airbrush.
2545	*
2546	* If this axis does not exist on the current tool, this function returns 0.
2547	*
2548	* @param event The libinput tablet tool event
2549	* @return The current value of the the axis
2550	*
2551	* @since 1.2
2552	*/
2553	double
2554	libinput_event_tablet_tool_get_slider_position(struct libinput_event_tablet_tool *event);
2555
2556	/**
2557	* @ingroup event_tablet
2558	*
2559	* Returns the current size in mm along the major axis of the touching
2560	* ellipse. This axis is not necessarily aligned with either x or y, the
2561	* rotation must be taken into account.
2562	*
2563	* Where no rotation is available on a tool, or where rotation is zero, the
2564	* major axis aligns with the y axis and the minor axis with the x axis.
2565	*
2566	* If this axis does not exist on the current tool, this function returns 0.
2567	*
2568	* @param event The libinput tablet tool event
2569	* @return The current value of the axis major in mm
2570	*/
2571	double
2572	libinput_event_tablet_tool_get_size_major(struct libinput_event_tablet_tool *event);
2573
2574	/**
2575	* @ingroup event_tablet
2576	*
2577	* Returns the current size in mm along the minor axis of the touching
2578	* ellipse. This axis is not necessarily aligned with either x or y, the
2579	* rotation must be taken into account.
2580	*
2581	* Where no rotation is available on a tool, or where rotation is zero, the
2582	* minor axis aligns with the y axis and the minor axis with the x axis.
2583	*
2584	* If this axis does not exist on the current tool, this function returns 0.
2585	*
2586	* @param event The libinput tablet tool event
2587	* @return The current value of the axis minor in mm
2588	*/
2589	double
2590	libinput_event_tablet_tool_get_size_minor(struct libinput_event_tablet_tool *event);
2591
2592	/**
2593	* @ingroup event_tablet
2594	*
2595	* Return the delta for the wheel in degrees.
2596	*
2597	* @param event The libinput tablet tool event
2598	* @return The delta of the wheel, in degrees, compared to the last event
2599	*
2600	* @see libinput_event_tablet_tool_get_wheel_delta_discrete
2601	*/
2602	double
2603	libinput_event_tablet_tool_get_wheel_delta(
2604	struct libinput_event_tablet_tool *event);
2605
2606	/**
2607	* @ingroup event_tablet
2608	*
2609	* Return the delta for the wheel in discrete steps (e.g. wheel clicks).
2610
2611	* @param event The libinput tablet tool event
2612	* @return The delta of the wheel, in discrete steps, compared to the last event
2613	*
2614	* @see libinput_event_tablet_tool_get_wheel_delta_discrete
2615	*
2616	* @since 1.2
2617	*/
2618	int
2619	libinput_event_tablet_tool_get_wheel_delta_discrete(
2620	struct libinput_event_tablet_tool *event);
2621
2622	/**
2623	* @ingroup event_tablet
2624	*
2625	* Return the current absolute x coordinate of the tablet tool event,
2626	* transformed to screen coordinates.
2627	*
2628	* @note This function may be called for a specific axis even if
2629	* libinput_event_tablet_tool_*_has_changed() returns 0 for that axis.
2630	* libinput always includes all device axes in the event.
2631	*
2632	* @note On some devices, returned value may be negative or larger than the
2633	* width of the device. See the libinput documentation for more details.
2634	*
2635	* @param event The libinput tablet tool event
2636	* @param width The current output screen width
2637	* @return the current absolute x coordinate transformed to a screen coordinate
2638	*
2639	* @since 1.2
2640	*/
2641	double
2642	libinput_event_tablet_tool_get_x_transformed(struct libinput_event_tablet_tool *event,
2643	uint32_t width);
2644
2645	/**
2646	* @ingroup event_tablet
2647	*
2648	* Return the current absolute y coordinate of the tablet tool event,
2649	* transformed to screen coordinates.
2650	*
2651	* @note This function may be called for a specific axis even if
2652	* libinput_event_tablet_tool_*_has_changed() returns 0 for that axis.
2653	* libinput always includes all device axes in the event.
2654	*
2655	* @note On some devices, returned value may be negative or larger than the
2656	* width of the device. See the libinput documentation for more details.
2657	*
2658	* @param event The libinput tablet tool event
2659	* @param height The current output screen height
2660	* @return the current absolute y coordinate transformed to a screen coordinate
2661	*
2662	* @since 1.2
2663	*/
2664	double
2665	libinput_event_tablet_tool_get_y_transformed(struct libinput_event_tablet_tool *event,
2666	uint32_t height);
2667
2668	/**
2669	* @ingroup event_tablet
2670	*
2671	* Returns the tool that was in use during this event.
2672	*
2673	* The returned tablet tool is not refcounted and may become invalid after
2674	* the next call to libinput. Use libinput_tablet_tool_ref() and
2675	* libinput_tablet_tool_unref() to continue using the handle outside of the
2676	* immediate scope.
2677	*
2678	* If the caller holds at least one reference, this struct is used
2679	* whenever the tools enters proximity again.
2680	*
2681	* @note Physical tool tracking requires hardware support. If unavailable,
2682	* libinput creates one tool per type per tablet. See
2683	* libinput_tablet_tool_get_serial() for more details.
2684	*
2685	* @param event The libinput tablet tool event
2686	* @return The new tool triggering this event
2687	*
2688	* @since 1.2
2689	*/
2690	struct libinput_tablet_tool *
2691	libinput_event_tablet_tool_get_tool(struct libinput_event_tablet_tool *event);
2692
2693	/**
2694	* @ingroup event_tablet
2695	*
2696	* Returns the new proximity state of a tool from a proximity event.
2697	* Used to check whether or not a tool came in or out of proximity during an
2698	* event of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY.
2699	*
2700	* The proximity state represents the logical proximity state which does not
2701	* necessarily match when a tool comes into sensor range or leaves the
2702	* sensor range. On some tools this range does not represent the physical
2703	* range but a reduced tool-specific logical range. If the range is reduced,
2704	* this is done transparent to the caller.
2705	*
2706	* For example, the Wacom mouse and lens cursor tools are usually
2707	* used in relative mode, lying flat on the tablet. Movement typically follows
2708	* the interaction normal mouse movements have, i.e. slightly lift the tool and
2709	* place it in a separate location. The proximity detection on Wacom
2710	* tablets however extends further than the user may lift the mouse, i.e. the
2711	* tool may not be lifted out of physical proximity. For such tools, libinput
2712	* provides software-emulated proximity.
2713	*
2714	* @param event The libinput tablet tool event
2715	* @return The new proximity state of the tool from the event.
2716	*
2717	* @since 1.2
2718	*/
2719	enum libinput_tablet_tool_proximity_state
2720	libinput_event_tablet_tool_get_proximity_state(struct libinput_event_tablet_tool *event);
2721
2722	/**
2723	* @ingroup event_tablet
2724	*
2725	* Returns the new tip state of a tool from a tip event.
2726	* Used to check whether or not a tool came in contact with the tablet
2727	* surface or left contact with the tablet surface during an
2728	* event of type @ref LIBINPUT_EVENT_TABLET_TOOL_TIP.
2729	*
2730	* @param event The libinput tablet tool event
2731	* @return The new tip state of the tool from the event.
2732	*
2733	* @since 1.2
2734	*/
2735	enum libinput_tablet_tool_tip_state
2736	libinput_event_tablet_tool_get_tip_state(struct libinput_event_tablet_tool *event);
2737
2738	/**
2739	* @ingroup event_tablet
2740	*
2741	* Return the button that triggered this event. For events that are not of
2742	* type @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON, this function returns 0.
2743	*
2744	* @note It is an application bug to call this function for events other than
2745	* @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2746	*
2747	* @param event The libinput tablet tool event
2748	* @return the button triggering this event
2749	*
2750	* @since 1.2
2751	*/
2752	uint32_t
2753	libinput_event_tablet_tool_get_button(struct libinput_event_tablet_tool *event);
2754
2755	/**
2756	* @ingroup event_tablet
2757	*
2758	* Return the button state of the event.
2759	*
2760	* @note It is an application bug to call this function for events other than
2761	* @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
2762	*
2763	* @param event The libinput tablet tool event
2764	* @return the button state triggering this event
2765	*
2766	* @since 1.2
2767	*/
2768	enum libinput_button_state
2769	libinput_event_tablet_tool_get_button_state(struct libinput_event_tablet_tool *event);
2770
2771	/**
2772	* @ingroup event_tablet
2773	*
2774	* For the button of a @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON event, return the total
2775	* number of buttons pressed on all devices on the associated seat after the
2776	* the event was triggered.
2777	*
2778	" @note It is an application bug to call this function for events other than
2779	* @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON. For other events, this function returns 0.
2780	*
2781	* @param event The libinput tablet tool event
2782	* @return the seat wide pressed button count for the key of this event
2783	*
2784	* @since 1.2
2785	*/
2786	uint32_t
2787	libinput_event_tablet_tool_get_seat_button_count(struct libinput_event_tablet_tool *event);
2788
2789	/**
2790	* @ingroup event_tablet
2791	*
2792	* @note Timestamps may not always increase. See the libinput documentation
2793	* for more details.
2794	*
2795	* @param event The libinput tablet tool event
2796	* @return The event time for this event
2797	*
2798	* @since 1.2
2799	*/
2800	uint32_t
2801	libinput_event_tablet_tool_get_time(struct libinput_event_tablet_tool *event);
2802
2803	/**
2804	* @ingroup event_tablet
2805	*
2806	* @note Timestamps may not always increase. See the libinput documentation
2807	* for more details.
2808	*
2809	* @param event The libinput tablet tool event
2810	* @return The event time for this event in microseconds
2811	*
2812	* @since 1.2
2813	*/
2814	uint64_t
2815	libinput_event_tablet_tool_get_time_usec(struct libinput_event_tablet_tool *event);
2816
2817	/**
2818	* @ingroup event_tablet
2819	*
2820	* Return the high-level tool type for a tool object.
2821	*
2822	* The high level tool describes general interaction expected with the tool.
2823	* For example, a user would expect a tool of type @ref
2824	* LIBINPUT_TABLET_TOOL_TYPE_PEN to interact with a graphics application
2825	* taking pressure and tilt into account. The default virtual tool assigned
2826	* should be a drawing tool, e.g. a virtual pen or brush.
2827	* A tool of type @ref LIBINPUT_TABLET_TOOL_TYPE_ERASER would normally be
2828	* mapped to an eraser-like virtual tool.
2829	*
2830	* If supported by the hardware, a more specific tool id is always
2831	* available, see libinput_tablet_tool_get_tool_id().
2832	*
2833	* @param tool The libinput tool
2834	* @return The tool type for this tool object
2835	*
2836	* @see libinput_tablet_tool_get_tool_id
2837	*
2838	* @since 1.2
2839	*/
2840	enum libinput_tablet_tool_type
2841	libinput_tablet_tool_get_type(struct libinput_tablet_tool *tool);
2842
2843	/**
2844	* @ingroup event_tablet
2845	*
2846	* Return the tool ID for a tool object. If nonzero, this number identifies
2847	* the specific type of the tool with more precision than the type returned in
2848	* libinput_tablet_tool_get_type(). Not all tablets support a tool ID.
2849	*
2850	* Tablets known to support tool IDs include the Wacom Intuos 3, 4, 5, Wacom
2851	* Cintiq and Wacom Intuos Pro series. The tool ID can be used to
2852	* distinguish between e.g. a Wacom Classic Pen or a Wacom Pro Pen. It is
2853	* the caller's responsibility to interpret the tool ID.
2854	*
2855	* @param tool The libinput tool
2856	* @return The tool ID for this tool object or 0 if none is provided
2857	*
2858	* @see libinput_tablet_tool_get_type
2859	*
2860	* @since 1.2
2861	*/
2862	uint64_t
2863	libinput_tablet_tool_get_tool_id(struct libinput_tablet_tool *tool);
2864
2865	/**
2866	* @ingroup event_tablet
2867	*
2868	* Increment the reference count of the tool by one. A tool is destroyed
2869	* whenever the reference count reaches 0. See libinput_tablet_tool_unref().
2870	*
2871	* @param tool The tool to increment the ref count of
2872	* @return The passed tool
2873	*
2874	* @see libinput_tablet_tool_unref
2875	*
2876	* @since 1.2
2877	*/
2878	struct libinput_tablet_tool *
2879	libinput_tablet_tool_ref(struct libinput_tablet_tool *tool);
2880
2881	/**
2882	* @ingroup event_tablet
2883	*
2884	* Decrement the reference count of the tool by one. When the reference
2885	* count of the tool reaches 0, the memory allocated for the tool will be
2886	* freed.
2887	*
2888	* @param tool The tool to decrement the ref count of
2889	* @return NULL if the tool was destroyed otherwise the passed tool
2890	*
2891	* @see libinput_tablet_tool_ref
2892	*
2893	* @since 1.2
2894	*/
2895	struct libinput_tablet_tool *
2896	libinput_tablet_tool_unref(struct libinput_tablet_tool *tool);
2897
2898	/**
2899	* @ingroup event_tablet
2900	*
2901	* Return whether the tablet tool supports pressure.
2902	*
2903	* @param tool The tool to check the axis capabilities of
2904	* @return Nonzero if the axis is available, zero otherwise.
2905	*
2906	* @since 1.2
2907	*/
2908	int
2909	libinput_tablet_tool_has_pressure(struct libinput_tablet_tool *tool);
2910
2911	/**
2912	* @ingroup event_tablet
2913	*
2914	* Return whether the tablet tool supports distance.
2915	*
2916	* @param tool The tool to check the axis capabilities of
2917	* @return Nonzero if the axis is available, zero otherwise.
2918	*
2919	* @since 1.2
2920	*/
2921	int
2922	libinput_tablet_tool_has_distance(struct libinput_tablet_tool *tool);
2923
2924	/**
2925	* @ingroup event_tablet
2926	*
2927	* Return whether the tablet tool supports tilt.
2928	*
2929	* @param tool The tool to check the axis capabilities of
2930	* @return Nonzero if the axis is available, zero otherwise.
2931	*
2932	* @since 1.2
2933	*/
2934	int
2935	libinput_tablet_tool_has_tilt(struct libinput_tablet_tool *tool);
2936
2937	/**
2938	* @ingroup event_tablet
2939	*
2940	* Return whether the tablet tool supports z-rotation.
2941	*
2942	* @param tool The tool to check the axis capabilities of
2943	* @return Nonzero if the axis is available, zero otherwise.
2944	*
2945	* @since 1.2
2946	*/
2947	int
2948	libinput_tablet_tool_has_rotation(struct libinput_tablet_tool *tool);
2949
2950	/**
2951	* @ingroup event_tablet
2952	*
2953	* Return whether the tablet tool has a slider axis.
2954	*
2955	* @param tool The tool to check the axis capabilities of
2956	* @return Nonzero if the axis is available, zero otherwise.
2957	*
2958	* @since 1.2
2959	*/
2960	int
2961	libinput_tablet_tool_has_slider(struct libinput_tablet_tool *tool);
2962
2963	/**
2964	* @ingroup event_tablet
2965	*
2966	* Return whether the tablet tool has a ellipsis major and minor.
2967	* Where the underlying hardware only supports one of either major or minor,
2968	* libinput emulates the other axis as a circular contact, i.e. major ==
2969	* minor for all values of major.
2970	*
2971	* @param tool The tool to check the axis capabilities of
2972	* @return Nonzero if the axis is available, zero otherwise.
2973	*/
2974	int
2975	libinput_tablet_tool_has_size(struct libinput_tablet_tool *tool);
2976
2977	/**
2978	* @ingroup event_tablet
2979	*
2980	* Return whether the tablet tool has a relative wheel.
2981	*
2982	* @param tool The tool to check the axis capabilities of
2983	* @return Nonzero if the axis is available, zero otherwise.
2984	*
2985	* @since 1.2
2986	*/
2987	int
2988	libinput_tablet_tool_has_wheel(struct libinput_tablet_tool *tool);
2989
2990	/**
2991	* @ingroup event_tablet
2992	*
2993	* Check if a tablet tool has a button with the
2994	* passed-in code (see linux/input.h).
2995	*
2996	* @param tool A tablet tool
2997	* @param code button code to check for
2998	*
2999	* @return 1 if the tool supports this button code, 0 if it does not
3000	*
3001	* @since 1.2
3002	*/
3003	int
3004	libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool,
3005	uint32_t code);
3006
3007	/**
3008	* @ingroup event_tablet
3009	*
3010	* Return nonzero if the physical tool can be uniquely identified by
3011	* libinput, or nonzero otherwise. If a tool can be uniquely identified,
3012	* keeping a reference to the tool allows tracking the tool across
3013	* proximity out sequences and across compatible tablets.
3014	* See libinput_tablet_tool_get_serial() for more details.
3015	*
3016	* @param tool A tablet tool
3017	* @return 1 if the tool can be uniquely identified, 0 otherwise.
3018	*
3019	* @see libinput_tablet_tool_get_serial
3020	*
3021	* @since 1.2
3022	*/
3023	int
3024	libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool);
3025
3026	/**
3027	* @ingroup event_tablet
3028	*
3029	* Return the serial number of a tool. If the tool does not report a serial
3030	* number, this function returns zero.
3031	*
3032	* Some tools provide hardware information that enables libinput to uniquely
3033	* identify the physical device. For example, tools compatible with the
3034	* Wacom Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely
3035	* identifiable through a serial number. libinput does not specify how a
3036	* tool can be identified uniquely, a caller should use
3037	* libinput_tablet_tool_is_unique() to check if the tool is unique.
3038	*
3039	* libinput creates a struct @ref libinput_tablet_tool on the first
3040	* proximity in of this tool. By default, this struct is destroyed on
3041	* proximity out and re-initialized on the next proximity in. If a caller
3042	* keeps a reference to the tool by using libinput_tablet_tool_ref()
3043	* libinput re-uses this struct whenever that same physical tool comes into
3044	* proximity on any tablet
3045	* recognized by libinput. It is possible to attach tool-specific virtual
3046	* state to the tool. For example, a graphics program such as the GIMP may
3047	* assign a specific color to each tool, allowing the artist to use the
3048	* tools like physical pens of different color. In multi-tablet setups it is
3049	* also possible to track the tool across devices.
3050	*
3051	* If the tool does not have a unique identifier, libinput creates a single
3052	* struct @ref libinput_tablet_tool per tool type on each tablet the tool is
3053	* used on.
3054	*
3055	* @param tool The libinput tool
3056	* @return The tool serial number
3057	*
3058	* @see libinput_tablet_tool_is_unique
3059	*
3060	* @since 1.2
3061	*/
3062	uint64_t
3063	libinput_tablet_tool_get_serial(struct libinput_tablet_tool *tool);
3064
3065	/**
3066	* @ingroup event_tablet
3067	*
3068	* Return the user data associated with a tool object. libinput does
3069	* not manage, look at, or modify this data. The caller must ensure the
3070	* data is valid.
3071	*
3072	* @param tool The libinput tool
3073	* @return The user data associated with the tool object
3074	*
3075	* @since 1.2
3076	*/
3077	void *
3078	libinput_tablet_tool_get_user_data(struct libinput_tablet_tool *tool);
3079
3080	/**
3081	* @ingroup event_tablet
3082	*
3083	* Set the user data associated with a tool object, if any.
3084	*
3085	* @param tool The libinput tool
3086	* @param user_data The user data to associate with the tool object
3087	*
3088	* @since 1.2
3089	*/
3090	void
3091	libinput_tablet_tool_set_user_data(struct libinput_tablet_tool *tool,
3092	void *user_data);
3093
3094	/**
3095	* @defgroup event_tablet_pad Tablet pad events
3096	*
3097	* Events that come from the pad of tablet devices. For events from the
3098	* tablet tools, see @ref event_tablet.
3099	*
3100	* @since 1.3
3101	*/
3102
3103	/**
3104	* @ingroup event_tablet_pad
3105	*
3106	* @return The generic libinput_event of this event
3107	*
3108	* @since 1.3
3109	*/
3110	struct libinput_event *
3111	libinput_event_tablet_pad_get_base_event(struct libinput_event_tablet_pad *event);
3112
3113	/**
3114	* @ingroup event_tablet_pad
3115	*
3116	* Returns the current position of the ring, in degrees counterclockwise
3117	* from the northern-most point of the ring in the tablet's current logical
3118	* orientation.
3119	*
3120	* If the source is @ref LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER,
3121	* libinput sends a terminating event with a ring value of -1 when the
3122	* finger is lifted from the ring. A caller may use this information to e.g.
3123	* determine if kinetic scrolling should be triggered.
3124	*
3125	* @note It is an application bug to call this function for events other than
3126	* @ref LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function
3127	* returns 0.
3128	*
3129	* @param event The libinput tablet pad event
3130	* @return The current value of the the axis
3131	* @retval -1 The finger was lifted
3132	*
3133	* @since 1.3
3134	*/
3135	double
3136	libinput_event_tablet_pad_get_ring_position(struct libinput_event_tablet_pad *event);
3137
3138	/**
3139	* @ingroup event_tablet_pad
3140	*
3141	* Returns the number of the ring that has changed state, with 0 being the
3142	* first ring. On tablets with only one ring, this function always returns
3143	* 0.
3144	*
3145	* @note It is an application bug to call this function for events other than
3146	* @ref LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function
3147	* returns 0.
3148	*
3149	* @param event The libinput tablet pad event
3150	* @return The index of the ring that changed state
3151	*
3152	* @since 1.3
3153	*/
3154	unsigned int
3155	libinput_event_tablet_pad_get_ring_number(struct libinput_event_tablet_pad *event);
3156
3157	/**
3158	* @ingroup event_tablet_pad
3159	*
3160	* Returns the source of the interaction with the ring. If the source is
3161	* @ref LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER, libinput sends a ring
3162	* position value of -1 to terminate the current interaction.
3163	*
3164	* @note It is an application bug to call this function for events other than
3165	* @ref LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function
3166	* returns 0.
3167	*
3168	* @param event The libinput tablet pad event
3169	* @return The source of the ring interaction
3170	*
3171	* @since 1.3
3172	*/
3173	enum libinput_tablet_pad_ring_axis_source
3174	libinput_event_tablet_pad_get_ring_source(struct libinput_event_tablet_pad *event);
3175
3176	/**
3177	* @ingroup event_tablet_pad
3178	*
3179	* Returns the current position of the strip, normalized to the range
3180	* [0, 1], with 0 being the top/left-most point in the tablet's current
3181	* logical orientation.
3182	*
3183	* If the source is @ref LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER,
3184	* libinput sends a terminating event with a ring value of -1 when the
3185	* finger is lifted from the ring. A caller may use this information to e.g.
3186	* determine if kinetic scrolling should be triggered.
3187	*
3188	* @note It is an application bug to call this function for events other than
3189	* @ref LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function
3190	* returns 0.
3191	*
3192	* @param event The libinput tablet pad event
3193	* @return The current value of the the axis
3194	* @retval -1 The finger was lifted
3195	*
3196	* @since 1.3
3197	*/
3198	double
3199	libinput_event_tablet_pad_get_strip_position(struct libinput_event_tablet_pad *event);
3200
3201	/**
3202	* @ingroup event_tablet_pad
3203	*
3204	* Returns the number of the strip that has changed state, with 0 being the
3205	* first strip. On tablets with only one strip, this function always returns
3206	* 0.
3207	*
3208	* @note It is an application bug to call this function for events other than
3209	* @ref LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function
3210	* returns 0.
3211	*
3212	* @param event The libinput tablet pad event
3213	* @return The index of the strip that changed state
3214	*
3215	* @since 1.3
3216	*/
3217	unsigned int
3218	libinput_event_tablet_pad_get_strip_number(struct libinput_event_tablet_pad *event);
3219
3220	/**
3221	* @ingroup event_tablet_pad
3222	*
3223	* Returns the source of the interaction with the strip. If the source is
3224	* @ref LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER, libinput sends a strip
3225	* position value of -1 to terminate the current interaction.
3226	*
3227	* @note It is an application bug to call this function for events other than
3228	* @ref LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function
3229	* returns 0.
3230	*
3231	* @param event The libinput tablet pad event
3232	* @return The source of the strip interaction
3233	*
3234	* @since 1.3
3235	*/
3236	enum libinput_tablet_pad_strip_axis_source
3237	libinput_event_tablet_pad_get_strip_source(struct libinput_event_tablet_pad *event);
3238
3239	/**
3240	* @ingroup event_tablet_pad
3241	*
3242	* Return the button number that triggered this event, starting at 0.
3243	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON,
3244	* this function returns 0.
3245	*
3246	* Note that the number returned is a generic sequential button number and
3247	* not a semantic button code as defined in linux/input.h.
3248	* See the libinput documentation for more details.
3249	*
3250	* @note It is an application bug to call this function for events other than
3251	* @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON. For other events, this function
3252	* returns 0.
3253	*
3254	* @param event The libinput tablet pad event
3255	* @return the button triggering this event
3256	*
3257	* @since 1.3
3258	*/
3259	uint32_t
3260	libinput_event_tablet_pad_get_button_number(struct libinput_event_tablet_pad *event);
3261
3262	/**
3263	* @ingroup event_tablet_pad
3264	*
3265	* Return the button state of the event.
3266	*
3267	* @note It is an application bug to call this function for events other than
3268	* @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON. For other events, this function
3269	* returns 0.
3270	*
3271	* @param event The libinput tablet pad event
3272	* @return the button state triggering this event
3273	*
3274	* @since 1.3
3275	*/
3276	enum libinput_button_state
3277	libinput_event_tablet_pad_get_button_state(struct libinput_event_tablet_pad *event);
3278
3279	/**
3280	* @ingroup event_tablet_pad
3281	*
3282	* Return the key code that triggered this event, e.g. KEY_CONTROLPANEL. The
3283	* list of key codes is defined in linux/input-event-codes.h.
3284	*
3285	* For events that are not of type @ref LIBINPUT_EVENT_TABLET_PAD_KEY,
3286	* this function returns 0.
3287	*
3288	* @note It is an application bug to call this function for events other than
3289	* @ref LIBINPUT_EVENT_TABLET_PAD_KEY. For other events, this function
3290	* returns 0.
3291	*
3292	* @param event The libinput tablet pad event
3293	* @return the key code triggering this event
3294	*
3295	* @since 1.15
3296	*/
3297	uint32_t
3298	libinput_event_tablet_pad_get_key(struct libinput_event_tablet_pad *event);
3299
3300	/**
3301	* @ingroup event_tablet_pad
3302	*
3303	* Return the key state of the event.
3304	*
3305	* @note It is an application bug to call this function for events other than
3306	* @ref LIBINPUT_EVENT_TABLET_PAD_KEY. For other events, this function
3307	* returns 0.
3308	*
3309	* @param event The libinput tablet pad event
3310	* @return the key state triggering this event
3311	*
3312	* @since 1.15
3313	*/
3314	enum libinput_key_state
3315	libinput_event_tablet_pad_get_key_state(struct libinput_event_tablet_pad *event);
3316
3317	/**
3318	* @ingroup event_tablet_pad
3319	*
3320	* Returns the mode the button, ring, or strip that triggered this event is
3321	* in, at the time of the event.
3322	*
3323	* The mode is a virtual grouping of functionality, usually based on some
3324	* visual feedback like LEDs on the pad. Mode indices start at 0, a device
3325	* that does not support modes always returns 0.
3326	*
3327	* @note Pad keys are not part of a mode group. It is an application bug to
3328	* call this function for @ref LIBINPUT_EVENT_TABLET_PAD_KEY.
3329	*
3330	* Mode switching is controlled by libinput and more than one mode may exist
3331	* on the tablet. This function returns the mode that this event's button,
3332	* ring or strip is logically in. If the button is a mode toggle button
3333	* and the button event caused a new mode to be toggled, the mode returned
3334	* is the new mode the button is in.
3335	*
3336	* Note that the returned mode is the mode valid as of the time of the
3337	* event. The returned mode may thus be different to the mode returned by
3338	* libinput_tablet_pad_mode_group_get_mode(). See
3339	* libinput_tablet_pad_mode_group_get_mode() for details.
3340	*
3341	* @param event The libinput tablet pad event
3342	* @return the 0-indexed mode of this button, ring or strip at the time of
3343	* the event
3344	*
3345	* @see libinput_tablet_pad_mode_group_get_mode
3346	*
3347	* @since 1.4
3348	*/
3349	unsigned int
3350	libinput_event_tablet_pad_get_mode(struct libinput_event_tablet_pad *event);
3351
3352	/**
3353	* @ingroup event_tablet_pad
3354	*
3355	* Returns the mode group that the button, ring, or strip that triggered
3356	* this event is considered in. The mode is a virtual grouping of
3357	* functionality, usually based on some visual feedback like LEDs on the
3358	* pad.
3359	*
3360	* @note Pad keys are not part of a mode group. It is an application bug to
3361	* call this function for @ref LIBINPUT_EVENT_TABLET_PAD_KEY.
3362	*
3363	* The returned mode group is not refcounted and may become invalid after
3364	* the next call to libinput. Use libinput_tablet_pad_mode_group_ref() and
3365	* libinput_tablet_pad_mode_group_unref() to continue using the handle
3366	* outside of the immediate scope.
3367	*
3368	* @param event The libinput tablet pad event
3369	* @return the mode group of the button, ring or strip that caused this event
3370	*
3371	* @see libinput_device_tablet_pad_get_mode_group
3372	*
3373	* @since 1.4
3374	*/
3375	struct libinput_tablet_pad_mode_group *
3376	libinput_event_tablet_pad_get_mode_group(struct libinput_event_tablet_pad *event);
3377
3378	/**
3379	* @ingroup event_tablet_pad
3380	*
3381	* @note Timestamps may not always increase. See the libinput documentation
3382	* for more details.
3383	*
3384	* @param event The libinput tablet pad event
3385	* @return The event time for this event
3386	*
3387	* @since 1.3
3388	*/
3389	uint32_t
3390	libinput_event_tablet_pad_get_time(struct libinput_event_tablet_pad *event);
3391
3392	/**
3393	* @ingroup event_tablet_pad
3394	*
3395	* @note Timestamps may not always increase. See the libinput documentation
3396	* for more details.
3397	*
3398	* @param event The libinput tablet pad event
3399	* @return The event time for this event in microseconds
3400	*
3401	* @since 1.3
3402	*/
3403	uint64_t
3404	libinput_event_tablet_pad_get_time_usec(struct libinput_event_tablet_pad *event);
3405
3406	/**
3407	* @defgroup event_switch Switch events
3408	*
3409	* Events that come from switch devices.
3410	*/
3411
3412	/**
3413	* @ingroup event_switch
3414	*
3415	* Return the switch that triggered this event.
3416	* For pointer events that are not of type @ref
3417	* LIBINPUT_EVENT_SWITCH_TOGGLE, this function returns 0.
3418	*
3419	* @note It is an application bug to call this function for events other than
3420	* @ref LIBINPUT_EVENT_SWITCH_TOGGLE.
3421	*
3422	* @param event The libinput switch event
3423	* @return The switch triggering this event
3424	*
3425	* @since 1.7
3426	*/
3427	enum libinput_switch
3428	libinput_event_switch_get_switch(struct libinput_event_switch *event);
3429
3430	/**
3431	* @ingroup event_switch
3432	*
3433	* Return the switch state that triggered this event.
3434	* For switch events that are not of type @ref
3435	* LIBINPUT_EVENT_SWITCH_TOGGLE, this function returns 0.
3436	*
3437	* @note It is an application bug to call this function for events other than
3438	* @ref LIBINPUT_EVENT_SWITCH_TOGGLE.
3439	*
3440	* @param event The libinput switch event
3441	* @return The switch state triggering this event
3442	*
3443	* @since 1.7
3444	*/
3445	enum libinput_switch_state
3446	libinput_event_switch_get_switch_state(struct libinput_event_switch *event);
3447
3448	/**
3449	* @ingroup event_switch
3450	*
3451	* @return The generic libinput_event of this event
3452	*
3453	* @since 1.7
3454	*/
3455	struct libinput_event *
3456	libinput_event_switch_get_base_event(struct libinput_event_switch *event);
3457
3458	/**
3459	* @ingroup event_switch
3460	*
3461	* @note Timestamps may not always increase. See the libinput documentation
3462	* for more details.
3463	*
3464	* @param event The libinput switch event
3465	* @return The event time for this event
3466	*
3467	* @since 1.7
3468	*/
3469	uint32_t
3470	libinput_event_switch_get_time(struct libinput_event_switch *event);
3471
3472	/**
3473	* @ingroup event_switch
3474	*
3475	* @note Timestamps may not always increase. See the libinput documentation
3476	* for more details.
3477	*
3478	* @param event The libinput switch event
3479	* @return The event time for this event in microseconds
3480	*
3481	* @since 1.7
3482	*/
3483	uint64_t
3484	libinput_event_switch_get_time_usec(struct libinput_event_switch *event);
3485
3486	/**
3487	* @defgroup base Initialization and manipulation of libinput contexts
3488	*/
3489
3490	/**
3491	* @ingroup base
3492	* @struct libinput_interface
3493	*
3494	* libinput does not open file descriptors to devices directly, instead
3495	* open_restricted() and close_restricted() are called for each path that
3496	* must be opened.
3497	*
3498	* @see libinput_udev_create_context
3499	* @see libinput_path_create_context
3500	*/
3501	struct libinput_interface {
3502	/**
3503	* Open the device at the given path with the flags provided and
3504	* return the fd.
3505	*
3506	* @param path The device path to open
3507	* @param flags Flags as defined by open(2)
3508	* @param user_data The user_data provided in
3509	* libinput_udev_create_context()
3510	*
3511	* @return The file descriptor, or a negative errno on failure.
3512	*/
3513	int (*open_restricted)(const char *path, int flags, void *user_data);
3514	/**
3515	* Close the file descriptor.
3516	*
3517	* @param fd The file descriptor to close
3518	* @param user_data The user_data provided in
3519	* libinput_udev_create_context()
3520	*/
3521	void (*close_restricted)(int fd, void *user_data);
3522	};
3523
3524	/**
3525	* @ingroup base
3526	*
3527	* Create a new libinput context from udev. This context is inactive until
3528	* assigned a seat ID with libinput_udev_assign_seat().
3529	*
3530	* @param interface The callback interface
3531	* @param user_data Caller-specific data passed to the various callback
3532	* interfaces.
3533	* @param udev An already initialized udev context
3534	*
3535	* @return An initialized, but inactive libinput context or NULL on error
3536	*/
3537	struct libinput *
3538	libinput_udev_create_context(const struct libinput_interface *interface,
3539	void *user_data,
3540	struct udev *udev);
3541
3542	/**
3543	* @ingroup base
3544	*
3545	* Assign a seat to this libinput context. New devices or the removal of
3546	* existing devices will appear as events during libinput_dispatch().
3547	*
3548	* libinput_udev_assign_seat() succeeds even if no input devices are currently
3549	* available on this seat, or if devices are available but fail to open in
3550	* @ref libinput_interface::open_restricted. Devices that do not have the
3551	* minimum capabilities to be recognized as pointer, keyboard or touch
3552	* device are ignored. Such devices and those that failed to open
3553	* ignored until the next call to libinput_resume().
3554	*
3555	* This function may only be called once per context.
3556	*
3557	* @param libinput A libinput context initialized with
3558	* libinput_udev_create_context()
3559	* @param seat_id A seat identifier. This string must not be NULL.
3560	*
3561	* @return 0 on success or -1 on failure.
3562	*/
3563	int
3564	libinput_udev_assign_seat(struct libinput *libinput,
3565	const char *seat_id);
3566
3567	/**
3568	* @ingroup base
3569	*
3570	* Create a new libinput context that requires the caller to manually add or
3571	* remove devices with libinput_path_add_device() and
3572	* libinput_path_remove_device().
3573	*
3574	* The context is fully initialized but will not generate events until at
3575	* least one device has been added.
3576	*
3577	* The reference count of the context is initialized to 1. See @ref
3578	* libinput_unref.
3579	*
3580	* @param interface The callback interface
3581	* @param user_data Caller-specific data passed to the various callback
3582	* interfaces.
3583	*
3584	* @return An initialized, empty libinput context.
3585	*/
3586	struct libinput *
3587	libinput_path_create_context(const struct libinput_interface *interface,
3588	void *user_data);
3589
3590	/**
3591	* @ingroup base
3592	*
3593	* Add a device to a libinput context initialized with
3594	* libinput_path_create_context(). If successful, the device will be
3595	* added to the internal list and re-opened on libinput_resume(). The device
3596	* can be removed with libinput_path_remove_device().
3597	*
3598	* If the device was successfully initialized, it is returned in the device
3599	* argument. The lifetime of the returned device pointer is limited until
3600	* the next libinput_dispatch(), use libinput_device_ref() to keep a permanent
3601	* reference.
3602	*
3603	* @param libinput A previously initialized libinput context
3604	* @param path Path to an input device
3605	* @return The newly initiated device on success, or NULL on failure.
3606	*
3607	* @note It is an application bug to call this function on a libinput
3608	* context initialized with libinput_udev_create_context().
3609	*/
3610	struct libinput_device *
3611	libinput_path_add_device(struct libinput *libinput,
3612	const char *path);
3613
3614	/**
3615	* @ingroup base
3616	*
3617	* Remove a device from a libinput context initialized with
3618	* libinput_path_create_context() or added to such a context with
3619	* libinput_path_add_device().
3620	*
3621	* Events already processed from this input device are kept in the queue,
3622	* the @ref LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for
3623	* this device.
3624	*
3625	* If no matching device exists, this function does nothing.
3626	*
3627	* @param device A libinput device
3628	*
3629	* @note It is an application bug to call this function on a libinput
3630	* context initialized with libinput_udev_create_context().
3631	*/
3632	void
3633	libinput_path_remove_device(struct libinput_device *device);
3634
3635	/**
3636	* @ingroup base
3637	*
3638	* libinput keeps a single file descriptor for all events. Call into
3639	* libinput_dispatch() if any events become available on this fd.
3640	*
3641	* @return The file descriptor used to notify of pending events.
3642	*/
3643	int
3644	libinput_get_fd(struct libinput *libinput);
3645
3646	/**
3647	* @ingroup base
3648	*
3649	* Main event dispatchment function. Reads events of the file descriptors
3650	* and processes them internally. Use libinput_get_event() to retrieve the
3651	* events.
3652	*
3653	* Dispatching does not necessarily queue libinput events. This function
3654	* should be called immediately once data is available on the file
3655	* descriptor returned by libinput_get_fd(). libinput has a number of
3656	* timing-sensitive features (e.g. tap-to-click), any delay in calling
3657	* libinput_dispatch() may prevent these features from working correctly.
3658	*
3659	* @param libinput A previously initialized libinput context
3660	*
3661	* @return 0 on success, or a negative errno on failure
3662	*/
3663	int
3664	libinput_dispatch(struct libinput *libinput);
3665
3666	/**
3667	* @ingroup base
3668	*
3669	* Retrieve the next event from libinput's internal event queue.
3670	*
3671	* After handling the retrieved event, the caller must destroy it using
3672	* libinput_event_destroy().
3673	*
3674	* @param libinput A previously initialized libinput context
3675	* @return The next available event, or NULL if no event is available.
3676	*/
3677	struct libinput_event *
3678	libinput_get_event(struct libinput *libinput);
3679
3680	/**
3681	* @ingroup base
3682	*
3683	* Return the type of the next event in the internal queue. This function
3684	* does not pop the event off the queue and the next call to
3685	* libinput_get_event() returns that event.
3686	*
3687	* @param libinput A previously initialized libinput context
3688	* @return The event type of the next available event or @ref
3689	* LIBINPUT_EVENT_NONE if no event is available.
3690	*/
3691	enum libinput_event_type
3692	libinput_next_event_type(struct libinput *libinput);
3693
3694	/**
3695	* @ingroup base
3696	*
3697	* Set caller-specific data associated with this context. libinput does
3698	* not manage, look at, or modify this data. The caller must ensure the
3699	* data is valid.
3700	*
3701	* @param libinput A previously initialized libinput context
3702	* @param user_data Caller-specific data passed to the various callback
3703	* interfaces.
3704	*/
3705	void
3706	libinput_set_user_data(struct libinput *libinput,
3707	void *user_data);
3708
3709	/**
3710	* @ingroup base
3711	*
3712	* Get the caller-specific data associated with this context, if any.
3713	*
3714	* @param libinput A previously initialized libinput context
3715	* @return The caller-specific data previously assigned in
3716	* libinput_set_user_data(), libinput_path_create_context() or
3717	* libinput_udev_create_context().
3718	*/
3719	void *
3720	libinput_get_user_data(struct libinput *libinput);
3721
3722	/**
3723	* @ingroup base
3724	*
3725	* Resume a suspended libinput context. This re-enables device
3726	* monitoring and adds existing devices.
3727	*
3728	* @param libinput A previously initialized libinput context
3729	* @see libinput_suspend
3730	*
3731	* @return 0 on success or -1 on failure
3732	*/
3733	int
3734	libinput_resume(struct libinput *libinput);
3735
3736	/**
3737	* @ingroup base
3738	*
3739	* Suspend monitoring for new devices and close existing devices.
3740	* This all but terminates libinput but does keep the context
3741	* valid to be resumed with libinput_resume().
3742	*
3743	* @param libinput A previously initialized libinput context
3744	*/
3745	void
3746	libinput_suspend(struct libinput *libinput);
3747
3748	/**
3749	* @ingroup base
3750	*
3751	* Add a reference to the context. A context is destroyed whenever the
3752	* reference count reaches 0. See @ref libinput_unref.
3753	*
3754	* @param libinput A previously initialized valid libinput context
3755	* @return The passed libinput context
3756	*/
3757	struct libinput *
3758	libinput_ref(struct libinput *libinput);
3759
3760	/**
3761	* @ingroup base
3762	*
3763	* Dereference the libinput context. After this, the context may have been
3764	* destroyed, if the last reference was dereferenced. If so, the context is
3765	* invalid and may not be interacted with.
3766	*
3767	* @bug When the refcount reaches zero, libinput_unref() releases resources
3768	* even if a caller still holds refcounted references to related resources
3769	* (e.g. a libinput_device). When libinput_unref() returns
3770	* NULL, the caller must consider any resources related to that context
3771	* invalid. See https://bugs.freedesktop.org/show_bug.cgi?id=91872.
3772	*
3773	* Example code:
3774	* @code
3775	* li = libinput_path_create_context(&interface, NULL);
3776	* device = libinput_path_add_device(li, "/dev/input/event0");
3777	* // get extra reference to device
3778	* libinput_device_ref(device);
3779	*
3780	* // refcount reaches 0, so *all* resources are cleaned up,
3781	* // including device
3782	* libinput_unref(li);
3783	*
3784	* // INCORRECT: device has been cleaned up and must not be used
3785	* // li = libinput_device_get_context(device);
3786	* @endcode
3787	*
3788	* @param libinput A previously initialized libinput context
3789	* @return NULL if context was destroyed otherwise the passed context
3790	*/
3791	struct libinput *
3792	libinput_unref(struct libinput *libinput);
3793
3794	/**
3795	* @ingroup base
3796	*
3797	* Set the log priority for the libinput context. Messages with priorities
3798	* equal to or higher than the argument will be printed to the context's
3799	* log handler.
3800	*
3801	* The default log priority is @ref LIBINPUT_LOG_PRIORITY_ERROR.
3802	*
3803	* @param libinput A previously initialized libinput context
3804	* @param priority The minimum priority of log messages to print.
3805	*
3806	* @see libinput_log_set_handler
3807	* @see libinput_log_get_priority
3808	*/
3809	void
3810	libinput_log_set_priority(struct libinput *libinput,
3811	enum libinput_log_priority priority);
3812
3813	/**
3814	* @ingroup base
3815	*
3816	* Get the context's log priority. Messages with priorities equal to or
3817	* higher than the argument will be printed to the current log handler.
3818	*
3819	* The default log priority is @ref LIBINPUT_LOG_PRIORITY_ERROR.
3820	*
3821	* @param libinput A previously initialized libinput context
3822	* @return The minimum priority of log messages to print.
3823	*
3824	* @see libinput_log_set_handler
3825	* @see libinput_log_set_priority
3826	*/
3827	enum libinput_log_priority
3828	libinput_log_get_priority(const struct libinput *libinput);
3829
3830	/**
3831	* @ingroup base
3832	*
3833	* Log handler type for custom logging.
3834	*
3835	* @param libinput The libinput context
3836	* @param priority The priority of the current message
3837	* @param format Message format in printf-style
3838	* @param args Message arguments
3839	*
3840	* @see libinput_log_set_priority
3841	* @see libinput_log_get_priority
3842	* @see libinput_log_set_handler
3843	*/
3844	typedef void (*libinput_log_handler)(struct libinput *libinput,
3845	enum libinput_log_priority priority,
3846	const char *format, va_list args)
3847	LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
3848
3849	/**
3850	* @ingroup base
3851	*
3852	* Set the context's log handler. Messages with priorities equal to or
3853	* higher than the context's log priority will be passed to the given
3854	* log handler.
3855	*
3856	* The default log handler prints to stderr.
3857	*
3858	* @param libinput A previously initialized libinput context
3859	* @param log_handler The log handler for library messages.
3860	*
3861	* @see libinput_log_set_priority
3862	* @see libinput_log_get_priority
3863	*/
3864	void
3865	libinput_log_set_handler(struct libinput *libinput,
3866	libinput_log_handler log_handler);
3867
3868	/**
3869	* @defgroup seat Initialization and manipulation of seats
3870	*
3871	* A seat has two identifiers, the physical name and the logical name. A
3872	* device is always assigned to exactly one seat. It may change to a
3873	* different logical seat but it cannot change physical seats.
3874	*
3875	* See the libinput documentation for more information on seats.
3876	*/
3877
3878	/**
3879	* @ingroup seat
3880	*
3881	* Increase the refcount of the seat. A seat will be freed whenever the
3882	* refcount reaches 0. This may happen during libinput_dispatch() if the
3883	* seat was removed from the system. A caller must ensure to reference
3884	* the seat correctly to avoid dangling pointers.
3885	*
3886	* @param seat A previously obtained seat
3887	* @return The passed seat
3888	*/
3889	struct libinput_seat *
3890	libinput_seat_ref(struct libinput_seat *seat);
3891
3892	/**
3893	* @ingroup seat
3894	*
3895	* Decrease the refcount of the seat. A seat will be freed whenever the
3896	* refcount reaches 0. This may happen during libinput_dispatch() if the
3897	* seat was removed from the system. A caller must ensure to reference
3898	* the seat correctly to avoid dangling pointers.
3899	*
3900	* @param seat A previously obtained seat
3901	* @return NULL if seat was destroyed, otherwise the passed seat
3902	*/
3903	struct libinput_seat *
3904	libinput_seat_unref(struct libinput_seat *seat);
3905
3906	/**
3907	* @ingroup seat
3908	*
3909	* Set caller-specific data associated with this seat. libinput does
3910	* not manage, look at, or modify this data. The caller must ensure the
3911	* data is valid.
3912	*
3913	* @param seat A previously obtained seat
3914	* @param user_data Caller-specific data pointer
3915	* @see libinput_seat_get_user_data
3916	*/
3917	void
3918	libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
3919
3920	/**
3921	* @ingroup seat
3922	*
3923	* Get the caller-specific data associated with this seat, if any.
3924	*
3925	* @param seat A previously obtained seat
3926	* @return Caller-specific data pointer or NULL if none was set
3927	* @see libinput_seat_set_user_data
3928	*/
3929	void *
3930	libinput_seat_get_user_data(struct libinput_seat *seat);
3931
3932	/**
3933	* @ingroup seat
3934	*
3935	* Get the libinput context from the seat.
3936	*
3937	* @param seat A previously obtained seat
3938	* @return The libinput context for this seat.
3939	*/
3940	struct libinput *
3941	libinput_seat_get_context(struct libinput_seat *seat);
3942
3943	/**
3944	* @ingroup seat
3945	*
3946	* Return the physical name of the seat. For libinput contexts created from
3947	* udev, this is always the same value as passed into
3948	* libinput_udev_assign_seat() and all seats from that context will have
3949	* the same physical name.
3950	*
3951	* The physical name of the seat is one that is usually set by the system or
3952	* lower levels of the stack. In most cases, this is the base filter for
3953	* devices - devices assigned to seats outside the current seat will not
3954	* be available to the caller.
3955	*
3956	* @param seat A previously obtained seat
3957	* @return The physical name of this seat
3958	*/
3959	const char *
3960	libinput_seat_get_physical_name(struct libinput_seat *seat);
3961
3962	/**
3963	* @ingroup seat
3964	*
3965	* Return the logical name of the seat. This is an identifier to group sets
3966	* of devices within the compositor.
3967	*
3968	* @param seat A previously obtained seat
3969	* @return The logical name of this seat
3970	*/
3971	const char *
3972	libinput_seat_get_logical_name(struct libinput_seat *seat);
3973
3974	/**
3975	* @defgroup device Initialization and manipulation of input devices
3976	*/
3977
3978	/**
3979	* @ingroup device
3980	*
3981	* Increase the refcount of the input device. An input device will be freed
3982	* whenever the refcount reaches 0. This may happen during
3983	* libinput_dispatch() if the device was removed from the system. A caller
3984	* must ensure to reference the device correctly to avoid dangling pointers.
3985	*
3986	* @param device A previously obtained device
3987	* @return The passed device
3988	*/
3989	struct libinput_device *
3990	libinput_device_ref(struct libinput_device *device);
3991
3992	/**
3993	* @ingroup device
3994	*
3995	* Decrease the refcount of the input device. An input device will be freed
3996	* whenever the refcount reaches 0. This may happen during libinput_dispatch
3997	* if the device was removed from the system. A caller must ensure to
3998	* reference the device correctly to avoid dangling pointers.
3999	*
4000	* @param device A previously obtained device
4001	* @return NULL if the device was destroyed, otherwise the passed device
4002	*/
4003	struct libinput_device *
4004	libinput_device_unref(struct libinput_device *device);
4005
4006	/**
4007	* @ingroup device
4008	*
4009	* Set caller-specific data associated with this input device. libinput does
4010	* not manage, look at, or modify this data. The caller must ensure the
4011	* data is valid.
4012	*
4013	* @param device A previously obtained device
4014	* @param user_data Caller-specific data pointer
4015	* @see libinput_device_get_user_data
4016	*/
4017	void
4018	libinput_device_set_user_data(struct libinput_device *device, void *user_data);
4019
4020	/**
4021	* @ingroup device
4022	*
4023	* Get the caller-specific data associated with this input device, if any.
4024	*
4025	* @param device A previously obtained device
4026	* @return Caller-specific data pointer or NULL if none was set
4027	* @see libinput_device_set_user_data
4028	*/
4029	void *
4030	libinput_device_get_user_data(struct libinput_device *device);
4031
4032	/**
4033	* @ingroup device
4034	*
4035	* Get the libinput context from the device.
4036	*
4037	* @param device A previously obtained device
4038	* @return The libinput context for this device.
4039	*/
4040	struct libinput *
4041	libinput_device_get_context(struct libinput_device *device);
4042
4043	/**
4044	* @ingroup device
4045	*
4046	* Get the device group this device is assigned to. Some physical
4047	* devices like graphics tablets are represented by multiple kernel
4048	* devices and thus by multiple struct @ref libinput_device.
4049	*
4050	* libinput assigns these devices to the same @ref libinput_device_group
4051	* allowing the caller to identify such devices and adjust configuration
4052	* settings accordingly. For example, setting a tablet to left-handed often
4053	* means turning it upside down. A touch device on the same tablet would
4054	* need to be turned upside down too to work correctly.
4055	*
4056	* All devices are part of a device group though for most devices the group
4057	* will be a singleton. A device is assigned to a device group on @ref
4058	* LIBINPUT_EVENT_DEVICE_ADDED and removed from that group on @ref
4059	* LIBINPUT_EVENT_DEVICE_REMOVED. It is up to the caller to track how many
4060	* devices are in each device group.
4061	*
4062	* @dot
4063	* digraph groups_libinput {
4064	* rankdir="TB";
4065	* node [
4066	* shape="box";
4067	* ]
4068	*
4069	* mouse [ label="mouse"; URL="\ref libinput_device"];
4070	* kbd [ label="keyboard"; URL="\ref libinput_device"];
4071	*
4072	* pen [ label="tablet pen"; URL="\ref libinput_device"];
4073	* touch [ label="tablet touch"; URL="\ref libinput_device"];
4074	* pad [ label="tablet pad"; URL="\ref libinput_device"];
4075	*
4076	* group1 [ label="group 1"; URL="\ref libinput_device_group"];
4077	* group2 [ label="group 2"; URL="\ref libinput_device_group"];
4078	* group3 [ label="group 3"; URL="\ref libinput_device_group"];
4079	*
4080	* mouse -> group1
4081	* kbd -> group2
4082	*
4083	* pen -> group3;
4084	* touch -> group3;
4085	* pad -> group3;
4086	* }
4087	* @enddot
4088	*
4089	* Device groups do not get re-used once the last device in the group was
4090	* removed, i.e. unplugging and re-plugging a physical device with grouped
4091	* devices will return a different device group after every unplug.
4092	*
4093	* The returned device group is not refcounted and may become invalid after
4094	* the next call to libinput. Use libinput_device_group_ref() and
4095	* libinput_device_group_unref() to continue using the handle outside of the
4096	* immediate scope.
4097	*
4098	* Device groups are assigned based on the <b>LIBINPUT_DEVICE_GROUP</b> udev
4099	* property, see the libinput documentation for more details.
4100	*
4101	* @return The device group this device belongs to
4102	*/
4103	struct libinput_device_group *
4104	libinput_device_get_device_group(struct libinput_device *device);
4105
4106	/**
4107	* @ingroup device
4108	*
4109	* Get the system name of the device.
4110	*
4111	* To get the descriptive device name, use libinput_device_get_name().
4112	*
4113	* @param device A previously obtained device
4114	* @return System name of the device
4115	*
4116	*/
4117	const char *
4118	libinput_device_get_sysname(struct libinput_device *device);
4119
4120	/**
4121	* @ingroup device
4122	*
4123	* The descriptive device name as advertised by the kernel and/or the
4124	* hardware itself. To get the sysname for this device, use
4125	* libinput_device_get_sysname().
4126	*
4127	* The lifetime of the returned string is tied to the struct
4128	* libinput_device. The string may be the empty string but is never NULL.
4129	*
4130	* @param device A previously obtained device
4131	* @return The device name
4132	*/
4133	const char *
4134	libinput_device_get_name(struct libinput_device *device);
4135
4136	/**
4137	* @ingroup device
4138	*
4139	* Get the product ID for this device.
4140	*
4141	* @param device A previously obtained device
4142	* @return The product ID of this device
4143	*/
4144	unsigned int
4145	libinput_device_get_id_product(struct libinput_device *device);
4146
4147	/**
4148	* @ingroup device
4149	*
4150	* Get the vendor ID for this device.
4151	*
4152	* @param device A previously obtained device
4153	* @return The vendor ID of this device
4154	*/
4155	unsigned int
4156	libinput_device_get_id_vendor(struct libinput_device *device);
4157
4158	/**
4159	* @ingroup device
4160	*
4161	* A device may be mapped to a single output, or all available outputs. If a
4162	* device is mapped to a single output only, a relative device may not move
4163	* beyond the boundaries of this output. An absolute device has its input
4164	* coordinates mapped to the extents of this output.
4165	*
4166	* @note <b>Use of this function is discouraged.</b> Its return value is not
4167	* precisely defined and may not be understood by the caller or may be
4168	* insufficient to map the device. Instead, the system configuration could
4169	* set a udev property the caller understands and interprets correctly. The
4170	* caller could then obtain device with libinput_device_get_udev_device()
4171	* and query it for this property. For more complex cases, the caller
4172	* must implement monitor-to-device association heuristics.
4173	*
4174	* @return The name of the output this device is mapped to, or NULL if no
4175	* output is set
4176	*/
4177	const char *
4178	libinput_device_get_output_name(struct libinput_device *device);
4179
4180	/**
4181	* @ingroup device
4182	*
4183	* Get the seat associated with this input device.
4184	*
4185	* A seat can be uniquely identified by the physical and logical seat name.
4186	* There will ever be only one seat instance with a given physical and logical
4187	* seat name pair at any given time, but if no external reference is kept, it
4188	* may be destroyed if no device belonging to it is left.
4189	*
4190	* The returned seat is not refcounted and may become invalid after
4191	* the next call to libinput. Use libinput_seat_ref() and
4192	* libinput_seat_unref() to continue using the handle outside of the
4193	* immediate scope.
4194	*
4195	* See the libinput documentation for more information on seats.
4196	*
4197	* @param device A previously obtained device
4198	* @return The seat this input device belongs to
4199	*/
4200	struct libinput_seat *
4201	libinput_device_get_seat(struct libinput_device *device);
4202
4203	/**
4204	* @ingroup device
4205	*
4206	* Change the logical seat associated with this device by removing the
4207	* device and adding it to the new seat.
4208	*
4209	* This command is identical to physically unplugging the device, then
4210	* re-plugging it as a member of the new seat. libinput will generate a
4211	* @ref LIBINPUT_EVENT_DEVICE_REMOVED event and this @ref libinput_device is
4212	* considered removed from the context; it will not generate further events
4213	* and will be freed when the refcount reaches zero.
4214	* A @ref LIBINPUT_EVENT_DEVICE_ADDED event is generated with a new @ref
4215	* libinput_device handle. It is the caller's responsibility to update
4216	* references to the new device accordingly.
4217	*
4218	* If the logical seat name already exists in the device's physical seat,
4219	* the device is added to this seat. Otherwise, a new seat is created.
4220	*
4221	* @note This change applies to this device until removal or @ref
4222	* libinput_suspend(), whichever happens earlier.
4223	*
4224	* @param device A previously obtained device
4225	* @param name The new logical seat name
4226	* @return 0 on success, non-zero on error
4227	*/
4228	int
4229	libinput_device_set_seat_logical_name(struct libinput_device *device,
4230	const char *name);
4231
4232	/**
4233	* @ingroup device
4234	*
4235	* Return a udev handle to the device that is this libinput device, if any.
4236	* The returned handle has a refcount of at least 1, the caller must call
4237	* <i>udev_device_unref()</i> once to release the associated resources.
4238	* See the [libudev documentation]
4239	* (http://www.freedesktop.org/software/systemd/libudev/) for details.
4240	*
4241	* Some devices may not have a udev device, or the udev device may be
4242	* unobtainable. This function returns NULL if no udev device was available.
4243	*
4244	* Calling this function multiple times for the same device may not
4245	* return the same udev handle each time.
4246	*
4247	* @param device A previously obtained device
4248	* @return A udev handle to the device with a refcount of >= 1 or NULL.
4249	* @retval NULL This device is not represented by a udev device
4250	*/
4251	struct udev_device *
4252	libinput_device_get_udev_device(struct libinput_device *device);
4253
4254	/**
4255	* @ingroup device
4256	*
4257	* Update the LEDs on the device, if any. If the device does not have
4258	* LEDs, or does not have one or more of the LEDs given in the mask, this
4259	* function does nothing.
4260	*
4261	* @param device A previously obtained device
4262	* @param leds A mask of the LEDs to set, or unset.
4263	*/
4264	void
4265	libinput_device_led_update(struct libinput_device *device,
4266	enum libinput_led leds);
4267
4268	/**
4269	* @ingroup device
4270	*
4271	* Check if the given device has the specified capability
4272	*
4273	* @return Non-zero if the given device has the capability or zero otherwise
4274	*/
4275	int
4276	libinput_device_has_capability(struct libinput_device *device,
4277	enum libinput_device_capability capability);
4278
4279	/**
4280	* @ingroup device
4281	*
4282	* Get the physical size of a device in mm, where meaningful. This function
4283	* only succeeds on devices with the required data, i.e. tablets, touchpads
4284	* and touchscreens.
4285	*
4286	* If this function returns nonzero, width and height are unmodified.
4287	*
4288	* @param device The device
4289	* @param width Set to the width of the device
4290	* @param height Set to the height of the device
4291	* @return 0 on success, or nonzero otherwise
4292	*/
4293	int
4294	libinput_device_get_size(struct libinput_device *device,
4295	double *width,
4296	double *height);
4297
4298	/**
4299	* @ingroup device
4300	*
4301	* Check if a @ref LIBINPUT_DEVICE_CAP_POINTER device has a button with the
4302	* given code (see linux/input-event-codes.h).
4303	*
4304	* @param device A current input device
4305	* @param code Button code to check for, e.g. <i>BTN_LEFT</i>
4306	*
4307	* @return 1 if the device supports this button code, 0 if it does not, -1
4308	* on error.
4309	*/
4310	int
4311	libinput_device_pointer_has_button(struct libinput_device *device, uint32_t code);
4312
4313	/**
4314	* @ingroup device
4315	*
4316	* Check if a @ref LIBINPUT_DEVICE_CAP_KEYBOARD device has a key with the
4317	* given code (see linux/input-event-codes.h).
4318	*
4319	* @param device A current input device
4320	* @param code Key code to check for, e.g. <i>KEY_ESC</i>
4321	*
4322	* @return 1 if the device supports this key code, 0 if it does not, -1
4323	* on error.
4324	*/
4325	int
4326	libinput_device_keyboard_has_key(struct libinput_device *device,
4327	uint32_t code);
4328
4329	/**
4330	* @ingroup device
4331	*
4332	* Check how many touches a @ref LIBINPUT_DEVICE_CAP_TOUCH device supports
4333	* simultaneously.
4334	*
4335	* @param device A current input device
4336	*
4337	* @return The number of simultaneous touches or 0 if unknown, -1
4338	* on error.
4339	*
4340	* @since 1.11
4341	*/
4342	int
4343	libinput_device_touch_get_touch_count(struct libinput_device *device);
4344
4345	/**
4346	* @ingroup device
4347	*
4348	* Check if a @ref LIBINPUT_DEVICE_CAP_SWITCH device has a switch of the
4349	* given type.
4350	*
4351	* @param device A current input device
4352	* @param sw Switch to check for
4353	*
4354	* @return 1 if the device supports this switch, 0 if it does not, -1
4355	* on error.
4356	*
4357	* @since 1.9
4358	*/
4359	int
4360	libinput_device_switch_has_switch(struct libinput_device *device,
4361	enum libinput_switch sw);
4362
4363	/**
4364	* @ingroup device
4365	*
4366	* Return the number of buttons on a device with the
4367	* @ref LIBINPUT_DEVICE_CAP_TABLET_PAD capability.
4368	* Buttons on a pad device are numbered sequentially, see the
4369	* libinput documentation for details.
4370	*
4371	* @param device A current input device
4372	*
4373	* @return The number of buttons supported by the device.
4374	*
4375	* @since 1.3
4376	*/
4377	int
4378	libinput_device_tablet_pad_get_num_buttons(struct libinput_device *device);
4379
4380	/**
4381	* @ingroup device
4382	*
4383	* Return the number of rings a device with the @ref
4384	* LIBINPUT_DEVICE_CAP_TABLET_PAD capability provides.
4385	*
4386	* @param device A current input device
4387	*
4388	* @return The number of rings or 0 if the device has no rings.
4389	*
4390	* @see libinput_event_tablet_pad_get_ring_number
4391	*
4392	* @since 1.3
4393	*/
4394	int
4395	libinput_device_tablet_pad_get_num_rings(struct libinput_device *device);
4396
4397	/**
4398	* @ingroup device
4399	*
4400	* Return the number of strips a device with the @ref
4401	* LIBINPUT_DEVICE_CAP_TABLET_PAD capability provides.
4402	*
4403	* @param device A current input device
4404	*
4405	* @return The number of strips or 0 if the device has no strips.
4406	*
4407	* @see libinput_event_tablet_pad_get_strip_number
4408	*
4409	* @since 1.3
4410	*/
4411	int
4412	libinput_device_tablet_pad_get_num_strips(struct libinput_device *device);
4413
4414	/**
4415	* @ingroup device
4416	*
4417	* Check if a @ref LIBINPUT_DEVICE_CAP_TABLET_PAD device has a key with the
4418	* given code (see linux/input-event-codes.h).
4419	*
4420	* @param device A current input device
4421	* @param code Key code to check for, e.g. <i>KEY_ESC</i>
4422	*
4423	* @return 1 if the device supports this key code, 0 if it does not, -1
4424	* on error.
4425	*
4426	* @since 1.15
4427	*/
4428	int
4429	libinput_device_tablet_pad_has_key(struct libinput_device *device,
4430	uint32_t code);
4431
4432	/**
4433	* @ingroup device
4434	*
4435	* Increase the refcount of the device group. A device group will be freed
4436	* whenever the refcount reaches 0. This may happen during
4437	* libinput_dispatch() if all devices of this group were removed from the
4438	* system. A caller must ensure to reference the device group correctly to
4439	* avoid dangling pointers.
4440	*
4441	* @param group A previously obtained device group
4442	* @return The passed device group
4443	*/
4444	struct libinput_device_group *
4445	libinput_device_group_ref(struct libinput_device_group *group);
4446
4447	/**
4448	* @ingroup device
4449	*
4450	* Decrease the refcount of the device group. A device group will be freed
4451	* whenever the refcount reaches 0. This may happen during
4452	* libinput_dispatch() if all devices of this group were removed from the
4453	* system. A caller must ensure to reference the device group correctly to
4454	* avoid dangling pointers.
4455	*
4456	* @param group A previously obtained device group
4457	* @return NULL if the device group was destroyed, otherwise the passed
4458	* device group
4459	*/
4460	struct libinput_device_group *
4461	libinput_device_group_unref(struct libinput_device_group *group);
4462
4463	/**
4464	* @ingroup device
4465	*
4466	* Set caller-specific data associated with this device group. libinput does
4467	* not manage, look at, or modify this data. The caller must ensure the
4468	* data is valid.
4469	*
4470	* @param group A previously obtained device group
4471	* @param user_data Caller-specific data pointer
4472	* @see libinput_device_group_get_user_data
4473	*/
4474	void
4475	libinput_device_group_set_user_data(struct libinput_device_group *group,
4476	void *user_data);
4477
4478	/**
4479	* @ingroup device
4480	*
4481	* Get the caller-specific data associated with this input device group, if
4482	* any.
4483	*
4484	* @param group A previously obtained group
4485	* @return Caller-specific data pointer or NULL if none was set
4486	* @see libinput_device_group_set_user_data
4487	*/
4488	void *
4489	libinput_device_group_get_user_data(struct libinput_device_group *group);
4490
4491	/**
4492	* @defgroup config Device configuration
4493	*
4494	* Enable, disable, change and/or check for device-specific features. For
4495	* all features, libinput assigns a default based on the hardware
4496	* configuration. This default can be obtained with the respective
4497	* get_default call.
4498	*
4499	* Configuration options are device dependent and not all options are
4500	* supported on all devices. For all configuration options, libinput
4501	* provides a call to check if a configuration option is available on a
4502	* device (e.g. libinput_device_config_calibration_has_matrix())
4503	*
4504	* Some configuration option may be dependent on or mutually exclusive with
4505	* with other options. The behavior in those cases is
4506	* implementation-dependent, the caller must ensure that the options are set
4507	* in the right order.
4508	*
4509	* Below is a general grouping of configuration options according to device
4510	* type. Note that this is a guide only and not indicative of any specific
4511	* device.
4512	* - Touchpad:
4513	* - libinput_device_config_tap_set_enabled()
4514	* - libinput_device_config_tap_set_drag_enabled()
4515	* - libinput_device_config_tap_set_drag_lock_enabled()
4516	* - libinput_device_config_click_set_method()
4517	* - libinput_device_config_scroll_set_method()
4518	* - libinput_device_config_dwt_set_enabled()
4519	* - Touchscreens:
4520	* - libinput_device_config_calibration_set_matrix()
4521	* - Pointer devices (mice, trackballs, touchpads):
4522	* - libinput_device_config_accel_set_speed()
4523	* - libinput_device_config_accel_set_profile()
4524	* - libinput_device_config_scroll_set_natural_scroll_enabled()
4525	* - libinput_device_config_left_handed_set()
4526	* - libinput_device_config_middle_emulation_set_enabled()
4527	* - libinput_device_config_rotation_set_angle()
4528	* - All devices:
4529	* - libinput_device_config_send_events_set_mode()
4530	*/
4531
4532	/**
4533	* @ingroup config
4534	*
4535	* Status codes returned when applying configuration settings.
4536	*/
4537	enum libinput_config_status {
4538	LIBINPUT_CONFIG_STATUS_SUCCESS = 0, /**< Config applied successfully */
4539	LIBINPUT_CONFIG_STATUS_UNSUPPORTED, /**< Configuration not available on
4540	this device */
4541	LIBINPUT_CONFIG_STATUS_INVALID, /**< Invalid parameter range */
4542	};
4543
4544	/**
4545	* @ingroup config
4546	*
4547	* Return a string describing the error.
4548	*
4549	* @param status The status to translate to a string
4550	* @return A human-readable string representing the error or NULL for an
4551	* invalid status.
4552	*/
4553	const char *
4554	libinput_config_status_to_str(enum libinput_config_status status);
4555
4556	/**
4557	* @ingroup config
4558	*/
4559	enum libinput_config_tap_state {
4560	LIBINPUT_CONFIG_TAP_DISABLED, /**< Tapping is to be disabled, or is
4561	currently disabled */
4562	LIBINPUT_CONFIG_TAP_ENABLED, /**< Tapping is to be enabled, or is
4563	currently enabled */
4564	};
4565
4566	/**
4567	* @ingroup config
4568	*
4569	* Check if the device supports tap-to-click and how many fingers can be
4570	* used for tapping. See
4571	* libinput_device_config_tap_set_enabled() for more information.
4572	*
4573	* @param device The device to configure
4574	* @return The number of fingers that can generate a tap event, or 0 if the
4575	* device does not support tapping.
4576	*
4577	* @see libinput_device_config_tap_set_enabled
4578	* @see libinput_device_config_tap_get_enabled
4579	* @see libinput_device_config_tap_get_default_enabled
4580	*/
4581	int
4582	libinput_device_config_tap_get_finger_count(struct libinput_device *device);
4583
4584	/**
4585	* @ingroup config
4586	*
4587	* Enable or disable tap-to-click on this device, with a default mapping of
4588	* 1, 2, 3 finger tap mapping to left, right, middle click, respectively.
4589	* Tapping is limited by the number of simultaneous touches
4590	* supported by the device, see
4591	* libinput_device_config_tap_get_finger_count().
4592	*
4593	* @param device The device to configure
4594	* @param enable @ref LIBINPUT_CONFIG_TAP_ENABLED to enable tapping or @ref
4595	* LIBINPUT_CONFIG_TAP_DISABLED to disable tapping
4596	*
4597	* @return A config status code. Disabling tapping on a device that does not
4598	* support tapping always succeeds.
4599	*
4600	* @see libinput_device_config_tap_get_finger_count
4601	* @see libinput_device_config_tap_get_enabled
4602	* @see libinput_device_config_tap_get_default_enabled
4603	*/
4604	enum libinput_config_status
4605	libinput_device_config_tap_set_enabled(struct libinput_device *device,
4606	enum libinput_config_tap_state enable);
4607
4608	/**
4609	* @ingroup config
4610	*
4611	* Check if tap-to-click is enabled on this device. If the device does not
4612	* support tapping, this function always returns @ref
4613	* LIBINPUT_CONFIG_TAP_DISABLED.
4614	*
4615	* @param device The device to configure
4616	*
4617	* @retval LIBINPUT_CONFIG_TAP_ENABLED If tapping is currently enabled
4618	* @retval LIBINPUT_CONFIG_TAP_DISABLED If tapping is currently disabled
4619	*
4620	* @see libinput_device_config_tap_get_finger_count
4621	* @see libinput_device_config_tap_set_enabled
4622	* @see libinput_device_config_tap_get_default_enabled
4623	*/
4624	enum libinput_config_tap_state
4625	libinput_device_config_tap_get_enabled(struct libinput_device *device);
4626
4627	/**
4628	* @ingroup config
4629	*
4630	* Return the default setting for whether tap-to-click is enabled on this
4631	* device.
4632	*
4633	* @param device The device to configure
4634	* @retval LIBINPUT_CONFIG_TAP_ENABLED If tapping is enabled by default
4635	* @retval LIBINPUT_CONFIG_TAP_DISABLED If tapping Is disabled by default
4636	*
4637	* @see libinput_device_config_tap_get_finger_count
4638	* @see libinput_device_config_tap_set_enabled
4639	* @see libinput_device_config_tap_get_enabled
4640	*/
4641	enum libinput_config_tap_state
4642	libinput_device_config_tap_get_default_enabled(struct libinput_device *device);
4643
4644	/**
4645	* @ingroup config
4646	*
4647	* @since 1.5
4648	*/
4649	enum libinput_config_tap_button_map {
4650	/** 1/2/3 finger tap maps to left/right/middle */
4651	LIBINPUT_CONFIG_TAP_MAP_LRM,
4652	/** 1/2/3 finger tap maps to left/middle/right*/
4653	LIBINPUT_CONFIG_TAP_MAP_LMR,
4654	};
4655
4656	/**
4657	* @ingroup config
4658	*
4659	* Set the finger number to button number mapping for tap-to-click. The
4660	* default mapping on most devices is to have a 1, 2 and 3 finger tap to map
4661	* to the left, right and middle button, respectively.
4662	* A device may permit changing the button mapping but disallow specific
4663	* maps. In this case @ref LIBINPUT_CONFIG_STATUS_UNSUPPORTED is returned,
4664	* the caller is expected to handle this case correctly.
4665	*
4666	* Changing the button mapping may not take effect immediately,
4667	* the device may wait until it is in a neutral state before applying any
4668	* changes.
4669	*
4670	* The mapping may be changed when tap-to-click is disabled. The new mapping
4671	* takes effect when tap-to-click is enabled in the future.
4672	*
4673	* @note It is an application bug to call this function for devices where
4674	* libinput_device_config_tap_get_finger_count() returns 0.
4675	*
4676	* @param device The device to configure
4677	* @param map The new finger-to-button number mapping
4678	* @return A config status code. Changing the order on a device that does not
4679	* support tapping always fails with @ref LIBINPUT_CONFIG_STATUS_UNSUPPORTED.
4680	*
4681	* @see libinput_device_config_tap_get_button_map
4682	* @see libinput_device_config_tap_get_default_button_map
4683	*
4684	* @since 1.5
4685	*/
4686	enum libinput_config_status
4687	libinput_device_config_tap_set_button_map(struct libinput_device *device,
4688	enum libinput_config_tap_button_map map);
4689
4690	/**
4691	* @ingroup config
4692	*
4693	* Get the finger number to button number mapping for tap-to-click.
4694	*
4695	* The return value for a device that does not support tapping is always
4696	* @ref LIBINPUT_CONFIG_TAP_MAP_LRM.
4697	*
4698	* @note It is an application bug to call this function for devices where
4699	* libinput_device_config_tap_get_finger_count() returns 0.
4700	*
4701	* @param device The device to configure
4702	* @return The current finger-to-button number mapping
4703	*
4704	* @see libinput_device_config_tap_set_button_map
4705	* @see libinput_device_config_tap_get_default_button_map
4706	*
4707	* @since 1.5
4708	*/
4709	enum libinput_config_tap_button_map
4710	libinput_device_config_tap_get_button_map(struct libinput_device *device);
4711
4712	/**
4713	* @ingroup config
4714	*
4715	* Get the default finger number to button number mapping for tap-to-click.
4716	*
4717	* The return value for a device that does not support tapping is always
4718	* @ref LIBINPUT_CONFIG_TAP_MAP_LRM.
4719	*
4720	* @note It is an application bug to call this function for devices where
4721	* libinput_device_config_tap_get_finger_count() returns 0.
4722	*
4723	* @param device The device to configure
4724	* @return The current finger-to-button number mapping
4725	*
4726	* @see libinput_device_config_tap_set_button_map
4727	* @see libinput_device_config_tap_get_default_button_map
4728	*
4729	* @since 1.5
4730	*/
4731	enum libinput_config_tap_button_map
4732	libinput_device_config_tap_get_default_button_map(struct libinput_device *device);
4733
4734	/**
4735	* @ingroup config
4736	*
4737	* A config status to distinguish or set dragging on a device. Currently
4738	* implemented for tap-and-drag only, see
4739	* libinput_device_config_tap_set_drag_enabled()
4740	*
4741	* @since 1.2
4742	*/
4743	enum libinput_config_drag_state {
4744	/**
4745	* Drag is to be disabled, or is
4746	* currently disabled.
4747	*/
4748	LIBINPUT_CONFIG_DRAG_DISABLED,
4749	/**
4750	* Drag is to be enabled, or is
4751	* currently enabled
4752	*/
4753	LIBINPUT_CONFIG_DRAG_ENABLED,
4754	};
4755
4756	/**
4757	* @ingroup config
4758	*
4759	* Enable or disable tap-and-drag on this device. When enabled, a
4760	* tap immediately followed by a finger down results in a button down event,
4761	* subsequent finger motion thus triggers a drag. The button is released
4762	* on finger up. See the libinput documentation for more details.
4763	*
4764	* @param device The device to configure
4765	* @param enable @ref LIBINPUT_CONFIG_DRAG_ENABLED to enable, @ref
4766	* LIBINPUT_CONFIG_DRAG_DISABLED to disable tap-and-drag
4767	*
4768	* @see libinput_device_config_tap_drag_get_enabled
4769	* @see libinput_device_config_tap_drag_get_default_enabled
4770	*
4771	* @since 1.2
4772	*/
4773	enum libinput_config_status
4774	libinput_device_config_tap_set_drag_enabled(struct libinput_device *device,
4775	enum libinput_config_drag_state enable);
4776
4777	/**
4778	* @ingroup config
4779	*
4780	* Return whether tap-and-drag is enabled or disabled on this device.
4781	*
4782	* @param device The device to check
4783	* @retval LIBINPUT_CONFIG_DRAG_ENABLED if tap-and-drag is enabled
4784	* @retval LIBINPUT_CONFIG_DRAG_DISABLED if tap-and-drag is
4785	* disabled
4786	*
4787	* @see libinput_device_config_tap_drag_set_enabled
4788	* @see libinput_device_config_tap_drag_get_default_enabled
4789	*
4790	* @since 1.2
4791	*/
4792	enum libinput_config_drag_state
4793	libinput_device_config_tap_get_drag_enabled(struct libinput_device *device);
4794
4795	/**
4796	* @ingroup config
4797	*
4798	* Return whether tap-and-drag is enabled or disabled by default on this
4799	* device.
4800	*
4801	* @param device The device to check
4802	* @retval LIBINPUT_CONFIG_DRAG_ENABLED if tap-and-drag is enabled by
4803	* default
4804	* @retval LIBINPUT_CONFIG_DRAG_DISABLED if tap-and-drag is
4805	* disabled by default
4806	*
4807	* @see libinput_device_config_tap_drag_set_enabled
4808	* @see libinput_device_config_tap_drag_get_enabled
4809	*
4810	* @since 1.2
4811	*/
4812	enum libinput_config_drag_state
4813	libinput_device_config_tap_get_default_drag_enabled(struct libinput_device *device);
4814
4815	/**
4816	* @ingroup config
4817	*/
4818	enum libinput_config_drag_lock_state {
4819	/** Drag lock is to be disabled, or is currently disabled */
4820	LIBINPUT_CONFIG_DRAG_LOCK_DISABLED,
4821	/** Drag lock is to be enabled, or is currently disabled */
4822	LIBINPUT_CONFIG_DRAG_LOCK_ENABLED,
4823	};
4824
4825	/**
4826	* @ingroup config
4827	*
4828	* Enable or disable drag-lock during tapping on this device. When enabled,
4829	* a finger may be lifted and put back on the touchpad within a timeout and
4830	* the drag process continues. When disabled, lifting the finger during a
4831	* tap-and-drag will immediately stop the drag. See the libinput
4832	* documentation for more details.
4833	*
4834	* Enabling drag lock on a device that has tapping disabled is permitted,
4835	* but has no effect until tapping is enabled.
4836	*
4837	* @param device The device to configure
4838	* @param enable @ref LIBINPUT_CONFIG_DRAG_LOCK_ENABLED to enable drag lock
4839	* or @ref LIBINPUT_CONFIG_DRAG_LOCK_DISABLED to disable drag lock
4840	*
4841	* @return A config status code. Disabling drag lock on a device that does not
4842	* support tapping always succeeds.
4843	*
4844	* @see libinput_device_config_tap_get_drag_lock_enabled
4845	* @see libinput_device_config_tap_get_default_drag_lock_enabled
4846	*/
4847	enum libinput_config_status
4848	libinput_device_config_tap_set_drag_lock_enabled(struct libinput_device *device,
4849	enum libinput_config_drag_lock_state enable);
4850
4851	/**
4852	* @ingroup config
4853	*
4854	* Check if drag-lock during tapping is enabled on this device. If the
4855	* device does not support tapping, this function always returns
4856	* @ref LIBINPUT_CONFIG_DRAG_LOCK_DISABLED.
4857	*
4858	* Drag lock may be enabled even when tapping is disabled.
4859	*
4860	* @param device The device to configure
4861	*
4862	* @retval LIBINPUT_CONFIG_DRAG_LOCK_ENABLED If drag lock is currently enabled
4863	* @retval LIBINPUT_CONFIG_DRAG_LOCK_DISABLED If drag lock is currently disabled
4864	*
4865	* @see libinput_device_config_tap_set_drag_lock_enabled
4866	* @see libinput_device_config_tap_get_default_drag_lock_enabled
4867	*/
4868	enum libinput_config_drag_lock_state
4869	libinput_device_config_tap_get_drag_lock_enabled(struct libinput_device *device);
4870
4871	/**
4872	* @ingroup config
4873	*
4874	* Check if drag-lock during tapping is enabled by default on this device.
4875	* If the device does not support tapping, this function always returns
4876	* @ref LIBINPUT_CONFIG_DRAG_LOCK_DISABLED.
4877	*
4878	* Drag lock may be enabled by default even when tapping is disabled by
4879	* default.
4880	*
4881	* @param device The device to configure
4882	*
4883	* @retval LIBINPUT_CONFIG_DRAG_LOCK_ENABLED If drag lock is enabled by
4884	* default
4885	* @retval LIBINPUT_CONFIG_DRAG_LOCK_DISABLED If drag lock is disabled by
4886	* default
4887	*
4888	* @see libinput_device_config_tap_set_drag_lock_enabled
4889	* @see libinput_device_config_tap_get_drag_lock_enabled
4890	*/
4891	enum libinput_config_drag_lock_state
4892	libinput_device_config_tap_get_default_drag_lock_enabled(struct libinput_device *device);
4893
4894	/**
4895	* @ingroup config
4896	*
4897	* Check if the device can be calibrated via a calibration matrix.
4898	*
4899	* @param device The device to check
4900	* @return Non-zero if the device can be calibrated, zero otherwise.
4901	*
4902	* @see libinput_device_config_calibration_set_matrix
4903	* @see libinput_device_config_calibration_get_matrix
4904	* @see libinput_device_config_calibration_get_default_matrix
4905	*/
4906	int
4907	libinput_device_config_calibration_has_matrix(struct libinput_device *device);
4908
4909	/**
4910	* @ingroup config
4911	*
4912	* Apply the 3x3 transformation matrix to absolute device coordinates. This
4913	* matrix has no effect on relative events.
4914	*
4915	* Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
4916	* @code
4917	* [ a b c ] [ x ]
4918	* [ d e f ] * [ y ]
4919	* [ 0 0 1 ] [ 1 ]
4920	* @endcode
4921	*
4922	* The translation component (c, f) is expected to be normalized to the
4923	* device coordinate range. For example, the matrix
4924	* @code
4925	* [ 1 0 1 ]
4926	* [ 0 1 -1 ]
4927	* [ 0 0 1 ]
4928	* @endcode
4929	* moves all coordinates by 1 device-width to the right and 1 device-height
4930	* up.
4931	*
4932	* The rotation matrix for rotation around the origin is defined as
4933	* @code
4934	* [ cos(a) -sin(a) 0 ]
4935	* [ sin(a) cos(a) 0 ]
4936	* [ 0 0 1 ]
4937	* @endcode
4938	* Note that any rotation requires an additional translation component to
4939	* translate the rotated coordinates back into the original device space.
4940	* The rotation matrixes for 90, 180 and 270 degrees clockwise are:
4941	* @code
4942	* 90 deg cw: 180 deg cw: 270 deg cw:
4943	* [ 0 -1 1] [ -1 0 1] [ 0 1 0 ]
4944	* [ 1 0 0] [ 0 -1 1] [ -1 0 1 ]
4945	* [ 0 0 1] [ 0 0 1] [ 0 0 1 ]
4946	* @endcode
4947	*
4948	* @param device The device to configure
4949	* @param matrix An array representing the first two rows of a 3x3 matrix as
4950	* described above.
4951	*
4952	* @return A config status code.
4953	*
4954	* @see libinput_device_config_calibration_has_matrix
4955	* @see libinput_device_config_calibration_get_matrix
4956	* @see libinput_device_config_calibration_get_default_matrix
4957	*/
4958	enum libinput_config_status
4959	libinput_device_config_calibration_set_matrix(struct libinput_device *device,
4960	const float matrix[6]);
4961
4962	/**
4963	* @ingroup config
4964	*
4965	* Return the current calibration matrix for this device.
4966	*
4967	* @param device The device to configure
4968	* @param matrix Set to the array representing the first two rows of a 3x3 matrix as
4969	* described in libinput_device_config_calibration_set_matrix().
4970	*
4971	* @return 0 if no calibration is set and the returned matrix is the
4972	* identity matrix, 1 otherwise
4973	*
4974	* @see libinput_device_config_calibration_has_matrix
4975	* @see libinput_device_config_calibration_set_matrix
4976	* @see libinput_device_config_calibration_get_default_matrix
4977	*/
4978	int
4979	libinput_device_config_calibration_get_matrix(struct libinput_device *device,
4980	float matrix[6]);
4981
4982	/**
4983	* @ingroup config
4984	*
4985	* Return the default calibration matrix for this device. On most devices,
4986	* this is the identity matrix. If the udev property
4987	* <b>LIBINPUT_CALIBRATION_MATRIX</b> is set on the respective udev device,
4988	* that property's value becomes the default matrix, see the libinput
4989	* documentation for more details.
4990	*
4991	* @param device The device to configure
4992	* @param matrix Set to the array representing the first two rows of a 3x3 matrix as
4993	* described in libinput_device_config_calibration_set_matrix().
4994	*
4995	* @return 0 if no calibration is set and the returned matrix is the
4996	* identity matrix, 1 otherwise
4997	*
4998	* @see libinput_device_config_calibration_has_matrix
4999	* @see libinput_device_config_calibration_set_matrix
5000	* @see libinput_device_config_calibration_get_matrix
5001	*/
5002	int
5003	libinput_device_config_calibration_get_default_matrix(struct libinput_device *device,
5004	float matrix[6]);
5005
5006	/**
5007	* @ingroup config
5008	*
5009	* The send-event mode of a device defines when a device may generate events
5010	* and pass those events to the caller.
5011	*/
5012	enum libinput_config_send_events_mode {
5013	/**
5014	* Send events from this device normally. This is a placeholder
5015	* mode only, any device detected by libinput can be enabled. Do not
5016	* test for this value as bitmask.
5017	*/
5018	LIBINPUT_CONFIG_SEND_EVENTS_ENABLED = 0,
5019	/**
5020	* Do not send events through this device. Depending on the device,
5021	* this may close all file descriptors on the device or it may leave
5022	* the file descriptors open and route events through a different
5023	* device.
5024	*
5025	* If this bit field is set, other disable modes may be
5026	* ignored. For example, if both @ref
5027	* LIBINPUT_CONFIG_SEND_EVENTS_DISABLED and @ref
5028	* LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE are set,
5029	* the device remains disabled when all external pointer devices are
5030	* unplugged.
5031	*/
5032	LIBINPUT_CONFIG_SEND_EVENTS_DISABLED = (1 << 0),
5033	/**
5034	* If an external pointer device is plugged in, do not send events
5035	* from this device. This option may be available on built-in
5036	* touchpads.
5037	*/
5038	LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE = (1 << 1),
5039	};
5040
5041	/**
5042	* @ingroup config
5043	*
5044	* Return the possible send-event modes for this device. These modes define
5045	* when a device may process and send events.
5046	*
5047	* @param device The device to configure
5048	*
5049	* @return A bitmask of possible modes.
5050	*
5051	* @see libinput_device_config_send_events_set_mode
5052	* @see libinput_device_config_send_events_get_mode
5053	* @see libinput_device_config_send_events_get_default_mode
5054	*/
5055	uint32_t
5056	libinput_device_config_send_events_get_modes(struct libinput_device *device);
5057
5058	/**
5059	* @ingroup config
5060	*
5061	* Set the send-event mode for this device. The mode defines when the device
5062	* processes and sends events to the caller.
5063	*
5064	* The selected mode may not take effect immediately. Events already
5065	* received and processed from this device are unaffected and will be passed
5066	* to the caller on the next call to libinput_get_event().
5067	*
5068	* If the mode is a bitmask of @ref libinput_config_send_events_mode,
5069	* the device may wait for or generate events until it is in a neutral
5070	* state. For example, this may include waiting for or generating button
5071	* release events.
5072	*
5073	* If the device is already suspended, this function does nothing and
5074	* returns success. Changing the send-event mode on a device that has been
5075	* removed is permitted.
5076	*
5077	* @param device The device to configure
5078	* @param mode A bitmask of send-events modes
5079	*
5080	* @return A config status code.
5081	*
5082	* @see libinput_device_config_send_events_get_modes
5083	* @see libinput_device_config_send_events_get_mode
5084	* @see libinput_device_config_send_events_get_default_mode
5085	*/
5086	enum libinput_config_status
5087	libinput_device_config_send_events_set_mode(struct libinput_device *device,
5088	uint32_t mode);
5089
5090	/**
5091	* @ingroup config
5092	*
5093	* Get the send-event mode for this device. The mode defines when the device
5094	* processes and sends events to the caller.
5095	*
5096	* If a caller enables the bits for multiple modes, some of which are
5097	* subsets of another mode libinput may drop the bits that are subsets. In
5098	* other words, don't expect libinput_device_config_send_events_get_mode()
5099	* to always return exactly the same bitmask as passed into
5100	* libinput_device_config_send_events_set_mode().
5101	*
5102	* @param device The device to configure
5103	* @return The current bitmask of the send-event mode for this device.
5104	*
5105	* @see libinput_device_config_send_events_get_modes
5106	* @see libinput_device_config_send_events_set_mode
5107	* @see libinput_device_config_send_events_get_default_mode
5108	*/
5109	uint32_t
5110	libinput_device_config_send_events_get_mode(struct libinput_device *device);
5111
5112	/**
5113	* @ingroup config
5114	*
5115	* Get the default send-event mode for this device. The mode defines when
5116	* the device processes and sends events to the caller.
5117	*
5118	* @param device The device to configure
5119	* @return The bitmask of the send-event mode for this device.
5120	*
5121	* @see libinput_device_config_send_events_get_modes
5122	* @see libinput_device_config_send_events_set_mode
5123	* @see libinput_device_config_send_events_get_mode
5124	*/
5125	uint32_t
5126	libinput_device_config_send_events_get_default_mode(struct libinput_device *device);
5127
5128	/**
5129	* @ingroup config
5130	*
5131	* Check if a device uses libinput-internal pointer-acceleration.
5132	*
5133	* @param device The device to configure
5134	*
5135	* @return 0 if the device is not accelerated, nonzero if it is accelerated
5136	*
5137	* @see libinput_device_config_accel_set_speed
5138	* @see libinput_device_config_accel_get_speed
5139	* @see libinput_device_config_accel_get_default_speed
5140	*/
5141	int
5142	libinput_device_config_accel_is_available(struct libinput_device *device);
5143
5144	/**
5145	* @ingroup config
5146	*
5147	* Set the pointer acceleration speed of this pointer device within a range
5148	* of [-1, 1], where 0 is the default acceleration for this device, -1 is
5149	* the slowest acceleration and 1 is the maximum acceleration available on
5150	* this device. The actual pointer acceleration mechanism is
5151	* implementation-dependent, as is the number of steps available within the
5152	* range. libinput picks the semantically closest acceleration step if the
5153	* requested value does not match a discrete setting.
5154	*
5155	* @param device The device to configure
5156	* @param speed The normalized speed, in a range of [-1, 1]
5157	*
5158	* @return A config status code
5159	*
5160	* @see libinput_device_config_accel_is_available
5161	* @see libinput_device_config_accel_get_speed
5162	* @see libinput_device_config_accel_get_default_speed
5163	*/
5164	enum libinput_config_status
5165	libinput_device_config_accel_set_speed(struct libinput_device *device,
5166	double speed);
5167
5168	/**
5169	* @ingroup config
5170	*
5171	* Get the current pointer acceleration setting for this pointer device. The
5172	* returned value is normalized to a range of [-1, 1].
5173	* See libinput_device_config_accel_set_speed() for details.
5174	*
5175	* @param device The device to configure
5176	*
5177	* @return The current speed, range -1 to 1
5178	*
5179	* @see libinput_device_config_accel_is_available
5180	* @see libinput_device_config_accel_set_speed
5181	* @see libinput_device_config_accel_get_default_speed
5182	*/
5183	double
5184	libinput_device_config_accel_get_speed(struct libinput_device *device);
5185
5186	/**
5187	* @ingroup config
5188	*
5189	* Return the default speed setting for this device, normalized to a range
5190	* of [-1, 1].
5191	* See libinput_device_config_accel_set_speed() for details.
5192	*
5193	* @param device The device to configure
5194	* @return The default speed setting for this device.
5195	*
5196	* @see libinput_device_config_accel_is_available
5197	* @see libinput_device_config_accel_set_speed
5198	* @see libinput_device_config_accel_get_speed
5199	*/
5200	double
5201	libinput_device_config_accel_get_default_speed(struct libinput_device *device);
5202
5203	/**
5204	* @ingroup config
5205	*
5206	* @since 1.1
5207	*/
5208	enum libinput_config_accel_profile {
5209	/**
5210	* Placeholder for devices that don't have a configurable pointer
5211	* acceleration profile.
5212	*/
5213	LIBINPUT_CONFIG_ACCEL_PROFILE_NONE = 0,
5214	/**
5215	* A flat acceleration profile. Pointer motion is accelerated by a
5216	* constant (device-specific) factor, depending on the current
5217	* speed.
5218	*
5219	* @see libinput_device_config_accel_set_speed
5220	*/
5221	LIBINPUT_CONFIG_ACCEL_PROFILE_FLAT = (1 << 0),
5222
5223	/**
5224	* An adaptive acceleration profile. Pointer acceleration depends
5225	* on the input speed. This is the default profile for most devices.
5226	*/
5227	LIBINPUT_CONFIG_ACCEL_PROFILE_ADAPTIVE = (1 << 1),
5228	};
5229
5230	/**
5231	* @ingroup config
5232	*
5233	* Returns a bitmask of the configurable acceleration modes available on
5234	* this device.
5235	*
5236	* @param device The device to configure
5237	*
5238	* @return A bitmask of all configurable modes available on this device.
5239	*
5240	* @since 1.1
5241	*/
5242	uint32_t
5243	libinput_device_config_accel_get_profiles(struct libinput_device *device);
5244
5245	/**
5246	* @ingroup config
5247	*
5248	* Set the pointer acceleration profile of this pointer device to the given
5249	* mode.
5250	*
5251	* @param device The device to configure
5252	* @param profile The profile to set the device to.
5253	*
5254	* @return A config status code
5255	*
5256	* @since 1.1
5257	*/
5258	enum libinput_config_status
5259	libinput_device_config_accel_set_profile(struct libinput_device *device,
5260	enum libinput_config_accel_profile profile);
5261
5262	/**
5263	* @ingroup config
5264	*
5265	* Get the current pointer acceleration profile for this pointer device.
5266	*
5267	* @param device The device to configure
5268	*
5269	* @return The currently configured pointer acceleration profile.
5270	*
5271	* @since 1.1
5272	*/
5273	enum libinput_config_accel_profile
5274	libinput_device_config_accel_get_profile(struct libinput_device *device);
5275
5276	/**
5277	* @ingroup config
5278	*
5279	* Return the default pointer acceleration profile for this pointer device.
5280	*
5281	* @param device The device to configure
5282	*
5283	* @return The default acceleration profile for this device.
5284	*
5285	* @since 1.1
5286	*/
5287	enum libinput_config_accel_profile
5288	libinput_device_config_accel_get_default_profile(struct libinput_device *device);
5289
5290	/**
5291	* @ingroup config
5292	*
5293	* Return non-zero if the device supports "natural scrolling".
5294	*
5295	* In traditional scroll mode, the movement of fingers on a touchpad when
5296	* scrolling matches the movement of the scroll bars. When the fingers move
5297	* down, the scroll bar moves down, a line of text on the screen moves
5298	* towards the upper end of the screen. This also matches scroll wheels on
5299	* mice (wheel down, content moves up).
5300	*
5301	* Natural scrolling is the term coined by Apple for inverted scrolling.
5302	* In this mode, the effect of scrolling movement of fingers on a touchpad
5303	* resemble physical manipulation of paper. When the fingers move down, a
5304	* line of text on the screen moves down (scrollbars move up). This is the
5305	* opposite of scroll wheels on mice.
5306	*
5307	* A device supporting natural scrolling can be switched between traditional
5308	* scroll mode and natural scroll mode.
5309	*
5310	* @param device The device to configure
5311	*
5312	* @return Zero if natural scrolling is not supported, non-zero if natural
5313	* scrolling is supported by this device
5314	*
5315	* @see libinput_device_config_scroll_set_natural_scroll_enabled
5316	* @see libinput_device_config_scroll_get_natural_scroll_enabled
5317	* @see libinput_device_config_scroll_get_default_natural_scroll_enabled
5318	*/
5319	int
5320	libinput_device_config_scroll_has_natural_scroll(struct libinput_device *device);
5321
5322	/**
5323	* @ingroup config
5324	*
5325	* Enable or disable natural scrolling on the device.
5326	*
5327	* @param device The device to configure
5328	* @param enable non-zero to enable, zero to disable natural scrolling
5329	*
5330	* @return A config status code
5331	*
5332	* @see libinput_device_config_scroll_has_natural_scroll
5333	* @see libinput_device_config_scroll_get_natural_scroll_enabled
5334	* @see libinput_device_config_scroll_get_default_natural_scroll_enabled
5335	*/
5336	enum libinput_config_status
5337	libinput_device_config_scroll_set_natural_scroll_enabled(struct libinput_device *device,
5338	int enable);
5339	/**
5340	* @ingroup config
5341	*
5342	* Get the current mode for scrolling on this device
5343	*
5344	* @param device The device to configure
5345	*
5346	* @return Zero if natural scrolling is disabled, non-zero if enabled
5347	*
5348	* @see libinput_device_config_scroll_has_natural_scroll
5349	* @see libinput_device_config_scroll_set_natural_scroll_enabled
5350	* @see libinput_device_config_scroll_get_default_natural_scroll_enabled
5351	*/
5352	int
5353	libinput_device_config_scroll_get_natural_scroll_enabled(struct libinput_device *device);
5354
5355	/**
5356	* @ingroup config
5357	*
5358	* Get the default mode for scrolling on this device
5359	*
5360	* @param device The device to configure
5361	*
5362	* @return Zero if natural scrolling is disabled by default, non-zero if enabled
5363	*
5364	* @see libinput_device_config_scroll_has_natural_scroll
5365	* @see libinput_device_config_scroll_set_natural_scroll_enabled
5366	* @see libinput_device_config_scroll_get_natural_scroll_enabled
5367	*/
5368	int
5369	libinput_device_config_scroll_get_default_natural_scroll_enabled(struct libinput_device *device);
5370
5371	/**
5372	* @ingroup config
5373	*
5374	* Check if a device has a configuration that supports left-handed usage.
5375	*
5376	* @param device The device to configure
5377	* @return Non-zero if the device can be set to left-handed, or zero
5378	* otherwise
5379	*
5380	* @see libinput_device_config_left_handed_set
5381	* @see libinput_device_config_left_handed_get
5382	* @see libinput_device_config_left_handed_get_default
5383	*/
5384	int
5385	libinput_device_config_left_handed_is_available(struct libinput_device *device);
5386
5387	/**
5388	* @ingroup config
5389	*
5390	* Set the left-handed configuration of the device.
5391	*
5392	* The exact behavior is device-dependent. On a mouse and most pointing
5393	* devices, left and right buttons are swapped but the middle button is
5394	* unmodified. On a touchpad, physical buttons (if present) are swapped. On a
5395	* clickpad, the top and bottom software-emulated buttons are swapped where
5396	* present, the main area of the touchpad remains a left button. Tapping and
5397	* clickfinger behavior is not affected by this setting.
5398	*
5399	* Changing the left-handed configuration of a device may not take effect
5400	* until all buttons have been logically released.
5401	*
5402	* @param device The device to configure
5403	* @param left_handed Zero to disable, non-zero to enable left-handed mode
5404	* @return A configuration status code
5405	*
5406	* @see libinput_device_config_left_handed_is_available
5407	* @see libinput_device_config_left_handed_get
5408	* @see libinput_device_config_left_handed_get_default
5409	*/
5410	enum libinput_config_status
5411	libinput_device_config_left_handed_set(struct libinput_device *device,
5412	int left_handed);
5413
5414	/**
5415	* @ingroup config
5416	*
5417	* Get the current left-handed configuration of the device.
5418	*
5419	* @param device The device to configure
5420	* @return Zero if the device is in right-handed mode, non-zero if the
5421	* device is in left-handed mode
5422	*
5423	* @see libinput_device_config_left_handed_is_available
5424	* @see libinput_device_config_left_handed_set
5425	* @see libinput_device_config_left_handed_get_default
5426	*/
5427	int
5428	libinput_device_config_left_handed_get(struct libinput_device *device);
5429
5430	/**
5431	* @ingroup config
5432	*
5433	* Get the default left-handed configuration of the device.
5434	*
5435	* @param device The device to configure
5436	* @return Zero if the device is in right-handed mode by default, or non-zero
5437	* if the device is in left-handed mode by default
5438	*
5439	* @see libinput_device_config_left_handed_is_available
5440	* @see libinput_device_config_left_handed_set
5441	* @see libinput_device_config_left_handed_get
5442	*/
5443	int
5444	libinput_device_config_left_handed_get_default(struct libinput_device *device);
5445
5446	/**
5447	* @ingroup config
5448	*
5449	* The click method defines when to generate software-emulated
5450	* buttons, usually on a device that does not have a specific physical
5451	* button available.
5452	*/
5453	enum libinput_config_click_method {
5454	/**
5455	* Do not send software-emulated button events. This has no effect
5456	* on events generated by physical buttons.
5457	*/
5458	LIBINPUT_CONFIG_CLICK_METHOD_NONE = 0,
5459	/**
5460	* Use software-button areas to generate button events.
5461	*/
5462	LIBINPUT_CONFIG_CLICK_METHOD_BUTTON_AREAS = (1 << 0),
5463	/**
5464	* The number of fingers decides which button press to generate.
5465	*/
5466	LIBINPUT_CONFIG_CLICK_METHOD_CLICKFINGER = (1 << 1),
5467	};
5468
5469	/**
5470	* @ingroup config
5471	*
5472	* Check which button click methods a device supports. The button click
5473	* method defines when to generate software-emulated buttons, usually on a
5474	* device that does not have a specific physical button available.
5475	*
5476	* @param device The device to configure
5477	*
5478	* @return A bitmask of possible methods.
5479	*
5480	* @see libinput_device_config_click_get_methods
5481	* @see libinput_device_config_click_set_method
5482	* @see libinput_device_config_click_get_method
5483	*/
5484	uint32_t
5485	libinput_device_config_click_get_methods(struct libinput_device *device);
5486
5487	/**
5488	* @ingroup config
5489	*
5490	* Set the button click method for this device. The button click
5491	* method defines when to generate software-emulated buttons, usually on a
5492	* device that does not have a specific physical button available.
5493	*
5494	* @note The selected click method may not take effect immediately. The
5495	* device may require changing to a neutral state first before activating
5496	* the new method.
5497	*
5498	* @param device The device to configure
5499	* @param method The button click method
5500	*
5501	* @return A config status code
5502	*
5503	* @see libinput_device_config_click_get_methods
5504	* @see libinput_device_config_click_get_method
5505	* @see libinput_device_config_click_get_default_method
5506	*/
5507	enum libinput_config_status
5508	libinput_device_config_click_set_method(struct libinput_device *device,
5509	enum libinput_config_click_method method);
5510	/**
5511	* @ingroup config
5512	*
5513	* Get the button click method for this device. The button click
5514	* method defines when to generate software-emulated buttons, usually on a
5515	* device that does not have a specific physical button available.
5516	*
5517	* @param device The device to configure
5518	*
5519	* @return The current button click method for this device
5520	*
5521	* @see libinput_device_config_click_get_methods
5522	* @see libinput_device_config_click_set_method
5523	* @see libinput_device_config_click_get_default_method
5524	*/
5525	enum libinput_config_click_method
5526	libinput_device_config_click_get_method(struct libinput_device *device);
5527
5528	/**
5529	* @ingroup config
5530	*
5531	* Get the default button click method for this device. The button click
5532	* method defines when to generate software-emulated buttons, usually on a
5533	* device that does not have a specific physical button available.
5534	*
5535	* @param device The device to configure
5536	*
5537	* @return The default button click method for this device
5538	*
5539	* @see libinput_device_config_click_get_methods
5540	* @see libinput_device_config_click_set_method
5541	* @see libinput_device_config_click_get_method
5542	*/
5543	enum libinput_config_click_method
5544	libinput_device_config_click_get_default_method(struct libinput_device *device);
5545
5546	/**
5547	* @ingroup config
5548	*/
5549	enum libinput_config_middle_emulation_state {
5550	/**
5551	* Middle mouse button emulation is to be disabled, or
5552	* is currently disabled.
5553	*/
5554	LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED,
5555	/**
5556	* Middle mouse button emulation is to be enabled, or
5557	* is currently enabled.
5558	*/
5559	LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED,
5560	};
5561
5562	/**
5563	* @ingroup config
5564	*
5565	* Check if middle mouse button emulation configuration is available on this
5566	* device. See libinput_device_config_middle_emulation_set_enabled() for
5567	* more details.
5568	*
5569	* @note Some devices provide middle mouse button emulation but do not allow
5570	* enabling/disabling that emulation. These devices return zero in
5571	* libinput_device_config_middle_emulation_is_available().
5572	*
5573	* @param device The device to query
5574	*
5575	* @return Non-zero if middle mouse button emulation is available and can be
5576	* configured, zero otherwise.
5577	*
5578	* @see libinput_device_config_middle_emulation_set_enabled
5579	* @see libinput_device_config_middle_emulation_get_enabled
5580	* @see libinput_device_config_middle_emulation_get_default_enabled
5581	*/
5582	int
5583	libinput_device_config_middle_emulation_is_available(
5584	struct libinput_device *device);
5585
5586	/**
5587	* @ingroup config
5588	*
5589	* Enable or disable middle button emulation on this device. When enabled, a
5590	* simultaneous press of the left and right button generates a middle mouse
5591	* button event. Releasing the buttons generates a middle mouse button
5592	* release, the left and right button events are discarded otherwise.
5593	*
5594	* See the libinput documentation for more details.
5595	*
5596	* @param device The device to configure
5597	* @param enable @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED to
5598	* disable, @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED To enable
5599	* middle button emulation.
5600	*
5601	* @return A config status code. Disabling middle button emulation on a
5602	* device that does not support middle button emulation always succeeds.
5603	*
5604	* @see libinput_device_config_middle_emulation_is_available
5605	* @see libinput_device_config_middle_emulation_get_enabled
5606	* @see libinput_device_config_middle_emulation_get_default_enabled
5607	*/
5608	enum libinput_config_status
5609	libinput_device_config_middle_emulation_set_enabled(
5610	struct libinput_device *device,
5611	enum libinput_config_middle_emulation_state enable);
5612
5613	/**
5614	* @ingroup config
5615	*
5616	* Check if configurable middle button emulation is enabled on this device.
5617	* See libinput_device_config_middle_emulation_set_enabled() for more
5618	* details.
5619	*
5620	* If the device does not have configurable middle button emulation, this
5621	* function returns @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.
5622	*
5623	* @note Some devices provide middle mouse button emulation but do not allow
5624	* enabling/disabling that emulation. These devices always return @ref
5625	* LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.
5626	*
5627	* @param device The device to configure
5628	* @return @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED if disabled
5629	* or not available/configurable, @ref
5630	* LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED If enabled.
5631	*
5632	* @see libinput_device_config_middle_emulation_is_available
5633	* @see libinput_device_config_middle_emulation_set_enabled
5634	* @see libinput_device_config_middle_emulation_get_default_enabled
5635	*/
5636	enum libinput_config_middle_emulation_state
5637	libinput_device_config_middle_emulation_get_enabled(
5638	struct libinput_device *device);
5639
5640	/**
5641	* @ingroup config
5642	*
5643	* Check if configurable middle button emulation is enabled by default on
5644	* this device. See libinput_device_config_middle_emulation_set_enabled()
5645	* for more details.
5646	*
5647	* If the device does not have configurable middle button
5648	* emulation, this function returns @ref
5649	* LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.
5650	*
5651	* @note Some devices provide middle mouse button emulation but do not allow
5652	* enabling/disabling that emulation. These devices always return @ref
5653	* LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.
5654	*
5655	* @param device The device to configure
5656	* @return @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED If disabled
5657	* or not available, @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED if
5658	* enabled.
5659	*
5660	* @see libinput_device_config_middle_emulation_is_available
5661	* @see libinput_device_config_middle_emulation_set_enabled
5662	* @see libinput_device_config_middle_emulation_get_enabled
5663	*/
5664	enum libinput_config_middle_emulation_state
5665	libinput_device_config_middle_emulation_get_default_enabled(
5666	struct libinput_device *device);
5667
5668	/**
5669	* @ingroup config
5670	*
5671	* The scroll method of a device selects when to generate scroll axis events
5672	* instead of pointer motion events.
5673	*/
5674	enum libinput_config_scroll_method {
5675	/**
5676	* Never send scroll events instead of pointer motion events.
5677	* This has no effect on events generated by scroll wheels.
5678	*/
5679	LIBINPUT_CONFIG_SCROLL_NO_SCROLL = 0,
5680	/**
5681	* Send scroll events when two fingers are logically down on the
5682	* device.
5683	*/
5684	LIBINPUT_CONFIG_SCROLL_2FG = (1 << 0),
5685	/**
5686	* Send scroll events when a finger moves along the bottom or
5687	* right edge of a device.
5688	*/
5689	LIBINPUT_CONFIG_SCROLL_EDGE = (1 << 1),
5690	/**
5691	* Send scroll events when a button is down and the device moves
5692	* along a scroll-capable axis.
5693	*/
5694	LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN = (1 << 2),
5695	};
5696
5697	/**
5698	* @ingroup config
5699	*
5700	* Check which scroll methods a device supports. The method defines when to
5701	* generate scroll axis events instead of pointer motion events.
5702	*
5703	* @param device The device to configure
5704	*
5705	* @return A bitmask of possible methods.
5706	*
5707	* @see libinput_device_config_scroll_set_method
5708	* @see libinput_device_config_scroll_get_method
5709	* @see libinput_device_config_scroll_get_default_method
5710	* @see libinput_device_config_scroll_set_button
5711	* @see libinput_device_config_scroll_get_button
5712	* @see libinput_device_config_scroll_get_default_button
5713	*/
5714	uint32_t
5715	libinput_device_config_scroll_get_methods(struct libinput_device *device);
5716
5717	/**
5718	* @ingroup config
5719	*
5720	* Set the scroll method for this device. The method defines when to
5721	* generate scroll axis events instead of pointer motion events.
5722	*
5723	* @note Setting @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN enables
5724	* the scroll method, but scrolling is only activated when the configured
5725	* button is held down. If no button is set, i.e.
5726	* libinput_device_config_scroll_get_button() returns 0, scrolling
5727	* cannot activate.
5728	*
5729	* @param device The device to configure
5730	* @param method The scroll method for this device.
5731	*
5732	* @return A config status code.
5733	*
5734	* @see libinput_device_config_scroll_get_methods
5735	* @see libinput_device_config_scroll_get_method
5736	* @see libinput_device_config_scroll_get_default_method
5737	* @see libinput_device_config_scroll_set_button
5738	* @see libinput_device_config_scroll_get_button
5739	* @see libinput_device_config_scroll_get_default_button
5740	*/
5741	enum libinput_config_status
5742	libinput_device_config_scroll_set_method(struct libinput_device *device,
5743	enum libinput_config_scroll_method method);
5744
5745	/**
5746	* @ingroup config
5747	*
5748	* Get the scroll method for this device. The method defines when to
5749	* generate scroll axis events instead of pointer motion events.
5750	*
5751	* @param device The device to configure
5752	* @return The current scroll method for this device.
5753	*
5754	* @see libinput_device_config_scroll_get_methods
5755	* @see libinput_device_config_scroll_set_method
5756	* @see libinput_device_config_scroll_get_default_method
5757	* @see libinput_device_config_scroll_set_button
5758	* @see libinput_device_config_scroll_get_button
5759	* @see libinput_device_config_scroll_get_default_button
5760	*/
5761	enum libinput_config_scroll_method
5762	libinput_device_config_scroll_get_method(struct libinput_device *device);
5763
5764	/**
5765	* @ingroup config
5766	*
5767	* Get the default scroll method for this device. The method defines when to
5768	* generate scroll axis events instead of pointer motion events.
5769	*
5770	* @param device The device to configure
5771	* @return The default scroll method for this device.
5772	*
5773	* @see libinput_device_config_scroll_get_methods
5774	* @see libinput_device_config_scroll_set_method
5775	* @see libinput_device_config_scroll_get_method
5776	* @see libinput_device_config_scroll_set_button
5777	* @see libinput_device_config_scroll_get_button
5778	* @see libinput_device_config_scroll_get_default_button
5779	*/
5780	enum libinput_config_scroll_method
5781	libinput_device_config_scroll_get_default_method(struct libinput_device *device);
5782
5783	/**
5784	* @ingroup config
5785	*
5786	* Set the button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method
5787	* for this device.
5788	*
5789	* When the current scroll method is set to @ref
5790	* LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN, no button press/release events
5791	* will be send for the configured button.
5792	*
5793	* When the configured button is pressed, any motion events along a
5794	* scroll-capable axis are turned into scroll axis events.
5795	*
5796	* @note Setting the button does not change the scroll method. To change the
5797	* scroll method call libinput_device_config_scroll_set_method().
5798	*
5799	* If the button is 0, button scrolling is effectively disabled.
5800	*
5801	* @param device The device to configure
5802	* @param button The button which when pressed switches to sending scroll events
5803	*
5804	* @return A config status code
5805	* @retval LIBINPUT_CONFIG_STATUS_SUCCESS On success
5806	* @retval LIBINPUT_CONFIG_STATUS_UNSUPPORTED If @ref
5807	* LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN is not supported
5808	* @retval LIBINPUT_CONFIG_STATUS_INVALID The given button does not
5809	* exist on this device
5810	*
5811	* @see libinput_device_config_scroll_get_methods
5812	* @see libinput_device_config_scroll_set_method
5813	* @see libinput_device_config_scroll_get_method
5814	* @see libinput_device_config_scroll_get_default_method
5815	* @see libinput_device_config_scroll_get_button
5816	* @see libinput_device_config_scroll_get_default_button
5817	*/
5818	enum libinput_config_status
5819	libinput_device_config_scroll_set_button(struct libinput_device *device,
5820	uint32_t button);
5821
5822	/**
5823	* @ingroup config
5824	*
5825	* Get the button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method
5826	* for this device.
5827	*
5828	* If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not
5829	* supported, or no button is set, this function returns 0.
5830	*
5831	* @note The return value is independent of the currently selected
5832	* scroll-method. For button scrolling to activate, a device must have the
5833	* @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method enabled, and a non-zero
5834	* button set as scroll button.
5835	*
5836	* @param device The device to configure
5837	* @return The button which when pressed switches to sending scroll events
5838	*
5839	* @see libinput_device_config_scroll_get_methods
5840	* @see libinput_device_config_scroll_set_method
5841	* @see libinput_device_config_scroll_get_method
5842	* @see libinput_device_config_scroll_get_default_method
5843	* @see libinput_device_config_scroll_set_button
5844	* @see libinput_device_config_scroll_get_default_button
5845	*/
5846	uint32_t
5847	libinput_device_config_scroll_get_button(struct libinput_device *device);
5848
5849	/**
5850	* @ingroup config
5851	*
5852	* Get the default button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN
5853	* method for this device.
5854	*
5855	* If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not supported,
5856	* or no default button is set, this function returns 0.
5857	*
5858	* @param device The device to configure
5859	* @return The default button for the @ref
5860	* LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method
5861	*
5862	* @see libinput_device_config_scroll_get_methods
5863	* @see libinput_device_config_scroll_set_method
5864	* @see libinput_device_config_scroll_get_method
5865	* @see libinput_device_config_scroll_get_default_method
5866	* @see libinput_device_config_scroll_set_button
5867	* @see libinput_device_config_scroll_get_button
5868	*/
5869	uint32_t
5870	libinput_device_config_scroll_get_default_button(struct libinput_device *device);
5871
5872	enum libinput_config_scroll_button_lock_state {
5873	LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED,
5874	LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_ENABLED,
5875	};
5876
5877	/**
5878	* @ingroup config
5879	*
5880	* Set the scroll button lock. If the state is
5881	* @ref LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED, the button must
5882	* physically be held down for button scrolling to work.
5883	* If the state is
5884	* @ref LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_ENABLED, the button is considered
5885	* logically down after the first press and release sequence, and logically
5886	* up after the second press and release sequence.
5887	*
5888	* @param device The device to configure
5889	* @param state The state to set the scroll button lock to
5890	*
5891	* @return A config status code. Disabling the scroll button lock on
5892	* device that does not support button scrolling always succeeds.
5893	*
5894	* @see libinput_device_config_scroll_set_button
5895	* @see libinput_device_config_scroll_get_button
5896	* @see libinput_device_config_scroll_get_default_button
5897	*/
5898	enum libinput_config_status
5899	libinput_device_config_scroll_set_button_lock(struct libinput_device *device,
5900	enum libinput_config_scroll_button_lock_state state);
5901
5902	/**
5903	* @ingroup config
5904	*
5905	* Get the current scroll button lock state.
5906	*
5907	* If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not
5908	* supported, or no button is set, this function returns @ref
5909	* LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED.
5910	*
5911	* @note The return value is independent of the currently selected
5912	* scroll-method. For the scroll button lock to activate, a device must have
5913	* the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method enabled, and a
5914	* non-zero button set as scroll button.
5915	*
5916	* @param device The device to configure
5917	* @return The scroll button lock state
5918	*
5919	* @see libinput_device_config_scroll_set_button
5920	* @see libinput_device_config_scroll_set_button_lock
5921	* @see libinput_device_config_scroll_get_button_lock
5922	* @see libinput_device_config_scroll_get_default_button_lock
5923	*/
5924	enum libinput_config_scroll_button_lock_state
5925	libinput_device_config_scroll_get_button_lock(struct libinput_device *device);
5926
5927	/**
5928	* @ingroup config
5929	*
5930	* Get the default scroll button lock state.
5931	*
5932	* If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not
5933	* supported, or no button is set, this function returns @ref
5934	* LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED.
5935	*
5936	* @param device The device to configure
5937	* @return The default scroll button lock state
5938	*
5939	* @see libinput_device_config_scroll_set_button
5940	* @see libinput_device_config_scroll_set_button_lock
5941	* @see libinput_device_config_scroll_get_button_lock
5942	* @see libinput_device_config_scroll_get_default_button_lock
5943	*/
5944	enum libinput_config_scroll_button_lock_state
5945	libinput_device_config_scroll_get_default_button_lock(struct libinput_device *device);
5946
5947	/**
5948	* @ingroup config
5949	*
5950	* Possible states for the disable-while-typing feature.
5951	*/
5952	enum libinput_config_dwt_state {
5953	LIBINPUT_CONFIG_DWT_DISABLED,
5954	LIBINPUT_CONFIG_DWT_ENABLED,
5955	};
5956
5957	/**
5958	* @ingroup config
5959	*
5960	* Check if this device supports configurable disable-while-typing feature.
5961	* This feature is usually available on built-in touchpads and disables the
5962	* touchpad while typing. See the libinput documentation for details.
5963	*
5964	* @param device The device to configure
5965	* @return 0 if this device does not support disable-while-typing, or 1
5966	* otherwise.
5967	*
5968	* @see libinput_device_config_dwt_set_enabled
5969	* @see libinput_device_config_dwt_get_enabled
5970	* @see libinput_device_config_dwt_get_default_enabled
5971	*/
5972	int
5973	libinput_device_config_dwt_is_available(struct libinput_device *device);
5974
5975	/**
5976	* @ingroup config
5977	*
5978	* Enable or disable the disable-while-typing feature. When enabled, the
5979	* device will be disabled while typing and for a short period after. See
5980	* the libinput documentation for details.
5981	*
5982	* @note Enabling or disabling disable-while-typing may not take effect
5983	* immediately.
5984	*
5985	* @param device The device to configure
5986	* @param enable @ref LIBINPUT_CONFIG_DWT_DISABLED to disable
5987	* disable-while-typing, @ref LIBINPUT_CONFIG_DWT_ENABLED to enable
5988	*
5989	* @return A config status code. Disabling disable-while-typing on a
5990	* device that does not support the feature always succeeds.
5991	*
5992	* @see libinput_device_config_dwt_is_available
5993	* @see libinput_device_config_dwt_get_enabled
5994	* @see libinput_device_config_dwt_get_default_enabled
5995	*/
5996	enum libinput_config_status
5997	libinput_device_config_dwt_set_enabled(struct libinput_device *device,
5998	enum libinput_config_dwt_state enable);
5999
6000	/**
6001	* @ingroup config
6002	*
6003	* Check if the disable-while typing feature is currently enabled on this
6004	* device. If the device does not support disable-while-typing, this
6005	* function returns @ref LIBINPUT_CONFIG_DWT_DISABLED.
6006	*
6007	* @param device The device to configure
6008	* @return @ref LIBINPUT_CONFIG_DWT_DISABLED if disabled, @ref
6009	* LIBINPUT_CONFIG_DWT_ENABLED if enabled.
6010	*
6011	* @see libinput_device_config_dwt_is_available
6012	* @see libinput_device_config_dwt_set_enabled
6013	* @see libinput_device_config_dwt_get_default_enabled
6014	*/
6015	enum libinput_config_dwt_state
6016	libinput_device_config_dwt_get_enabled(struct libinput_device *device);
6017
6018	/**
6019	* @ingroup config
6020	*
6021	* Check if the disable-while typing feature is enabled on this device by
6022	* default. If the device does not support disable-while-typing, this
6023	* function returns @ref LIBINPUT_CONFIG_DWT_DISABLED.
6024	*
6025	* @param device The device to configure
6026	* @return @ref LIBINPUT_CONFIG_DWT_DISABLED if disabled, @ref
6027	* LIBINPUT_CONFIG_DWT_ENABLED if enabled.
6028	*
6029	* @see libinput_device_config_dwt_is_available
6030	* @see libinput_device_config_dwt_set_enabled
6031	* @see libinput_device_config_dwt_get_enabled
6032	*/
6033	enum libinput_config_dwt_state
6034	libinput_device_config_dwt_get_default_enabled(struct libinput_device *device);
6035
6036	/**
6037	* @ingroup config
6038	*
6039	* Check whether a device can have a custom rotation applied.
6040	*
6041	* @param device The device to configure
6042	* @return Non-zero if a device can be rotated, zero otherwise.
6043	*
6044	* @see libinput_device_config_rotation_set_angle
6045	* @see libinput_device_config_rotation_get_angle
6046	* @see libinput_device_config_rotation_get_default_angle
6047	*
6048	* @since 1.4
6049	*/
6050	int
6051	libinput_device_config_rotation_is_available(struct libinput_device *device);
6052
6053	/**
6054	* @ingroup config
6055	*
6056	* Set the rotation of a device in degrees clockwise off the logical neutral
6057	* position. Any subsequent motion events are adjusted according to the
6058	* given angle.
6059	*
6060	* The angle has to be in the range of [0, 360[ degrees, otherwise this
6061	* function returns LIBINPUT_CONFIG_STATUS_INVALID. If the angle is a
6062	* multiple of 360 or negative, the caller must ensure the correct ranging
6063	* before calling this function.
6064	*
6065	* libinput guarantees that this function accepts multiples of 90 degrees.
6066	* If a value is within the [0, 360[ range but not a multiple of 90 degrees,
6067	* this function may return LIBINPUT_CONFIG_STATUS_INVALID if the underlying
6068	* device or implementation does not support finer-grained rotation angles.
6069	*
6070	* The rotation angle is applied to all motion events emitted by the device.
6071	* Thus, rotating the device also changes the angle required or presented by
6072	* scrolling, gestures, etc.
6073	*
6074	* @param device The device to configure
6075	* @param degrees_cw The angle in degrees clockwise
6076	* @return A config status code. Setting a rotation of 0 degrees on a
6077	* device that does not support rotation always succeeds.
6078	*
6079	* @see libinput_device_config_rotation_is_available
6080	* @see libinput_device_config_rotation_get_angle
6081	* @see libinput_device_config_rotation_get_default_angle
6082	*
6083	* @since 1.4
6084	*/
6085	enum libinput_config_status
6086	libinput_device_config_rotation_set_angle(struct libinput_device *device,
6087	unsigned int degrees_cw);
6088
6089	/**
6090	* @ingroup config
6091	*
6092	* Get the current rotation of a device in degrees clockwise off the logical
6093	* neutral position. If this device does not support rotation, the return
6094	* value is always 0.
6095	*
6096	* @param device The device to configure
6097	* @return The angle in degrees clockwise
6098	*
6099	* @see libinput_device_config_rotation_is_available
6100	* @see libinput_device_config_rotation_set_angle
6101	* @see libinput_device_config_rotation_get_default_angle
6102	*
6103	* @since 1.4
6104	*/
6105	unsigned int
6106	libinput_device_config_rotation_get_angle(struct libinput_device *device);
6107
6108	/**
6109	* @ingroup config
6110	*
6111	* Get the default rotation of a device in degrees clockwise off the logical
6112	* neutral position. If this device does not support rotation, the return
6113	* value is always 0.
6114	*
6115	* @param device The device to configure
6116	* @return The default angle in degrees clockwise
6117	*
6118	* @see libinput_device_config_rotation_is_available
6119	* @see libinput_device_config_rotation_set_angle
6120	* @see libinput_device_config_rotation_get_angle
6121	*
6122	* @since 1.4
6123	*/
6124	unsigned int
6125	libinput_device_config_rotation_get_default_angle(struct libinput_device *device);
6126
6127	#ifdef __cplusplus
6128	}
6129	#endif
6130	#endif /* LIBINPUT_H */
6131