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