2 * Copyright © 2013 Jonas Ådahl
4 * Permission to use, copy, modify, distribute, and sell this software and
5 * its documentation for any purpose is hereby granted without fee, provided
6 * that the above copyright notice appear in all copies and that both that
7 * copyright notice and this permission notice appear in supporting
8 * documentation, and that the name of the copyright holders not be used in
9 * advertising or publicity pertaining to distribution of the software
10 * without specific, written prior permission. The copyright holders make
11 * no representations about the suitability of this software for any
12 * purpose. It is provided "as is" without express or implied warranty.
14 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
15 * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
17 * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
18 * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
19 * CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
20 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
34 #define LIBINPUT_ATTRIBUTE_PRINTF(_format, _args) \
35 __attribute__ ((format (printf, _format, _args)))
36 #define LIBINPUT_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated))
40 * libinput is a generic input device handling library. It abstracts
41 * commonly-used concepts such as keyboard, pointer and touchpad handling
46 * @page tpbuttons Touchpad button behavior
48 * For touchpad devices without physical buttons, libinput enables an
49 * emulated right button area through either of two methods.
51 * Software button areas
52 * =====================
53 * On most touchpads, the bottom area of the touchpad is split into a left
54 * and a right-button area. Pressing the touchpad down with a finger in
55 * those areas will generate clicks as shown in the diagram below:
58 +------------------------+
64 +------------------------+
66 +------------------------+
69 * Generally, the touchpad will emulate a right-button click if the finger
70 * was set down in the right button area and did not leave the
71 * right button area before clicking, even if another finger was already
72 * down on the touchpad in another area.
73 * A middle click is generated by clicking the touchpad when one finger is
74 * in the bottom left button area, and one finger is in the botton right
76 * The exact behavior of the touchpad is implementation-dependent.
78 * Top software button area
79 * ========================
80 * On selected touchpads, the top area of the touchpad is a separate set of
81 * software buttons split into a left, middle and right button area.
82 * Pressing the touchpad down with a finger in those areas will generate
83 * clicks as shown in the diagram below:
86 +------------------------+
87 | LEFT | MIDDLE | RIGHT |
88 +------------------------+
92 +------------------------+
94 +------------------------+
96 * This behavior is enabled on the Lenovo *40 series (T440, T540, T240...)
97 * and the Lenovo Helix, Yoga S1 and Carbon X1 2nd.
101 * On Apple touchpads, no button areas are provided. Instead, use a
102 * two-finger click for a right button click, and a three-finger click for a
103 * middle button click.
107 * Log priority for internal logging messages.
109 enum libinput_log_priority {
110 LIBINPUT_LOG_PRIORITY_DEBUG = 10,
111 LIBINPUT_LOG_PRIORITY_INFO = 20,
112 LIBINPUT_LOG_PRIORITY_ERROR = 30,
118 * Capabilities on a device. A device may have one or more capabilities
119 * at a time, and capabilities may appear or disappear during the
120 * lifetime of the device.
122 enum libinput_device_capability {
123 LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
124 LIBINPUT_DEVICE_CAP_POINTER = 1,
125 LIBINPUT_DEVICE_CAP_TOUCH = 2
131 * Logical state of a key. Note that the logical state may not represent
132 * the physical state of the key.
134 enum libinput_key_state {
135 LIBINPUT_KEY_STATE_RELEASED = 0,
136 LIBINPUT_KEY_STATE_PRESSED = 1
142 * Mask reflecting LEDs on a device.
145 LIBINPUT_LED_NUM_LOCK = (1 << 0),
146 LIBINPUT_LED_CAPS_LOCK = (1 << 1),
147 LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
153 * Logical state of a physical button. Note that the logical state may not
154 * represent the physical state of the button.
156 enum libinput_button_state {
157 LIBINPUT_BUTTON_STATE_RELEASED = 0,
158 LIBINPUT_BUTTON_STATE_PRESSED = 1
165 * Axes on a device that are not x or y coordinates.
167 enum libinput_pointer_axis {
168 LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0,
169 LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1,
175 * Event type for events returned by libinput_get_event().
177 enum libinput_event_type {
179 * This is not a real event type, and is only used to tell the user that
180 * no new event is available in the queue. See
181 * libinput_next_event_type().
183 LIBINPUT_EVENT_NONE = 0,
186 * Signals that a device has been added to the context. The device will
187 * not be read until the next time the user calls libinput_dispatch()
188 * and data is available.
190 * This allows setting up initial device configuration before any events
193 LIBINPUT_EVENT_DEVICE_ADDED,
196 * Signals that a device has been removed. No more events from the
197 * associated device will be in the queue or be queued after this event.
199 LIBINPUT_EVENT_DEVICE_REMOVED,
201 LIBINPUT_EVENT_KEYBOARD_KEY = 300,
203 LIBINPUT_EVENT_POINTER_MOTION = 400,
204 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
205 LIBINPUT_EVENT_POINTER_BUTTON,
206 LIBINPUT_EVENT_POINTER_AXIS,
208 LIBINPUT_EVENT_TOUCH_DOWN = 500,
209 LIBINPUT_EVENT_TOUCH_UP,
210 LIBINPUT_EVENT_TOUCH_MOTION,
211 LIBINPUT_EVENT_TOUCH_CANCEL,
213 * Signals the end of a set of touchpoints at one device sample
214 * time. This event has no coordinate information attached.
216 LIBINPUT_EVENT_TOUCH_FRAME
220 struct libinput_device;
221 struct libinput_seat;
223 struct libinput_event;
224 struct libinput_event_device_notify;
225 struct libinput_event_keyboard;
226 struct libinput_event_pointer;
229 * @ingroup event_touch
230 * @struct libinput_event_touch
232 * Touch event representing a touch down, move or up, as well as a touch
233 * cancel and touch frame events. Valid event types for this event are @ref
234 * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
235 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
236 * LIBINPUT_EVENT_TOUCH_FRAME.
238 struct libinput_event_touch;
241 * @defgroup event Accessing and destruction of events
249 * @param event An event retrieved by libinput_get_event().
252 libinput_event_destroy(struct libinput_event *event);
257 * Get the type of the event.
259 * @param event An event retrieved by libinput_get_event().
261 enum libinput_event_type
262 libinput_event_get_type(struct libinput_event *event);
267 * Get the libinput context from the event.
269 * @param event The libinput event
270 * @return The libinput context for this event.
273 libinput_event_get_context(struct libinput_event *event);
278 * Return the device associated with this event, if applicable. For device
279 * added/removed events this is the device added or removed. For all other
280 * device events, this is the device that generated the event.
282 * This device is not refcounted and its lifetime is that of the event. Use
283 * libinput_device_ref() before using the device outside of this scope.
285 * @return The device associated with this event
288 struct libinput_device *
289 libinput_event_get_device(struct libinput_event *event);
294 * Return the pointer event that is this input event. If the event type does
295 * not match the pointer event types, this function returns NULL.
297 * The inverse of this function is libinput_event_pointer_get_base_event().
299 * @return A pointer event, or NULL for other events
301 struct libinput_event_pointer *
302 libinput_event_get_pointer_event(struct libinput_event *event);
307 * Return the keyboard event that is this input event. If the event type does
308 * not match the keyboard event types, this function returns NULL.
310 * The inverse of this function is libinput_event_keyboard_get_base_event().
312 * @return A keyboard event, or NULL for other events
314 struct libinput_event_keyboard *
315 libinput_event_get_keyboard_event(struct libinput_event *event);
320 * Return the touch event that is this input event. If the event type does
321 * not match the touch event types, this function returns NULL.
323 * The inverse of this function is libinput_event_touch_get_base_event().
325 * @return A touch event, or NULL for other events
327 struct libinput_event_touch *
328 libinput_event_get_touch_event(struct libinput_event *event);
333 * Return the device event that is this input event. If the event type does
334 * not match the device event types, this function returns NULL.
336 * The inverse of this function is
337 * libinput_event_device_notify_get_base_event().
339 * @return A device event, or NULL for other events
341 struct libinput_event_device_notify *
342 libinput_event_get_device_notify_event(struct libinput_event *event);
347 * @return The generic libinput_event of this event
349 struct libinput_event *
350 libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
353 * @defgroup event_keyboard Keyboard events
355 * Key events are generated when a key changes its logical state, usually by
356 * being pressed or released.
360 * @ingroup event_keyboard
362 * @return The event time for this event
365 libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
368 * @ingroup event_keyboard
370 * @return The keycode that triggered this key event
373 libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
376 * @ingroup event_keyboard
378 * @return The state change of the key
380 enum libinput_key_state
381 libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
385 * @ingroup event_keyboard
387 * @return The generic libinput_event of this event
389 struct libinput_event *
390 libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
393 * @ingroup event_keyboard
395 * For the key of a LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
396 * of keys pressed on all devices on the associated seat after the event was
399 " @note It is an application bug to call this function for events other than
400 * LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
402 * @return the seat wide pressed key count for the key of this event
405 libinput_event_keyboard_get_seat_key_count(
406 struct libinput_event_keyboard *event);
409 * @defgroup event_pointer Pointer events
411 * Pointer events reflect motion, button and scroll events, as well as
412 * events from other axes.
416 * @ingroup event_pointer
418 * @return The event time for this event
421 libinput_event_pointer_get_time(struct libinput_event_pointer *event);
424 * @ingroup event_pointer
426 * Return the delta between the last event and the current event. For pointer
427 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
430 * @note It is an application bug to call this function for events other than
431 * LIBINPUT_EVENT_POINTER_MOTION.
433 * @return the relative x movement since the last event
436 libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
439 * @ingroup event_pointer
441 * Return the delta between the last event and the current event. For pointer
442 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
445 * @note It is an application bug to call this function for events other than
446 * LIBINPUT_EVENT_POINTER_MOTION.
448 * @return the relative y movement since the last event
451 libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
454 * @ingroup event_pointer
456 * Return the current absolute x coordinate of the pointer event, in mm from
457 * the top left corner of the device. To get the corresponding output screen
458 * coordinate, use libinput_event_pointer_get_absolute_x_transformed().
460 * For pointer events that are not of type
461 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
463 * @note It is an application bug to call this function for events other than
464 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
466 * @return the current absolute x coordinate
469 libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
472 * @ingroup event_pointer
474 * Return the current absolute y coordinate of the pointer event, in mm from
475 * the top left corner of the device. To get the corresponding output screen
476 * coordinate, use libinput_event_pointer_get_absolute_y_transformed().
478 * For pointer events that are not of type
479 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
481 * @note It is an application bug to call this function for events other than
482 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
484 * @return the current absolute y coordinate
487 libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
490 * @ingroup event_pointer
492 * Return the current absolute x coordinate of the pointer event, transformed to
493 * screen coordinates.
495 * For pointer events that are not of type
496 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
499 * @note It is an application bug to call this function for events other than
500 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
502 * @param event The libinput pointer event
503 * @param width The current output screen width
504 * @return the current absolute x coordinate transformed to a screen coordinate
507 libinput_event_pointer_get_absolute_x_transformed(
508 struct libinput_event_pointer *event,
512 * @ingroup event_pointer
514 * Return the current absolute y coordinate of the pointer event, transformed to
515 * screen coordinates.
517 * For pointer events that are not of type
518 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
521 * @note It is an application bug to call this function for events other than
522 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
524 * @param event The libinput pointer event
525 * @param height The current output screen height
526 * @return the current absolute y coordinate transformed to a screen coordinate
529 libinput_event_pointer_get_absolute_y_transformed(
530 struct libinput_event_pointer *event,
534 * @ingroup event_pointer
536 * Return the button that triggered this event.
537 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
538 * this function returns 0.
540 * @note It is an application bug to call this function for events other than
541 * LIBINPUT_EVENT_POINTER_BUTTON.
543 * @return the button triggering this event
546 libinput_event_pointer_get_button(struct libinput_event_pointer *event);
549 * @ingroup event_pointer
551 * Return the button state that triggered this event.
552 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
553 * this function returns 0.
555 * @note It is an application bug to call this function for events other than
556 * LIBINPUT_EVENT_POINTER_BUTTON.
558 * @return the button state triggering this event
560 enum libinput_button_state
561 libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
564 * @ingroup event_pointer
566 * For the button of a LIBINPUT_EVENT_POINTER_BUTTON event, return the total
567 * number of buttons pressed on all devices on the associated seat after the
568 * the event was triggered.
570 " @note It is an application bug to call this function for events other than
571 * LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function returns 0.
573 * @return the seat wide pressed button count for the key of this event
576 libinput_event_pointer_get_seat_button_count(
577 struct libinput_event_pointer *event);
580 * @ingroup event_pointer
582 * Return the axis that triggered this event.
583 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
584 * this function returns 0.
586 * @note It is an application bug to call this function for events other than
587 * LIBINPUT_EVENT_POINTER_AXIS.
589 * @return the axis triggering this event
591 enum libinput_pointer_axis
592 libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
595 * @ingroup event_pointer
597 * Return the axis value of the given axis. The interpretation of the value
598 * is dependent on the axis. For the two scrolling axes
599 * LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
600 * LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in
601 * relative scroll units, with the positive direction being down or right,
602 * respectively. The dimension of a scroll unit is equal to one unit of
603 * motion in the respective axis, where applicable (e.g. touchpad two-finger
606 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
607 * this function returns 0.
609 * @note It is an application bug to call this function for events other than
610 * LIBINPUT_EVENT_POINTER_AXIS.
612 * @return the axis value of this event
615 libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
618 * @ingroup event_pointer
620 * @return The generic libinput_event of this event
622 struct libinput_event *
623 libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
627 * @defgroup event_touch Touch events
629 * Events from absolute touch devices.
633 * @ingroup event_touch
635 * @return The event time for this event
638 libinput_event_touch_get_time(struct libinput_event_touch *event);
641 * @ingroup event_touch
643 * Get the slot of this touch event. See the kernel's multitouch
644 * protocol B documentation for more information.
646 * If the touch event has no assigned slot, for example if it is from a
647 * single touch device, this function returns -1.
649 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
650 * LIBINPUT_EVENT_TOUCH_FRAME.
652 * @return The slot of this touch event
655 libinput_event_touch_get_slot(struct libinput_event_touch *event);
658 * @ingroup event_touch
660 * Get the seat slot of the touch event. A seat slot is a non-negative seat
661 * wide unique identifier of an active touch point.
663 * Events from single touch devices will be represented as one individual
664 * touch point per device.
666 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
667 * LIBINPUT_EVENT_TOUCH_FRAME.
669 * @return The seat slot of the touch event
672 libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
675 * @ingroup event_touch
677 * Return the current absolute x coordinate of the touch event, in mm from
678 * the top left corner of the device. To get the corresponding output screen
679 * coordinate, use libinput_event_touch_get_x_transformed().
681 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
682 * LIBINPUT_EVENT_TOUCH_MOTION.
684 * @param event The libinput touch event
685 * @return the current absolute x coordinate
688 libinput_event_touch_get_x(struct libinput_event_touch *event);
691 * @ingroup event_touch
693 * Return the current absolute y coordinate of the touch event, in mm from
694 * the top left corner of the device. To get the corresponding output screen
695 * coordinate, use libinput_event_touch_get_y_transformed().
697 * For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
699 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
700 * LIBINPUT_EVENT_TOUCH_MOTION.
702 * @param event The libinput touch event
703 * @return the current absolute y coordinate
706 libinput_event_touch_get_y(struct libinput_event_touch *event);
709 * @ingroup event_touch
711 * Return the current absolute x coordinate of the touch event, transformed to
712 * screen coordinates.
714 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
715 * LIBINPUT_EVENT_TOUCH_MOTION.
717 * @param event The libinput touch event
718 * @param width The current output screen width
719 * @return the current absolute x coordinate transformed to a screen coordinate
722 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
726 * @ingroup event_touch
728 * Return the current absolute y coordinate of the touch event, transformed to
729 * screen coordinates.
731 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
732 * LIBINPUT_EVENT_TOUCH_MOTION.
734 * @param event The libinput touch event
735 * @param height The current output screen height
736 * @return the current absolute y coordinate transformed to a screen coordinate
739 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
743 * @ingroup event_touch
745 * @return The generic libinput_event of this event
747 struct libinput_event *
748 libinput_event_touch_get_base_event(struct libinput_event_touch *event);
751 * @defgroup base Initialization and manipulation of libinput contexts
754 struct libinput_interface {
756 * Open the device at the given path with the flags provided and
759 * @param path The device path to open
760 * @param flags Flags as defined by open(2)
761 * @param user_data The user_data provided in
762 * libinput_udev_create_context()
764 * @return the file descriptor, or a negative errno on failure.
766 int (*open_restricted)(const char *path, int flags, void *user_data);
768 * Close the file descriptor.
770 * @param fd The file descriptor to close
771 * @param user_data The user_data provided in
772 * libinput_udev_create_context()
774 void (*close_restricted)(int fd, void *user_data);
780 * Create a new libinput context from udev. This context is inactive until
781 * assigned a seat ID with libinput_udev_assign_seat().
783 * @param interface The callback interface
784 * @param user_data Caller-specific data passed to the various callback
786 * @param udev An already initialized udev context
788 * @return An initialized, but inactive libinput context or NULL on error
791 libinput_udev_create_context(const struct libinput_interface *interface,
798 * Assign a seat to this libinput context. New devices or the removal of
799 * existing devices will appear as events during libinput_dispatch().
801 * libinput_udev_assign_seat() succeeds even if no input devices are currently
802 * available on this seat, or if devices are available but fail to open in
803 * @ref libinput_interface::open_restricted. Devices that do not have the
804 * minimum capabilities to be recognized as pointer, keyboard or touch
805 * device are ignored. Such devices and those that failed to open
806 * ignored until the next call to libinput_resume().
808 * This function may only be called once per context.
810 * @param libinput A libinput context initialized with
811 * libinput_udev_create_context()
812 * @param seat_id A seat identifier. This string must not be NULL.
814 * @return 0 on success or -1 on failure.
817 libinput_udev_assign_seat(struct libinput *libinput,
818 const char *seat_id);
823 * Create a new libinput context that requires the caller to manually add or
824 * remove devices with libinput_path_add_device() and
825 * libinput_path_remove_device().
827 * The context is fully initialized but will not generate events until at
828 * least one device has been added.
830 * The reference count of the context is initialized to 1. See @ref
833 * @param interface The callback interface
834 * @param user_data Caller-specific data passed to the various callback
837 * @return An initialized, empty libinput context.
840 libinput_path_create_context(const struct libinput_interface *interface,
846 * Add a device to a libinput context initialized with
847 * libinput_path_create_context(). If successful, the device will be
848 * added to the internal list and re-opened on libinput_resume(). The device
849 * can be removed with libinput_path_remove_device().
851 * If the device was successfully initialized, it is returned in the device
852 * argument. The lifetime of the returned device pointer is limited until
853 * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent
856 * @param libinput A previously initialized libinput context
857 * @param path Path to an input device
858 * @return The newly initiated device on success, or NULL on failure.
860 * @note It is an application bug to call this function on a libinput
861 * context initialized with libinput_udev_create_context().
863 struct libinput_device *
864 libinput_path_add_device(struct libinput *libinput,
870 * Remove a device from a libinput context initialized with
871 * libinput_path_create_context() or added to such a context with
872 * libinput_path_add_device().
874 * Events already processed from this input device are kept in the queue,
875 * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
878 * If no matching device exists, this function does nothing.
880 * @param device A libinput device
882 * @note It is an application bug to call this function on a libinput
883 * context initialized with libinput_udev_create_context().
886 libinput_path_remove_device(struct libinput_device *device);
891 * libinput keeps a single file descriptor for all events. Call into
892 * libinput_dispatch() if any events become available on this fd.
894 * @return the file descriptor used to notify of pending events.
897 libinput_get_fd(struct libinput *libinput);
902 * Main event dispatchment function. Reads events of the file descriptors
903 * and processes them internally. Use libinput_get_event() to retrieve the
906 * Dispatching does not necessarily queue libinput events.
908 * @param libinput A previously initialized libinput context
910 * @return 0 on success, or a negative errno on failure
913 libinput_dispatch(struct libinput *libinput);
918 * Retrieve the next event from libinput's internal event queue.
920 * After handling the retrieved event, the caller must destroy it using
921 * libinput_event_destroy().
923 * @param libinput A previously initialized libinput context
924 * @return The next available event, or NULL if no event is available.
926 struct libinput_event *
927 libinput_get_event(struct libinput *libinput);
932 * Return the type of the next event in the internal queue. This function
933 * does not pop the event off the queue and the next call to
934 * libinput_get_event() returns that event.
936 * @param libinput A previously initialized libinput context
937 * @return The event type of the next available event or LIBINPUT_EVENT_NONE
938 * if no event is availble.
940 enum libinput_event_type
941 libinput_next_event_type(struct libinput *libinput);
946 * @param libinput A previously initialized libinput context
947 * @return the caller-specific data previously assigned in
948 * libinput_create_udev().
951 libinput_get_user_data(struct libinput *libinput);
956 * Resume a suspended libinput context. This re-enables device
957 * monitoring and adds existing devices.
959 * @param libinput A previously initialized libinput context
960 * @see libinput_suspend
962 * @return 0 on success or -1 on failure
965 libinput_resume(struct libinput *libinput);
970 * Suspend monitoring for new devices and close existing devices.
971 * This all but terminates libinput but does keep the context
972 * valid to be resumed with libinput_resume().
974 * @param libinput A previously initialized libinput context
977 libinput_suspend(struct libinput *libinput);
982 * Add a reference to the context. A context is destroyed whenever the
983 * reference count reaches 0. See @ref libinput_unref.
985 * @param libinput A previously initialized valid libinput context
986 * @return The passed libinput context
989 libinput_ref(struct libinput *libinput);
994 * Dereference the libinput context. After this, the context may have been
995 * destroyed, if the last reference was dereferenced. If so, the context is
996 * invalid and may not be interacted with.
998 * @param libinput A previously initialized libinput context
999 * @return NULL if context was destroyed otherwise the passed context
1002 libinput_unref(struct libinput *libinput);
1007 * Set the global log priority. Messages with priorities equal to or
1008 * higher than the argument will be printed to the current log handler.
1010 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1012 * @param libinput A previously initialized libinput context
1013 * @param priority The minimum priority of log messages to print.
1015 * @see libinput_log_set_handler
1016 * @see libinput_log_get_priority
1019 libinput_log_set_priority(struct libinput *libinput,
1020 enum libinput_log_priority priority);
1025 * Get the global log priority. Messages with priorities equal to or
1026 * higher than the argument will be printed to the current log handler.
1028 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1030 * @param libinput A previously initialized libinput context
1031 * @return The minimum priority of log messages to print.
1033 * @see libinput_log_set_handler
1034 * @see libinput_log_set_priority
1036 enum libinput_log_priority
1037 libinput_log_get_priority(const struct libinput *libinput);
1042 * Log handler type for custom logging.
1044 * @param libinput The libinput context
1045 * @param priority The priority of the current message
1046 * @param format Message format in printf-style
1047 * @param args Message arguments
1049 * @see libinput_set_log_priority
1050 * @see libinput_log_set_handler
1052 typedef void (*libinput_log_handler)(struct libinput *libinput,
1053 enum libinput_log_priority priority,
1054 const char *format, va_list args)
1055 LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
1060 * Set the global log handler. Messages with priorities equal to or higher
1061 * than the current log priority will be passed to the given
1064 * The default log handler prints to stderr.
1066 * @param libinput A previously initialized libinput context
1067 * @param log_handler The log handler for library messages.
1068 * @param user_data Caller-specific data pointer, passed into the log
1071 * @see libinput_log_set_handler
1074 libinput_log_set_handler(struct libinput *libinput,
1075 libinput_log_handler log_handler);
1078 * @defgroup seat Initialization and manipulation of seats
1080 * A seat has two identifiers, the physical name and the logical name. The
1081 * physical name is summarized as the list of devices a process on the same
1082 * physical seat has access to.
1084 * The logical seat name is the seat name for a logical group of devices. A
1085 * compositor may use that to create additonal seats as independent device
1086 * sets. Alternatively, a compositor may limit itself to a single logical
1087 * seat, leaving a second compositor to manage devices on the other logical
1091 * +---+--------+------------+------------------------+------------+
1092 * | | event0 | | | log seat A |
1093 * | K +--------+ | +------------+
1094 * | e | event1 | phys seat0 | libinput context 1 | |
1095 * | r +--------+ | | log seat B |
1096 * | n | event2 | | | |
1097 * | e +--------+------------+------------------------+------------+
1098 * | l | event3 | phys seat1 | libinput context 2 | log seat C |
1099 * +---+--------+------------+------------------------+------------+
1106 * Increase the refcount of the seat. A seat will be freed whenever the
1107 * refcount reaches 0. This may happen during dispatch if the
1108 * seat was removed from the system. A caller must ensure to reference
1109 * the seat correctly to avoid dangling pointers.
1111 * @param seat A previously obtained seat
1112 * @return The passed seat
1114 struct libinput_seat *
1115 libinput_seat_ref(struct libinput_seat *seat);
1120 * Decrease the refcount of the seat. A seat will be freed whenever the
1121 * refcount reaches 0. This may happen during dispatch if the
1122 * seat was removed from the system. A caller must ensure to reference
1123 * the seat correctly to avoid dangling pointers.
1125 * @param seat A previously obtained seat
1126 * @return NULL if seat was destroyed, otherwise the passed seat
1128 struct libinput_seat *
1129 libinput_seat_unref(struct libinput_seat *seat);
1134 * Set caller-specific data associated with this seat. libinput does
1135 * not manage, look at, or modify this data. The caller must ensure the
1138 * @param seat A previously obtained seat
1139 * @param user_data Caller-specific data pointer
1140 * @see libinput_seat_get_user_data
1143 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
1148 * Get the caller-specific data associated with this seat, if any.
1150 * @param seat A previously obtained seat
1151 * @return Caller-specific data pointer or NULL if none was set
1152 * @see libinput_seat_set_user_data
1155 libinput_seat_get_user_data(struct libinput_seat *seat);
1160 * Return the physical name of the seat. For libinput contexts created from
1161 * udev, this is always the same value as passed into
1162 * libinput_udev_assign_seat() and all seats from that context will have
1163 * the same physical name.
1165 * The physical name of the seat is one that is usually set by the system or
1166 * lower levels of the stack. In most cases, this is the base filter for
1167 * devices - devices assigned to seats outside the current seat will not
1168 * be available to the caller.
1170 * @param seat A previously obtained seat
1171 * @return the physical name of this seat
1174 libinput_seat_get_physical_name(struct libinput_seat *seat);
1179 * Return the logical name of the seat. This is an identifier to group sets
1180 * of devices within the compositor.
1182 * @param seat A previously obtained seat
1183 * @return the logical name of this seat
1186 libinput_seat_get_logical_name(struct libinput_seat *seat);
1189 * @defgroup device Initialization and manipulation of input devices
1195 * Increase the refcount of the input device. An input device will be freed
1196 * whenever the refcount reaches 0. This may happen during dispatch if the
1197 * device was removed from the system. A caller must ensure to reference
1198 * the device correctly to avoid dangling pointers.
1200 * @param device A previously obtained device
1201 * @return The passed device
1203 struct libinput_device *
1204 libinput_device_ref(struct libinput_device *device);
1209 * Decrease the refcount of the input device. An input device will be freed
1210 * whenever the refcount reaches 0. This may happen during dispatch if the
1211 * device was removed from the system. A caller must ensure to reference
1212 * the device correctly to avoid dangling pointers.
1214 * @param device A previously obtained device
1215 * @return NULL if device was destroyed, otherwise the passed device
1217 struct libinput_device *
1218 libinput_device_unref(struct libinput_device *device);
1223 * Set caller-specific data associated with this input device. libinput does
1224 * not manage, look at, or modify this data. The caller must ensure the
1227 * @param device A previously obtained device
1228 * @param user_data Caller-specific data pointer
1229 * @see libinput_device_get_user_data
1232 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1237 * Get the caller-specific data associated with this input device, if any.
1239 * @param device A previously obtained device
1240 * @return Caller-specific data pointer or NULL if none was set
1241 * @see libinput_device_set_user_data
1244 libinput_device_get_user_data(struct libinput_device *device);
1249 * Get the system name of the device.
1251 * To get the descriptive device name, use libinput_device_get_name().
1253 * @param device A previously obtained device
1254 * @return System name of the device
1258 libinput_device_get_sysname(struct libinput_device *device);
1263 * The descriptive device name as advertised by the kernel and/or the
1264 * hardware itself. To get the sysname for this device, use
1265 * libinput_device_get_sysname().
1267 * The lifetime of the returned string is tied to the struct
1268 * libinput_device. The string may be the empty string but is never NULL.
1270 * @param device A previously obtained device
1271 * @return The device name
1274 libinput_device_get_name(struct libinput_device *device);
1279 * Get the product ID for this device.
1281 * @param device A previously obtained device
1282 * @return The product ID of this device
1285 libinput_device_get_id_product(struct libinput_device *device);
1290 * Get the vendor ID for this device.
1292 * @param device A previously obtained device
1293 * @return The vendor ID of this device
1296 libinput_device_get_id_vendor(struct libinput_device *device);
1301 * A device may be mapped to a single output, or all available outputs. If a
1302 * device is mapped to a single output only, a relative device may not move
1303 * beyond the boundaries of this output. An absolute device has its input
1304 * coordinates mapped to the extents of this output.
1306 * @return the name of the output this device is mapped to, or NULL if no
1310 libinput_device_get_output_name(struct libinput_device *device);
1315 * Get the seat associated with this input device.
1317 * A seat can be uniquely identified by the physical and logical seat name.
1318 * There will ever be only one seat instance with a given physical and logical
1319 * seat name pair at any given time, but if no external reference is kept, it
1320 * may be destroyed if no device belonging to it is left.
1322 * @param device A previously obtained device
1323 * @return The seat this input device belongs to
1325 struct libinput_seat *
1326 libinput_device_get_seat(struct libinput_device *device);
1331 * Update the LEDs on the device, if any. If the device does not have
1332 * LEDs, or does not have one or more of the LEDs given in the mask, this
1333 * function does nothing.
1335 * @param device A previously obtained device
1336 * @param leds A mask of the LEDs to set, or unset.
1339 libinput_device_led_update(struct libinput_device *device,
1340 enum libinput_led leds);
1345 * Set the bitmask in keys to the bitmask of the keys present on the device
1346 * (see linux/input.h), up to size characters.
1348 * @param device A current input device
1349 * @param keys An array filled with the bitmask for the keys
1350 * @param size Size of the keys array
1352 * @return The number of valid bytes in keys, or a negative errno on failure
1355 libinput_device_get_keys(struct libinput_device *device,
1356 char *keys, size_t size);
1361 * Apply the 3x3 transformation matrix to absolute device coordinates. This
1362 * matrix has no effect on relative events.
1364 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1372 libinput_device_calibrate(struct libinput_device *device,
1373 float calibration[6]);
1378 * Check if the given device has the specified capability
1380 * @return 1 if the given device has the capability or 0 if not
1383 libinput_device_has_capability(struct libinput_device *device,
1384 enum libinput_device_capability capability);
1389 * Get the physical size of a device in mm, where meaningful. This function
1390 * only succeeds on devices with the required data, i.e. tablets, touchpads
1393 * If this function returns nonzero, width and height are unmodified.
1395 * @param device The device
1396 * @param width Set to the width of the device
1397 * @param height Set to the height of the device
1398 * @return 0 on success, or nonzero otherwise
1401 libinput_device_get_size(struct libinput_device *device,
1407 * @defgroup config Device configuration
1409 * Enable, disable, change and/or check for device-specific features. For
1410 * all features, libinput assigns a default based on the hardware
1411 * configuration. This default can be obtained with the respective
1414 * Some configuration option may be dependent on or mutually exclusive with
1415 * with other options. The behavior in those cases is
1416 * implementation-defined, the caller must ensure that the options are set
1417 * in the right order.
1423 * Status codes returned when applying configuration settings.
1425 enum libinput_config_status {
1426 LIBINPUT_CONFIG_STATUS_SUCCESS = 0, /**< Config applied successfully */
1427 LIBINPUT_CONFIG_STATUS_UNSUPPORTED, /**< Configuration not available on
1429 LIBINPUT_CONFIG_STATUS_INVALID, /**< Invalid parameter range */
1435 * Return a string describing the error.
1437 * @param status The status to translate to a string
1438 * @return A human-readable string representing the error or NULL for an
1442 libinput_config_status_to_str(enum libinput_config_status status);
1447 * Check if the device supports tap-to-click. See
1448 * libinput_device_config_tap_set_enabled() for more information.
1450 * @param device The device to configure
1451 * @return The number of fingers that can generate a tap event, or 0 if the
1452 * device does not support tapping.
1454 * @see libinput_device_config_tap_set_enabled
1455 * @see libinput_device_config_tap_get_enabled
1456 * @see libinput_device_config_tap_set_enabled_get_default
1459 libinput_device_config_tap_get_finger_count(struct libinput_device *device);
1464 * Enable or disable tap-to-click on this device, with a default mapping of
1465 * 1, 2, 3 finger tap mapping to left, right, middle click, respectively.
1466 * Tapping is limited by the number of simultaneous touches
1467 * supported by the device, see
1468 * libinput_device_config_tap_get_finger_count().
1470 * @param device The device to configure
1471 * @param enable Non-zero to enable, zero to disable
1473 * @return A config status code. Disabling tapping on a device that does not
1474 * support tapping always succeeds.
1476 * @see libinput_device_config_tap_get_finger_count
1477 * @see libinput_device_config_tap_get_enabled
1478 * @see libinput_device_config_tap_get_default_enabled
1480 enum libinput_config_status
1481 libinput_device_config_tap_set_enabled(struct libinput_device *device,
1487 * Check if tap-to-click is enabled on this device. If the device does not
1488 * support tapping, this function always returns 0.
1490 * @param device The device to configure
1492 * @return 1 if enabled, 0 otherwise.
1494 * @see libinput_device_config_tap_get_finger_count
1495 * @see libinput_device_config_tap_set_enabled
1496 * @see libinput_device_config_tap_get_default_enabled
1499 libinput_device_config_tap_get_enabled(struct libinput_device *device);
1504 * Return the default setting for whether tapping is enabled on this device.
1506 * @param device The device to configure
1507 * @return 1 if tapping is enabled by default, or 0 otherwise
1509 * @see libinput_device_config_tap_get_finger_count
1510 * @see libinput_device_config_tap_set_enabled
1511 * @see libinput_device_config_tap_get_enabled
1514 libinput_device_config_tap_get_default_enabled(struct libinput_device *device);
1519 #endif /* LIBINPUT_H */