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 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,
172 /** @deprecated Use @ref LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL instead */
173 LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL,
174 /** @deprecated Use @ref LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL instead */
175 LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL
181 * Event type for events returned by libinput_get_event().
183 enum libinput_event_type {
185 * This is not a real event type, and is only used to tell the user that
186 * no new event is available in the queue. See
187 * libinput_next_event_type().
189 LIBINPUT_EVENT_NONE = 0,
192 * Signals that a device has been added to the context. The device will
193 * not be read until the next time the user calls libinput_dispatch()
194 * and data is available.
196 * This allows setting up initial device configuration before any events
199 LIBINPUT_EVENT_DEVICE_ADDED,
202 * Signals that a device has been removed. No more events from the
203 * associated device will be in the queue or be queued after this event.
205 LIBINPUT_EVENT_DEVICE_REMOVED,
207 LIBINPUT_EVENT_KEYBOARD_KEY = 300,
209 LIBINPUT_EVENT_POINTER_MOTION = 400,
210 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
211 LIBINPUT_EVENT_POINTER_BUTTON,
212 LIBINPUT_EVENT_POINTER_AXIS,
214 LIBINPUT_EVENT_TOUCH_DOWN = 500,
215 LIBINPUT_EVENT_TOUCH_UP,
216 LIBINPUT_EVENT_TOUCH_MOTION,
217 LIBINPUT_EVENT_TOUCH_CANCEL,
219 * Signals the end of a set of touchpoints at one device sample
220 * time. This event has no coordinate information attached.
222 LIBINPUT_EVENT_TOUCH_FRAME
226 struct libinput_device;
227 struct libinput_seat;
229 struct libinput_event;
230 struct libinput_event_device_notify;
231 struct libinput_event_keyboard;
232 struct libinput_event_pointer;
235 * @ingroup event_touch
236 * @struct libinput_event_touch
238 * Touch event representing a touch down, move or up, as well as a touch
239 * cancel and touch frame events. Valid event types for this event are @ref
240 * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
241 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
242 * LIBINPUT_EVENT_TOUCH_FRAME.
244 struct libinput_event_touch;
247 * @defgroup event Accessing and destruction of events
255 * @param event An event retrieved by libinput_get_event().
258 libinput_event_destroy(struct libinput_event *event);
263 * Get the type of the event.
265 * @param event An event retrieved by libinput_get_event().
267 enum libinput_event_type
268 libinput_event_get_type(struct libinput_event *event);
273 * Get the libinput context from the event.
275 * @param event The libinput event
276 * @return The libinput context for this event.
279 libinput_event_get_context(struct libinput_event *event);
284 * Return the device associated with this event, if applicable. For device
285 * added/removed events this is the device added or removed. For all other
286 * device events, this is the device that generated the event.
288 * This device is not refcounted and its lifetime is that of the event. Use
289 * libinput_device_ref() before using the device outside of this scope.
291 * @return The device associated with this event
294 struct libinput_device *
295 libinput_event_get_device(struct libinput_event *event);
300 * Return the pointer event that is this input event. If the event type does
301 * not match the pointer event types, this function returns NULL.
303 * The inverse of this function is libinput_event_pointer_get_base_event().
305 * @return A pointer event, or NULL for other events
307 struct libinput_event_pointer *
308 libinput_event_get_pointer_event(struct libinput_event *event);
313 * Return the keyboard event that is this input event. If the event type does
314 * not match the keyboard event types, this function returns NULL.
316 * The inverse of this function is libinput_event_keyboard_get_base_event().
318 * @return A keyboard event, or NULL for other events
320 struct libinput_event_keyboard *
321 libinput_event_get_keyboard_event(struct libinput_event *event);
326 * Return the touch event that is this input event. If the event type does
327 * not match the touch event types, this function returns NULL.
329 * The inverse of this function is libinput_event_touch_get_base_event().
331 * @return A touch event, or NULL for other events
333 struct libinput_event_touch *
334 libinput_event_get_touch_event(struct libinput_event *event);
339 * Return the device event that is this input event. If the event type does
340 * not match the device event types, this function returns NULL.
342 * The inverse of this function is
343 * libinput_event_device_notify_get_base_event().
345 * @return A device event, or NULL for other events
347 struct libinput_event_device_notify *
348 libinput_event_get_device_notify_event(struct libinput_event *event);
353 * @return The generic libinput_event of this event
355 struct libinput_event *
356 libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
359 * @defgroup event_keyboard Keyboard events
361 * Key events are generated when a key changes its logical state, usually by
362 * being pressed or released.
366 * @ingroup event_keyboard
368 * @return The event time for this event
371 libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
374 * @ingroup event_keyboard
376 * @return The keycode that triggered this key event
379 libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
382 * @ingroup event_keyboard
384 * @return The state change of the key
386 enum libinput_key_state
387 libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
391 * @ingroup event_keyboard
393 * @return The generic libinput_event of this event
395 struct libinput_event *
396 libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
399 * @ingroup event_keyboard
401 * For the key of a LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
402 * of keys pressed on all devices on the associated seat after the event was
405 " @note It is an application bug to call this function for events other than
406 * LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
408 * @return the seat wide pressed key count for the key of this event
411 libinput_event_keyboard_get_seat_key_count(
412 struct libinput_event_keyboard *event);
415 * @defgroup event_pointer Pointer events
417 * Pointer events reflect motion, button and scroll events, as well as
418 * events from other axes.
422 * @ingroup event_pointer
424 * @return The event time for this event
427 libinput_event_pointer_get_time(struct libinput_event_pointer *event);
430 * @ingroup event_pointer
432 * Return the delta between the last event and the current event. For pointer
433 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
436 * @note It is an application bug to call this function for events other than
437 * LIBINPUT_EVENT_POINTER_MOTION.
439 * @return the relative x movement since the last event
442 libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
445 * @ingroup event_pointer
447 * Return the delta between the last event and the current event. For pointer
448 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
451 * @note It is an application bug to call this function for events other than
452 * LIBINPUT_EVENT_POINTER_MOTION.
454 * @return the relative y movement since the last event
457 libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
460 * @ingroup event_pointer
462 * Return the current absolute x coordinate of the pointer event, in mm from
463 * the top left corner of the device. To get the corresponding output screen
464 * coordinate, use libinput_event_pointer_get_x_transformed().
466 * For pointer events that are not of type
467 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
469 * @note It is an application bug to call this function for events other than
470 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
472 * @return the current absolute x coordinate
475 libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
478 * @ingroup event_pointer
480 * Return the current absolute y coordinate of the pointer event, in mm from
481 * the top left corner of the device. To get the corresponding output screen
482 * coordinate, use libinput_event_pointer_get_x_transformed().
484 * For pointer events that are not of type
485 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
487 * @note It is an application bug to call this function for events other than
488 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
490 * @return the current absolute y coordinate
493 libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
496 * @ingroup event_pointer
498 * Return the current absolute x coordinate of the pointer event, transformed to
499 * screen coordinates.
501 * For pointer events that are not of type
502 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
505 * @note It is an application bug to call this function for events other than
506 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
508 * @param event The libinput pointer event
509 * @param width The current output screen width
510 * @return the current absolute x coordinate transformed to a screen coordinate
513 libinput_event_pointer_get_absolute_x_transformed(
514 struct libinput_event_pointer *event,
518 * @ingroup event_pointer
520 * Return the current absolute y coordinate of the pointer event, transformed to
521 * screen coordinates.
523 * For pointer events that are not of type
524 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
527 * @note It is an application bug to call this function for events other than
528 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
530 * @param event The libinput pointer event
531 * @param height The current output screen height
532 * @return the current absolute y coordinate transformed to a screen coordinate
535 libinput_event_pointer_get_absolute_y_transformed(
536 struct libinput_event_pointer *event,
540 * @ingroup event_pointer
542 * Return the button that triggered this event.
543 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
544 * this function returns 0.
546 * @note It is an application bug to call this function for events other than
547 * LIBINPUT_EVENT_POINTER_BUTTON.
549 * @return the button triggering this event
552 libinput_event_pointer_get_button(struct libinput_event_pointer *event);
555 * @ingroup event_pointer
557 * Return the button state that triggered this event.
558 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
559 * this function returns 0.
561 * @note It is an application bug to call this function for events other than
562 * LIBINPUT_EVENT_POINTER_BUTTON.
564 * @return the button state triggering this event
566 enum libinput_button_state
567 libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
570 * @ingroup event_pointer
572 * For the button of a LIBINPUT_EVENT_POINTER_BUTTON event, return the total
573 * number of buttons pressed on all devices on the associated seat after the
574 * the event was triggered.
576 " @note It is an application bug to call this function for events other than
577 * LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function returns 0.
579 * @return the seat wide pressed button count for the key of this event
582 libinput_event_pointer_get_seat_button_count(
583 struct libinput_event_pointer *event);
586 * @ingroup event_pointer
588 * Return the axis that triggered this event.
589 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
590 * this function returns 0.
592 * @note It is an application bug to call this function for events other than
593 * LIBINPUT_EVENT_POINTER_AXIS.
595 * @return the axis triggering this event
597 enum libinput_pointer_axis
598 libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
601 * @ingroup event_pointer
603 * Return the axis value of the given axis. The interpretation of the value
604 * is dependent on the axis. For the two scrolling axes
605 * LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
606 * LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in
607 * relative scroll units, with the positive direction being down or right,
608 * respectively. The dimension of a scroll unit is equal to one unit of
609 * motion in the respective axis, where applicable (e.g. touchpad two-finger
612 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
613 * this function returns 0.
615 * @note It is an application bug to call this function for events other than
616 * LIBINPUT_EVENT_POINTER_AXIS.
618 * @return the axis value of this event
621 libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
624 * @ingroup event_pointer
626 * @return The generic libinput_event of this event
628 struct libinput_event *
629 libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
633 * @defgroup event_touch Touch events
635 * Events from absolute touch devices.
639 * @ingroup event_touch
641 * @return The event time for this event
644 libinput_event_touch_get_time(struct libinput_event_touch *event);
647 * @ingroup event_touch
649 * Get the slot of this touch event. See the kernel's multitouch
650 * protocol B documentation for more information.
652 * If the touch event has no assigned slot, for example if it is from a
653 * single touch device, this function returns -1.
655 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
656 * LIBINPUT_EVENT_TOUCH_FRAME.
658 * @return The slot of this touch event
661 libinput_event_touch_get_slot(struct libinput_event_touch *event);
664 * @ingroup event_touch
666 * Get the seat slot of the touch event. A seat slot is a non-negative seat
667 * wide unique identifier of an active touch point.
669 * Events from single touch devices will be represented as one individual
670 * touch point per device.
672 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
673 * LIBINPUT_EVENT_TOUCH_FRAME.
675 * @return The seat slot of the touch event
678 libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
681 * @ingroup event_touch
683 * Return the current absolute x coordinate of the touch event, in mm from
684 * the top left corner of the device. To get the corresponding output screen
685 * coordinate, use libinput_event_touch_get_x_transformed().
687 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
688 * LIBINPUT_EVENT_TOUCH_MOTION.
690 * @param event The libinput touch event
691 * @return the current absolute x coordinate
694 libinput_event_touch_get_x(struct libinput_event_touch *event);
697 * @ingroup event_touch
699 * Return the current absolute y coordinate of the touch event, in mm from
700 * the top left corner of the device. To get the corresponding output screen
701 * coordinate, use libinput_event_touch_get_y_transformed().
703 * For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
705 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
706 * LIBINPUT_EVENT_TOUCH_MOTION.
708 * @param event The libinput touch event
709 * @return the current absolute y coordinate
712 libinput_event_touch_get_y(struct libinput_event_touch *event);
715 * @ingroup event_touch
717 * Return the current absolute x coordinate of the touch event, transformed to
718 * screen coordinates.
720 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
721 * LIBINPUT_EVENT_TOUCH_MOTION.
723 * @param event The libinput touch event
724 * @param width The current output screen width
725 * @return the current absolute x coordinate transformed to a screen coordinate
728 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
732 * @ingroup event_touch
734 * Return the current absolute y coordinate of the touch event, transformed to
735 * screen coordinates.
737 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
738 * LIBINPUT_EVENT_TOUCH_MOTION.
740 * @param event The libinput touch event
741 * @param height The current output screen height
742 * @return the current absolute y coordinate transformed to a screen coordinate
745 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
749 * @ingroup event_touch
751 * @return The generic libinput_event of this event
753 struct libinput_event *
754 libinput_event_touch_get_base_event(struct libinput_event_touch *event);
757 * @defgroup base Initialization and manipulation of libinput contexts
760 struct libinput_interface {
762 * Open the device at the given path with the flags provided and
765 * @param path The device path to open
766 * @param flags Flags as defined by open(2)
767 * @param user_data The user_data provided in
768 * libinput_udev_create_for_seat()
770 * @return the file descriptor, or a negative errno on failure.
772 int (*open_restricted)(const char *path, int flags, void *user_data);
774 * Close the file descriptor.
776 * @param fd The file descriptor to close
777 * @param user_data The user_data provided in
778 * libinput_udev_create_for_seat()
780 void (*close_restricted)(int fd, void *user_data);
786 * Create a new libinput context from udev. This context is inactive until
787 * assigned a seat ID with libinput_udev_assign_seat().
789 * @param interface The callback interface
790 * @param user_data Caller-specific data passed to the various callback
792 * @param udev An already initialized udev context
794 * @return An initialized, but inactive libinput context or NULL on error
797 libinput_udev_create_context(const struct libinput_interface *interface,
804 * Assign a seat to this libinput context. New devices or the removal of
805 * existing devices will appear as events during libinput_dispatch().
807 * libinput_udev_assign_seat() succeeds even if no input devices are currently
808 * available on this seat, or if devices are available but fail to open in
809 * @ref libinput_interface::open_restricted. Devices that do not have the
810 * minimum capabilities to be recognized as pointer, keyboard or touch
811 * device are ignored. Such devices and those that failed to open
812 * ignored until the next call to libinput_resume().
814 * This function may only be called once per context.
816 * @param libinput A libinput context initialized with
817 * libinput_udev_create_context()
818 * @param seat_id A seat identifier. This string must not be NULL.
820 * @return 0 on success or -1 on failure.
823 libinput_udev_assign_seat(struct libinput *libinput,
824 const char *seat_id);
829 * Create a new libinput context from udev, for input devices matching
830 * the given seat ID. New devices or devices removed will appear as events
831 * during libinput_dispatch.
833 * libinput_udev_create_for_seat() succeeds even if no input device is
834 * available in this seat, or if devices are available but fail to open in
835 * @ref libinput_interface::open_restricted. Devices that do not have the
836 * minimum capabilities to be recognized as pointer, keyboard or touch
837 * device are ignored. Such devices and those that failed to open
838 * ignored until the next call to libinput_resume().
840 * @param interface The callback interface
841 * @param user_data Caller-specific data passed to the various callback
843 * @param udev An already initialized udev context
844 * @param seat_id A seat identifier. This string must not be NULL.
846 * @return An initialized libinput context, ready to handle events or NULL on
849 * @deprecated This function was deprecated in 0.4.0 and will be removed
850 * soon. Use libinput_udev_create_context() and libinput_udev_assign_seat()
854 libinput_udev_create_for_seat(const struct libinput_interface *interface,
858 LIBINPUT_ATTRIBUTE_DEPRECATED;
863 * Create a new libinput context that requires the caller to manually add or
864 * remove devices with libinput_path_add_device() and
865 * libinput_path_remove_device().
867 * The context is fully initialized but will not generate events until at
868 * least one device has been added.
870 * @param interface The callback interface
871 * @param user_data Caller-specific data passed to the various callback
874 * @return An initialized, empty libinput context.
877 libinput_path_create_context(const struct libinput_interface *interface,
883 * Add a device to a libinput context initialized with
884 * libinput_path_create_context(). If successful, the device will be
885 * added to the internal list and re-opened on libinput_resume(). The device
886 * can be removed with libinput_path_remove_device().
888 * If the device was successfully initialized, it is returned in the device
889 * argument. The lifetime of the returned device pointer is limited until
890 * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent
893 * @param libinput A previously initialized libinput context
894 * @param path Path to an input device
895 * @return The newly initiated device on success, or NULL on failure.
897 * @note It is an application bug to call this function on a libinput
898 * context initialized with libinput_udev_create_for_seat().
900 struct libinput_device *
901 libinput_path_add_device(struct libinput *libinput,
907 * Remove a device from a libinput context initialized with
908 * libinput_path_create_context() or added to such a context with
909 * libinput_path_add_device().
911 * Events already processed from this input device are kept in the queue,
912 * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
915 * If no matching device exists, this function does nothing.
917 * @param device A libinput device
919 * @note It is an application bug to call this function on a libinput
920 * context initialized with libinput_udev_create_for_seat().
923 libinput_path_remove_device(struct libinput_device *device);
928 * libinput keeps a single file descriptor for all events. Call into
929 * libinput_dispatch() if any events become available on this fd.
931 * @return the file descriptor used to notify of pending events.
934 libinput_get_fd(struct libinput *libinput);
939 * Main event dispatchment function. Reads events of the file descriptors
940 * and processes them internally. Use libinput_get_event() to retrieve the
943 * Dispatching does not necessarily queue libinput events.
945 * @param libinput A previously initialized libinput context
947 * @return 0 on success, or a negative errno on failure
950 libinput_dispatch(struct libinput *libinput);
955 * Retrieve the next event from libinput's internal event queue.
957 * After handling the retrieved event, the caller must destroy it using
958 * libinput_event_destroy().
960 * @param libinput A previously initialized libinput context
961 * @return The next available event, or NULL if no event is available.
963 struct libinput_event *
964 libinput_get_event(struct libinput *libinput);
969 * Return the type of the next event in the internal queue. This function
970 * does not pop the event off the queue and the next call to
971 * libinput_get_event() returns that event.
973 * @param libinput A previously initialized libinput context
974 * @return The event type of the next available event or LIBINPUT_EVENT_NONE
975 * if no event is availble.
977 enum libinput_event_type
978 libinput_next_event_type(struct libinput *libinput);
983 * @param libinput A previously initialized libinput context
984 * @return the caller-specific data previously assigned in
985 * libinput_create_udev().
988 libinput_get_user_data(struct libinput *libinput);
993 * Resume a suspended libinput context. This re-enables device
994 * monitoring and adds existing devices.
996 * @param libinput A previously initialized libinput context
997 * @see libinput_suspend
999 * @return 0 on success or -1 on failure
1002 libinput_resume(struct libinput *libinput);
1007 * Suspend monitoring for new devices and close existing devices.
1008 * This all but terminates libinput but does keep the context
1009 * valid to be resumed with libinput_resume().
1011 * @param libinput A previously initialized libinput context
1014 libinput_suspend(struct libinput *libinput);
1019 * Destroy the libinput context. After this, object references associated with
1020 * the destroyed context are invalid and may not be interacted with.
1022 * @param libinput A previously initialized libinput context
1025 libinput_destroy(struct libinput *libinput);
1030 * Set the global log priority. Messages with priorities equal to or
1031 * higher than the argument will be printed to the current log handler.
1033 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1035 * @param priority The minimum priority of log messages to print.
1037 * @see libinput_log_set_handler
1038 * @see libinput_log_get_priority
1041 libinput_log_set_priority(enum libinput_log_priority priority);
1046 * Get the global log priority. Messages with priorities equal to or
1047 * higher than the argument will be printed to the current log handler.
1049 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1051 * @return The minimum priority of log messages to print.
1053 * @see libinput_log_set_handler
1054 * @see libinput_log_set_priority
1056 enum libinput_log_priority
1057 libinput_log_get_priority(void);
1062 * Log handler type for custom logging.
1064 * @param priority The priority of the current message
1065 * @param user_data Caller-specific data pointer as previously passed into
1066 * libinput_log_set_handler()
1067 * @param format Message format in printf-style
1068 * @param args Message arguments
1070 * @see libinput_set_log_priority
1071 * @see libinput_log_set_handler
1073 typedef void (*libinput_log_handler)(enum libinput_log_priority priority,
1075 const char *format, va_list args)
1076 LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
1081 * Set the global log handler. Messages with priorities equal to or higher
1082 * than the current log priority will be passed to the given
1085 * The default log handler prints to stderr.
1087 * @param log_handler The log handler for library messages.
1088 * @param user_data Caller-specific data pointer, passed into the log
1091 * @see libinput_log_set_handler
1094 libinput_log_set_handler(libinput_log_handler log_handler,
1098 * @defgroup seat Initialization and manipulation of seats
1100 * A seat has two identifiers, the physical name and the logical name. The
1101 * physical name is summarized as the list of devices a process on the same
1102 * physical seat has access to.
1104 * The logical seat name is the seat name for a logical group of devices. A
1105 * compositor may use that to create additonal seats as independent device
1106 * sets. Alternatively, a compositor may limit itself to a single logical
1107 * seat, leaving a second compositor to manage devices on the other logical
1111 * +---+--------+------------+------------------------+------------+
1112 * | | event0 | | | log seat A |
1113 * | K +--------+ | +------------+
1114 * | e | event1 | phys seat0 | libinput context 1 | |
1115 * | r +--------+ | | log seat B |
1116 * | n | event2 | | | |
1117 * | e +--------+------------+------------------------+------------+
1118 * | l | event3 | phys seat1 | libinput context 2 | log seat C |
1119 * +---+--------+------------+------------------------+------------+
1126 * Increase the refcount of the seat. A seat will be freed whenever the
1127 * refcount reaches 0. This may happen during dispatch if the
1128 * seat was removed from the system. A caller must ensure to reference
1129 * the seat correctly to avoid dangling pointers.
1131 * @param seat A previously obtained seat
1134 libinput_seat_ref(struct libinput_seat *seat);
1139 * Decrease the refcount of the seat. A seat will be freed whenever the
1140 * refcount reaches 0. This may happen during dispatch if the
1141 * seat was removed from the system. A caller must ensure to reference
1142 * the seat correctly to avoid dangling pointers.
1144 * @param seat A previously obtained seat
1147 libinput_seat_unref(struct libinput_seat *seat);
1152 * Set caller-specific data associated with this seat. libinput does
1153 * not manage, look at, or modify this data. The caller must ensure the
1156 * @param seat A previously obtained seat
1157 * @param user_data Caller-specific data pointer
1158 * @see libinput_seat_get_user_data
1161 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
1166 * Get the caller-specific data associated with this seat, if any.
1168 * @param seat A previously obtained seat
1169 * @return Caller-specific data pointer or NULL if none was set
1170 * @see libinput_seat_set_user_data
1173 libinput_seat_get_user_data(struct libinput_seat *seat);
1178 * Return the physical name of the seat. For libinput contexts created from
1179 * udev, this is always the same value as passed into
1180 * libinput_udev_create_for_seat() and all seats from that context will have
1181 * the same physical name.
1183 * The physical name of the seat is one that is usually set by the system or
1184 * lower levels of the stack. In most cases, this is the base filter for
1185 * devices - devices assigned to seats outside the current seat will not
1186 * be available to the caller.
1188 * @param seat A previously obtained seat
1189 * @return the physical name of this seat
1192 libinput_seat_get_physical_name(struct libinput_seat *seat);
1197 * Return the logical name of the seat. This is an identifier to group sets
1198 * of devices within the compositor.
1200 * @param seat A previously obtained seat
1201 * @return the logical name of this seat
1204 libinput_seat_get_logical_name(struct libinput_seat *seat);
1207 * @defgroup device Initialization and manipulation of input devices
1213 * Increase the refcount of the input device. An input device will be freed
1214 * whenever the refcount reaches 0. This may happen during dispatch if the
1215 * device was removed from the system. A caller must ensure to reference
1216 * the device correctly to avoid dangling pointers.
1218 * @param device A previously obtained device
1221 libinput_device_ref(struct libinput_device *device);
1226 * Decrease the refcount of the input device. An input device will be freed
1227 * whenever the refcount reaches 0. This may happen during dispatch if the
1228 * device was removed from the system. A caller must ensure to reference
1229 * the device correctly to avoid dangling pointers.
1231 * @param device A previously obtained device
1234 libinput_device_unref(struct libinput_device *device);
1239 * Set caller-specific data associated with this input device. libinput does
1240 * not manage, look at, or modify this data. The caller must ensure the
1243 * @param device A previously obtained device
1244 * @param user_data Caller-specific data pointer
1245 * @see libinput_device_get_user_data
1248 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1253 * Get the caller-specific data associated with this input device, if any.
1255 * @param device A previously obtained device
1256 * @return Caller-specific data pointer or NULL if none was set
1257 * @see libinput_device_set_user_data
1260 libinput_device_get_user_data(struct libinput_device *device);
1265 * Get the system name of the device.
1267 * @param device A previously obtained device
1268 * @return System name of the device
1271 libinput_device_get_sysname(struct libinput_device *device);
1276 * A device may be mapped to a single output, or all available outputs. If a
1277 * device is mapped to a single output only, a relative device may not move
1278 * beyond the boundaries of this output. An absolute device has its input
1279 * coordinates mapped to the extents of this output.
1281 * @return the name of the output this device is mapped to, or NULL if no
1285 libinput_device_get_output_name(struct libinput_device *device);
1290 * Get the seat associated with this input device.
1292 * A seat can be uniquely identified by the physical and logical seat name.
1293 * There will ever be only one seat instance with a given physical and logical
1294 * seat name pair at any given time, but if no external reference is kept, it
1295 * may be destroyed if no device belonging to it is left.
1297 * @param device A previously obtained device
1298 * @return The seat this input device belongs to
1300 struct libinput_seat *
1301 libinput_device_get_seat(struct libinput_device *device);
1306 * Update the LEDs on the device, if any. If the device does not have
1307 * LEDs, or does not have one or more of the LEDs given in the mask, this
1308 * function does nothing.
1310 * @param device A previously obtained device
1311 * @param leds A mask of the LEDs to set, or unset.
1314 libinput_device_led_update(struct libinput_device *device,
1315 enum libinput_led leds);
1320 * Set the bitmask in keys to the bitmask of the keys present on the device
1321 * (see linux/input.h), up to size characters.
1323 * @param device A current input device
1324 * @param keys An array filled with the bitmask for the keys
1325 * @param size Size of the keys array
1327 * @return The number of valid bytes in keys, or a negative errno on failure
1330 libinput_device_get_keys(struct libinput_device *device,
1331 char *keys, size_t size);
1336 * Apply the 3x3 transformation matrix to absolute device coordinates. This
1337 * matrix has no effect on relative events.
1339 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1347 libinput_device_calibrate(struct libinput_device *device,
1348 float calibration[6]);
1353 * Check if the given device has the specified capability
1355 * @return 1 if the given device has the capability or 0 if not
1358 libinput_device_has_capability(struct libinput_device *device,
1359 enum libinput_device_capability capability);
1364 * Get the physical size of a device in mm, where meaningful. This function
1365 * only succeeds on devices with the required data, i.e. tablets, touchpads
1368 * If this function returns nonzero, width and height are unmodified.
1370 * @param device The device
1371 * @param width Set to the width of the device
1372 * @param height Set to the height of the device
1373 * @return 0 on success, or nonzero otherwise
1376 libinput_device_get_size(struct libinput_device *device,
1384 #endif /* LIBINPUT_H */