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 * @page udev_config Static device configuration via udev
109 * libinput supports some static configuration through udev properties.
110 * These propertiesare read when the device is initially added
111 * to libinput's device list, i.e. before the @ref
112 * LIBINPUT_EVENT_DEVICE_ADDED event is generated.
114 * The following udev properties are supported:
116 * <dt>LIBINPUT_CALIBRATION_MATRIX</dt>
117 * <dd>Sets the calibration matrix, see
118 * libinput_device_config_calibration_get_default_matrix(). If unset,
119 * defaults to the identity matrix.</dd>
121 * <dd>Assigns the physical seat for this device. See
122 * libinput_seat_get_physical_name(). Defaults to "seat0".</dd>
124 * <dd>Assigns the logical seat for this device. See
125 * libinput_seat_get_logical_name()
126 * context. Defaults to "default".</dd>
129 * Below is an example udev rule to assign "seat1" to a device from vendor
130 * 0x012a with the model ID of 0x034b.
132 * ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
133 * ENV{ID_MODEL_ID}=="034b", ENV{ID_SEAT}="seat1"
139 * Log priority for internal logging messages.
141 enum libinput_log_priority {
142 LIBINPUT_LOG_PRIORITY_DEBUG = 10,
143 LIBINPUT_LOG_PRIORITY_INFO = 20,
144 LIBINPUT_LOG_PRIORITY_ERROR = 30,
150 * Capabilities on a device. A device may have one or more capabilities
151 * at a time, and capabilities may appear or disappear during the
152 * lifetime of the device.
154 enum libinput_device_capability {
155 LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
156 LIBINPUT_DEVICE_CAP_POINTER = 1,
157 LIBINPUT_DEVICE_CAP_TOUCH = 2
163 * Logical state of a key. Note that the logical state may not represent
164 * the physical state of the key.
166 enum libinput_key_state {
167 LIBINPUT_KEY_STATE_RELEASED = 0,
168 LIBINPUT_KEY_STATE_PRESSED = 1
174 * Mask reflecting LEDs on a device.
177 LIBINPUT_LED_NUM_LOCK = (1 << 0),
178 LIBINPUT_LED_CAPS_LOCK = (1 << 1),
179 LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
185 * Logical state of a physical button. Note that the logical state may not
186 * represent the physical state of the button.
188 enum libinput_button_state {
189 LIBINPUT_BUTTON_STATE_RELEASED = 0,
190 LIBINPUT_BUTTON_STATE_PRESSED = 1
197 * Axes on a device that are not x or y coordinates.
199 enum libinput_pointer_axis {
200 LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0,
201 LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1,
207 * Event type for events returned by libinput_get_event().
209 enum libinput_event_type {
211 * This is not a real event type, and is only used to tell the user that
212 * no new event is available in the queue. See
213 * libinput_next_event_type().
215 LIBINPUT_EVENT_NONE = 0,
218 * Signals that a device has been added to the context. The device will
219 * not be read until the next time the user calls libinput_dispatch()
220 * and data is available.
222 * This allows setting up initial device configuration before any events
225 LIBINPUT_EVENT_DEVICE_ADDED,
228 * Signals that a device has been removed. No more events from the
229 * associated device will be in the queue or be queued after this event.
231 LIBINPUT_EVENT_DEVICE_REMOVED,
233 LIBINPUT_EVENT_KEYBOARD_KEY = 300,
235 LIBINPUT_EVENT_POINTER_MOTION = 400,
236 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
237 LIBINPUT_EVENT_POINTER_BUTTON,
238 LIBINPUT_EVENT_POINTER_AXIS,
240 LIBINPUT_EVENT_TOUCH_DOWN = 500,
241 LIBINPUT_EVENT_TOUCH_UP,
242 LIBINPUT_EVENT_TOUCH_MOTION,
243 LIBINPUT_EVENT_TOUCH_CANCEL,
245 * Signals the end of a set of touchpoints at one device sample
246 * time. This event has no coordinate information attached.
248 LIBINPUT_EVENT_TOUCH_FRAME
252 struct libinput_device;
253 struct libinput_seat;
255 struct libinput_event;
256 struct libinput_event_device_notify;
257 struct libinput_event_keyboard;
258 struct libinput_event_pointer;
261 * @ingroup event_touch
262 * @struct libinput_event_touch
264 * Touch event representing a touch down, move or up, as well as a touch
265 * cancel and touch frame events. Valid event types for this event are @ref
266 * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
267 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
268 * LIBINPUT_EVENT_TOUCH_FRAME.
270 struct libinput_event_touch;
273 * @defgroup event Accessing and destruction of events
281 * @param event An event retrieved by libinput_get_event().
284 libinput_event_destroy(struct libinput_event *event);
289 * Get the type of the event.
291 * @param event An event retrieved by libinput_get_event().
293 enum libinput_event_type
294 libinput_event_get_type(struct libinput_event *event);
299 * Get the libinput context from the event.
301 * @param event The libinput event
302 * @return The libinput context for this event.
305 libinput_event_get_context(struct libinput_event *event);
310 * Return the device associated with this event, if applicable. For device
311 * added/removed events this is the device added or removed. For all other
312 * device events, this is the device that generated the event.
314 * This device is not refcounted and its lifetime is that of the event. Use
315 * libinput_device_ref() before using the device outside of this scope.
317 * @return The device associated with this event
320 struct libinput_device *
321 libinput_event_get_device(struct libinput_event *event);
326 * Return the pointer event that is this input event. If the event type does
327 * not match the pointer event types, this function returns NULL.
329 * The inverse of this function is libinput_event_pointer_get_base_event().
331 * @return A pointer event, or NULL for other events
333 struct libinput_event_pointer *
334 libinput_event_get_pointer_event(struct libinput_event *event);
339 * Return the keyboard event that is this input event. If the event type does
340 * not match the keyboard event types, this function returns NULL.
342 * The inverse of this function is libinput_event_keyboard_get_base_event().
344 * @return A keyboard event, or NULL for other events
346 struct libinput_event_keyboard *
347 libinput_event_get_keyboard_event(struct libinput_event *event);
352 * Return the touch event that is this input event. If the event type does
353 * not match the touch event types, this function returns NULL.
355 * The inverse of this function is libinput_event_touch_get_base_event().
357 * @return A touch event, or NULL for other events
359 struct libinput_event_touch *
360 libinput_event_get_touch_event(struct libinput_event *event);
365 * Return the device event that is this input event. If the event type does
366 * not match the device event types, this function returns NULL.
368 * The inverse of this function is
369 * libinput_event_device_notify_get_base_event().
371 * @return A device event, or NULL for other events
373 struct libinput_event_device_notify *
374 libinput_event_get_device_notify_event(struct libinput_event *event);
379 * @return The generic libinput_event of this event
381 struct libinput_event *
382 libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
385 * @defgroup event_keyboard Keyboard events
387 * Key events are generated when a key changes its logical state, usually by
388 * being pressed or released.
392 * @ingroup event_keyboard
394 * @return The event time for this event
397 libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
400 * @ingroup event_keyboard
402 * @return The keycode that triggered this key event
405 libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
408 * @ingroup event_keyboard
410 * @return The state change of the key
412 enum libinput_key_state
413 libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
417 * @ingroup event_keyboard
419 * @return The generic libinput_event of this event
421 struct libinput_event *
422 libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
425 * @ingroup event_keyboard
427 * For the key of a LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
428 * of keys pressed on all devices on the associated seat after the event was
431 " @note It is an application bug to call this function for events other than
432 * LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
434 * @return the seat wide pressed key count for the key of this event
437 libinput_event_keyboard_get_seat_key_count(
438 struct libinput_event_keyboard *event);
441 * @defgroup event_pointer Pointer events
443 * Pointer events reflect motion, button and scroll events, as well as
444 * events from other axes.
448 * @ingroup event_pointer
450 * @return The event time for this event
453 libinput_event_pointer_get_time(struct libinput_event_pointer *event);
456 * @ingroup event_pointer
458 * Return the delta between the last event and the current event. For pointer
459 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
462 * If a device employs pointer acceleration, the delta returned by this
463 * function is the accelerated delta.
465 * @note It is an application bug to call this function for events other than
466 * LIBINPUT_EVENT_POINTER_MOTION.
468 * @return the relative x movement since the last event
471 libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
474 * @ingroup event_pointer
476 * Return the delta between the last event and the current event. For pointer
477 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
480 * If a device employs pointer acceleration, the delta returned by this
481 * function is the accelerated delta.
483 * @note It is an application bug to call this function for events other than
484 * LIBINPUT_EVENT_POINTER_MOTION.
486 * @return the relative y movement since the last event
489 libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
492 * @ingroup event_pointer
494 * Return the current absolute x coordinate of the pointer event, in mm from
495 * the top left corner of the device. To get the corresponding output screen
496 * coordinate, use libinput_event_pointer_get_absolute_x_transformed().
498 * For pointer events that are not of type
499 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
501 * @note It is an application bug to call this function for events other than
502 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
504 * @return the current absolute x coordinate
507 libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
510 * @ingroup event_pointer
512 * Return the current absolute y coordinate of the pointer event, in mm from
513 * the top left corner of the device. To get the corresponding output screen
514 * coordinate, use libinput_event_pointer_get_absolute_y_transformed().
516 * For pointer events that are not of type
517 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
519 * @note It is an application bug to call this function for events other than
520 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
522 * @return the current absolute y coordinate
525 libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
528 * @ingroup event_pointer
530 * Return the current absolute x coordinate of the pointer event, transformed to
531 * screen coordinates.
533 * For pointer events that are not of type
534 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
537 * @note It is an application bug to call this function for events other than
538 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
540 * @param event The libinput pointer event
541 * @param width The current output screen width
542 * @return the current absolute x coordinate transformed to a screen coordinate
545 libinput_event_pointer_get_absolute_x_transformed(
546 struct libinput_event_pointer *event,
550 * @ingroup event_pointer
552 * Return the current absolute y coordinate of the pointer event, transformed to
553 * screen coordinates.
555 * For pointer events that are not of type
556 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
559 * @note It is an application bug to call this function for events other than
560 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
562 * @param event The libinput pointer event
563 * @param height The current output screen height
564 * @return the current absolute y coordinate transformed to a screen coordinate
567 libinput_event_pointer_get_absolute_y_transformed(
568 struct libinput_event_pointer *event,
572 * @ingroup event_pointer
574 * Return the button that triggered this event.
575 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
576 * this function returns 0.
578 * @note It is an application bug to call this function for events other than
579 * LIBINPUT_EVENT_POINTER_BUTTON.
581 * @return the button triggering this event
584 libinput_event_pointer_get_button(struct libinput_event_pointer *event);
587 * @ingroup event_pointer
589 * Return the button state that triggered this event.
590 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
591 * this function returns 0.
593 * @note It is an application bug to call this function for events other than
594 * LIBINPUT_EVENT_POINTER_BUTTON.
596 * @return the button state triggering this event
598 enum libinput_button_state
599 libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
602 * @ingroup event_pointer
604 * For the button of a LIBINPUT_EVENT_POINTER_BUTTON event, return the total
605 * number of buttons pressed on all devices on the associated seat after the
606 * the event was triggered.
608 " @note It is an application bug to call this function for events other than
609 * LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function returns 0.
611 * @return the seat wide pressed button count for the key of this event
614 libinput_event_pointer_get_seat_button_count(
615 struct libinput_event_pointer *event);
618 * @ingroup event_pointer
620 * Return the axis that triggered this event.
621 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
622 * this function returns 0.
624 * @note It is an application bug to call this function for events other than
625 * LIBINPUT_EVENT_POINTER_AXIS.
627 * @return the axis triggering this event
629 enum libinput_pointer_axis
630 libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
633 * @ingroup event_pointer
635 * Return the axis value of the given axis. The interpretation of the value
636 * is dependent on the axis. For the two scrolling axes
637 * LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
638 * LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in
639 * relative scroll units, with the positive direction being down or right,
640 * respectively. The dimension of a scroll unit is equal to one unit of
641 * motion in the respective axis, where applicable (e.g. touchpad two-finger
644 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
645 * this function returns 0.
647 * @note It is an application bug to call this function for events other than
648 * LIBINPUT_EVENT_POINTER_AXIS.
650 * @return the axis value of this event
653 libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
656 * @ingroup event_pointer
658 * @return The generic libinput_event of this event
660 struct libinput_event *
661 libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
665 * @defgroup event_touch Touch events
667 * Events from absolute touch devices.
671 * @ingroup event_touch
673 * @return The event time for this event
676 libinput_event_touch_get_time(struct libinput_event_touch *event);
679 * @ingroup event_touch
681 * Get the slot of this touch event. See the kernel's multitouch
682 * protocol B documentation for more information.
684 * If the touch event has no assigned slot, for example if it is from a
685 * single touch device, this function returns -1.
687 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
688 * LIBINPUT_EVENT_TOUCH_FRAME.
690 * @return The slot of this touch event
693 libinput_event_touch_get_slot(struct libinput_event_touch *event);
696 * @ingroup event_touch
698 * Get the seat slot of the touch event. A seat slot is a non-negative seat
699 * wide unique identifier of an active touch point.
701 * Events from single touch devices will be represented as one individual
702 * touch point per device.
704 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
705 * LIBINPUT_EVENT_TOUCH_FRAME.
707 * @return The seat slot of the touch event
710 libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
713 * @ingroup event_touch
715 * Return the current absolute x coordinate of the touch event, in mm from
716 * the top left corner of the device. To get the corresponding output screen
717 * coordinate, use libinput_event_touch_get_x_transformed().
719 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
720 * LIBINPUT_EVENT_TOUCH_MOTION.
722 * @param event The libinput touch event
723 * @return the current absolute x coordinate
726 libinput_event_touch_get_x(struct libinput_event_touch *event);
729 * @ingroup event_touch
731 * Return the current absolute y coordinate of the touch event, in mm from
732 * the top left corner of the device. To get the corresponding output screen
733 * coordinate, use libinput_event_touch_get_y_transformed().
735 * For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
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 * @return the current absolute y coordinate
744 libinput_event_touch_get_y(struct libinput_event_touch *event);
747 * @ingroup event_touch
749 * Return the current absolute x coordinate of the touch event, transformed to
750 * screen coordinates.
752 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
753 * LIBINPUT_EVENT_TOUCH_MOTION.
755 * @param event The libinput touch event
756 * @param width The current output screen width
757 * @return the current absolute x coordinate transformed to a screen coordinate
760 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
764 * @ingroup event_touch
766 * Return the current absolute y coordinate of the touch event, transformed to
767 * screen coordinates.
769 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
770 * LIBINPUT_EVENT_TOUCH_MOTION.
772 * @param event The libinput touch event
773 * @param height The current output screen height
774 * @return the current absolute y coordinate transformed to a screen coordinate
777 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
781 * @ingroup event_touch
783 * @return The generic libinput_event of this event
785 struct libinput_event *
786 libinput_event_touch_get_base_event(struct libinput_event_touch *event);
789 * @defgroup base Initialization and manipulation of libinput contexts
792 struct libinput_interface {
794 * Open the device at the given path with the flags provided and
797 * @param path The device path to open
798 * @param flags Flags as defined by open(2)
799 * @param user_data The user_data provided in
800 * libinput_udev_create_context()
802 * @return the file descriptor, or a negative errno on failure.
804 int (*open_restricted)(const char *path, int flags, void *user_data);
806 * Close the file descriptor.
808 * @param fd The file descriptor to close
809 * @param user_data The user_data provided in
810 * libinput_udev_create_context()
812 void (*close_restricted)(int fd, void *user_data);
818 * Create a new libinput context from udev. This context is inactive until
819 * assigned a seat ID with libinput_udev_assign_seat().
821 * @param interface The callback interface
822 * @param user_data Caller-specific data passed to the various callback
824 * @param udev An already initialized udev context
826 * @return An initialized, but inactive libinput context or NULL on error
829 libinput_udev_create_context(const struct libinput_interface *interface,
836 * Assign a seat to this libinput context. New devices or the removal of
837 * existing devices will appear as events during libinput_dispatch().
839 * libinput_udev_assign_seat() succeeds even if no input devices are currently
840 * available on this seat, or if devices are available but fail to open in
841 * @ref libinput_interface::open_restricted. Devices that do not have the
842 * minimum capabilities to be recognized as pointer, keyboard or touch
843 * device are ignored. Such devices and those that failed to open
844 * ignored until the next call to libinput_resume().
846 * This function may only be called once per context.
848 * @param libinput A libinput context initialized with
849 * libinput_udev_create_context()
850 * @param seat_id A seat identifier. This string must not be NULL.
852 * @return 0 on success or -1 on failure.
855 libinput_udev_assign_seat(struct libinput *libinput,
856 const char *seat_id);
861 * Create a new libinput context that requires the caller to manually add or
862 * remove devices with libinput_path_add_device() and
863 * libinput_path_remove_device().
865 * The context is fully initialized but will not generate events until at
866 * least one device has been added.
868 * The reference count of the context is initialized to 1. See @ref
871 * @param interface The callback interface
872 * @param user_data Caller-specific data passed to the various callback
875 * @return An initialized, empty libinput context.
878 libinput_path_create_context(const struct libinput_interface *interface,
884 * Add a device to a libinput context initialized with
885 * libinput_path_create_context(). If successful, the device will be
886 * added to the internal list and re-opened on libinput_resume(). The device
887 * can be removed with libinput_path_remove_device().
889 * If the device was successfully initialized, it is returned in the device
890 * argument. The lifetime of the returned device pointer is limited until
891 * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent
894 * @param libinput A previously initialized libinput context
895 * @param path Path to an input device
896 * @return The newly initiated device on success, or NULL on failure.
898 * @note It is an application bug to call this function on a libinput
899 * context initialized with libinput_udev_create_context().
901 struct libinput_device *
902 libinput_path_add_device(struct libinput *libinput,
908 * Remove a device from a libinput context initialized with
909 * libinput_path_create_context() or added to such a context with
910 * libinput_path_add_device().
912 * Events already processed from this input device are kept in the queue,
913 * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
916 * If no matching device exists, this function does nothing.
918 * @param device A libinput device
920 * @note It is an application bug to call this function on a libinput
921 * context initialized with libinput_udev_create_context().
924 libinput_path_remove_device(struct libinput_device *device);
929 * libinput keeps a single file descriptor for all events. Call into
930 * libinput_dispatch() if any events become available on this fd.
932 * @return the file descriptor used to notify of pending events.
935 libinput_get_fd(struct libinput *libinput);
940 * Main event dispatchment function. Reads events of the file descriptors
941 * and processes them internally. Use libinput_get_event() to retrieve the
944 * Dispatching does not necessarily queue libinput events.
946 * @param libinput A previously initialized libinput context
948 * @return 0 on success, or a negative errno on failure
951 libinput_dispatch(struct libinput *libinput);
956 * Retrieve the next event from libinput's internal event queue.
958 * After handling the retrieved event, the caller must destroy it using
959 * libinput_event_destroy().
961 * @param libinput A previously initialized libinput context
962 * @return The next available event, or NULL if no event is available.
964 struct libinput_event *
965 libinput_get_event(struct libinput *libinput);
970 * Return the type of the next event in the internal queue. This function
971 * does not pop the event off the queue and the next call to
972 * libinput_get_event() returns that event.
974 * @param libinput A previously initialized libinput context
975 * @return The event type of the next available event or LIBINPUT_EVENT_NONE
976 * if no event is availble.
978 enum libinput_event_type
979 libinput_next_event_type(struct libinput *libinput);
984 * @param libinput A previously initialized libinput context
985 * @return the caller-specific data previously assigned in
986 * libinput_create_udev().
989 libinput_get_user_data(struct libinput *libinput);
994 * Resume a suspended libinput context. This re-enables device
995 * monitoring and adds existing devices.
997 * @param libinput A previously initialized libinput context
998 * @see libinput_suspend
1000 * @return 0 on success or -1 on failure
1003 libinput_resume(struct libinput *libinput);
1008 * Suspend monitoring for new devices and close existing devices.
1009 * This all but terminates libinput but does keep the context
1010 * valid to be resumed with libinput_resume().
1012 * @param libinput A previously initialized libinput context
1015 libinput_suspend(struct libinput *libinput);
1020 * Add a reference to the context. A context is destroyed whenever the
1021 * reference count reaches 0. See @ref libinput_unref.
1023 * @param libinput A previously initialized valid libinput context
1024 * @return The passed libinput context
1027 libinput_ref(struct libinput *libinput);
1032 * Dereference the libinput context. After this, the context may have been
1033 * destroyed, if the last reference was dereferenced. If so, the context is
1034 * invalid and may not be interacted with.
1036 * @param libinput A previously initialized libinput context
1037 * @return NULL if context was destroyed otherwise the passed context
1040 libinput_unref(struct libinput *libinput);
1045 * Set the global log priority. Messages with priorities equal to or
1046 * higher than the argument will be printed to the current log handler.
1048 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1050 * @param libinput A previously initialized libinput context
1051 * @param priority The minimum priority of log messages to print.
1053 * @see libinput_log_set_handler
1054 * @see libinput_log_get_priority
1057 libinput_log_set_priority(struct libinput *libinput,
1058 enum libinput_log_priority priority);
1063 * Get the global log priority. Messages with priorities equal to or
1064 * higher than the argument will be printed to the current log handler.
1066 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1068 * @param libinput A previously initialized libinput context
1069 * @return The minimum priority of log messages to print.
1071 * @see libinput_log_set_handler
1072 * @see libinput_log_set_priority
1074 enum libinput_log_priority
1075 libinput_log_get_priority(const struct libinput *libinput);
1080 * Log handler type for custom logging.
1082 * @param libinput The libinput context
1083 * @param priority The priority of the current message
1084 * @param format Message format in printf-style
1085 * @param args Message arguments
1087 * @see libinput_set_log_priority
1088 * @see libinput_log_set_handler
1090 typedef void (*libinput_log_handler)(struct libinput *libinput,
1091 enum libinput_log_priority priority,
1092 const char *format, va_list args)
1093 LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
1098 * Set the global log handler. Messages with priorities equal to or higher
1099 * than the current log priority will be passed to the given
1102 * The default log handler prints to stderr.
1104 * @param libinput A previously initialized libinput context
1105 * @param log_handler The log handler for library messages.
1106 * @param user_data Caller-specific data pointer, passed into the log
1109 * @see libinput_log_set_handler
1112 libinput_log_set_handler(struct libinput *libinput,
1113 libinput_log_handler log_handler);
1116 * @defgroup seat Initialization and manipulation of seats
1118 * A seat has two identifiers, the physical name and the logical name. The
1119 * physical name is summarized as the list of devices a process on the same
1120 * physical seat has access to.
1122 * The logical seat name is the seat name for a logical group of devices. A
1123 * compositor may use that to create additonal seats as independent device
1124 * sets. Alternatively, a compositor may limit itself to a single logical
1125 * seat, leaving a second compositor to manage devices on the other logical
1129 * +---+--------+------------+------------------------+------------+
1130 * | | event0 | | | log seat A |
1131 * | K +--------+ | +------------+
1132 * | e | event1 | phys seat0 | libinput context 1 | |
1133 * | r +--------+ | | log seat B |
1134 * | n | event2 | | | |
1135 * | e +--------+------------+------------------------+------------+
1136 * | l | event3 | phys seat1 | libinput context 2 | log seat C |
1137 * +---+--------+------------+------------------------+------------+
1144 * Increase the refcount of the seat. A seat will be freed whenever the
1145 * refcount reaches 0. This may happen during dispatch if the
1146 * seat was removed from the system. A caller must ensure to reference
1147 * the seat correctly to avoid dangling pointers.
1149 * @param seat A previously obtained seat
1150 * @return The passed seat
1152 struct libinput_seat *
1153 libinput_seat_ref(struct libinput_seat *seat);
1158 * Decrease the refcount of the seat. A seat will be freed whenever the
1159 * refcount reaches 0. This may happen during dispatch if the
1160 * seat was removed from the system. A caller must ensure to reference
1161 * the seat correctly to avoid dangling pointers.
1163 * @param seat A previously obtained seat
1164 * @return NULL if seat was destroyed, otherwise the passed seat
1166 struct libinput_seat *
1167 libinput_seat_unref(struct libinput_seat *seat);
1172 * Set caller-specific data associated with this seat. libinput does
1173 * not manage, look at, or modify this data. The caller must ensure the
1176 * @param seat A previously obtained seat
1177 * @param user_data Caller-specific data pointer
1178 * @see libinput_seat_get_user_data
1181 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
1186 * Get the caller-specific data associated with this seat, if any.
1188 * @param seat A previously obtained seat
1189 * @return Caller-specific data pointer or NULL if none was set
1190 * @see libinput_seat_set_user_data
1193 libinput_seat_get_user_data(struct libinput_seat *seat);
1198 * Return the physical name of the seat. For libinput contexts created from
1199 * udev, this is always the same value as passed into
1200 * libinput_udev_assign_seat() and all seats from that context will have
1201 * the same physical name.
1203 * The physical name of the seat is one that is usually set by the system or
1204 * lower levels of the stack. In most cases, this is the base filter for
1205 * devices - devices assigned to seats outside the current seat will not
1206 * be available to the caller.
1208 * @param seat A previously obtained seat
1209 * @return the physical name of this seat
1212 libinput_seat_get_physical_name(struct libinput_seat *seat);
1217 * Return the logical name of the seat. This is an identifier to group sets
1218 * of devices within the compositor.
1220 * @param seat A previously obtained seat
1221 * @return the logical name of this seat
1224 libinput_seat_get_logical_name(struct libinput_seat *seat);
1227 * @defgroup device Initialization and manipulation of input devices
1233 * Increase the refcount of the input device. An input device will be freed
1234 * whenever the refcount reaches 0. This may happen during dispatch if the
1235 * device was removed from the system. A caller must ensure to reference
1236 * the device correctly to avoid dangling pointers.
1238 * @param device A previously obtained device
1239 * @return The passed device
1241 struct libinput_device *
1242 libinput_device_ref(struct libinput_device *device);
1247 * Decrease the refcount of the input device. An input device will be freed
1248 * whenever the refcount reaches 0. This may happen during dispatch if the
1249 * device was removed from the system. A caller must ensure to reference
1250 * the device correctly to avoid dangling pointers.
1252 * @param device A previously obtained device
1253 * @return NULL if device was destroyed, otherwise the passed device
1255 struct libinput_device *
1256 libinput_device_unref(struct libinput_device *device);
1261 * Set caller-specific data associated with this input device. libinput does
1262 * not manage, look at, or modify this data. The caller must ensure the
1265 * @param device A previously obtained device
1266 * @param user_data Caller-specific data pointer
1267 * @see libinput_device_get_user_data
1270 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1275 * Get the caller-specific data associated with this input device, if any.
1277 * @param device A previously obtained device
1278 * @return Caller-specific data pointer or NULL if none was set
1279 * @see libinput_device_set_user_data
1282 libinput_device_get_user_data(struct libinput_device *device);
1287 * Get the system name of the device.
1289 * To get the descriptive device name, use libinput_device_get_name().
1291 * @param device A previously obtained device
1292 * @return System name of the device
1296 libinput_device_get_sysname(struct libinput_device *device);
1301 * The descriptive device name as advertised by the kernel and/or the
1302 * hardware itself. To get the sysname for this device, use
1303 * libinput_device_get_sysname().
1305 * The lifetime of the returned string is tied to the struct
1306 * libinput_device. The string may be the empty string but is never NULL.
1308 * @param device A previously obtained device
1309 * @return The device name
1312 libinput_device_get_name(struct libinput_device *device);
1317 * Get the product ID for this device.
1319 * @param device A previously obtained device
1320 * @return The product ID of this device
1323 libinput_device_get_id_product(struct libinput_device *device);
1328 * Get the vendor ID for this device.
1330 * @param device A previously obtained device
1331 * @return The vendor ID of this device
1334 libinput_device_get_id_vendor(struct libinput_device *device);
1339 * A device may be mapped to a single output, or all available outputs. If a
1340 * device is mapped to a single output only, a relative device may not move
1341 * beyond the boundaries of this output. An absolute device has its input
1342 * coordinates mapped to the extents of this output.
1344 * @return the name of the output this device is mapped to, or NULL if no
1348 libinput_device_get_output_name(struct libinput_device *device);
1353 * Get the seat associated with this input device.
1355 * A seat can be uniquely identified by the physical and logical seat name.
1356 * There will ever be only one seat instance with a given physical and logical
1357 * seat name pair at any given time, but if no external reference is kept, it
1358 * may be destroyed if no device belonging to it is left.
1360 * @param device A previously obtained device
1361 * @return The seat this input device belongs to
1363 struct libinput_seat *
1364 libinput_device_get_seat(struct libinput_device *device);
1369 * Update the LEDs on the device, if any. If the device does not have
1370 * LEDs, or does not have one or more of the LEDs given in the mask, this
1371 * function does nothing.
1373 * @param device A previously obtained device
1374 * @param leds A mask of the LEDs to set, or unset.
1377 libinput_device_led_update(struct libinput_device *device,
1378 enum libinput_led leds);
1383 * Set the bitmask in keys to the bitmask of the keys present on the device
1384 * (see linux/input.h), up to size characters.
1386 * @param device A current input device
1387 * @param keys An array filled with the bitmask for the keys
1388 * @param size Size of the keys array
1390 * @return The number of valid bytes in keys, or a negative errno on failure
1393 libinput_device_get_keys(struct libinput_device *device,
1394 char *keys, size_t size)
1395 LIBINPUT_ATTRIBUTE_DEPRECATED;
1400 * @deprecated Use libinput_device_config_calibration_set_matrix() instead.
1403 libinput_device_calibrate(struct libinput_device *device,
1404 float calibration[6])
1405 LIBINPUT_ATTRIBUTE_DEPRECATED;
1410 * Check if the given device has the specified capability
1412 * @return 1 if the given device has the capability or 0 if not
1415 libinput_device_has_capability(struct libinput_device *device,
1416 enum libinput_device_capability capability);
1421 * Get the physical size of a device in mm, where meaningful. This function
1422 * only succeeds on devices with the required data, i.e. tablets, touchpads
1425 * If this function returns nonzero, width and height are unmodified.
1427 * @param device The device
1428 * @param width Set to the width of the device
1429 * @param height Set to the height of the device
1430 * @return 0 on success, or nonzero otherwise
1433 libinput_device_get_size(struct libinput_device *device,
1439 * @defgroup config Device configuration
1441 * Enable, disable, change and/or check for device-specific features. For
1442 * all features, libinput assigns a default based on the hardware
1443 * configuration. This default can be obtained with the respective
1446 * Some configuration option may be dependent on or mutually exclusive with
1447 * with other options. The behavior in those cases is
1448 * implementation-defined, the caller must ensure that the options are set
1449 * in the right order.
1455 * Status codes returned when applying configuration settings.
1457 enum libinput_config_status {
1458 LIBINPUT_CONFIG_STATUS_SUCCESS = 0, /**< Config applied successfully */
1459 LIBINPUT_CONFIG_STATUS_UNSUPPORTED, /**< Configuration not available on
1461 LIBINPUT_CONFIG_STATUS_INVALID, /**< Invalid parameter range */
1467 * Return a string describing the error.
1469 * @param status The status to translate to a string
1470 * @return A human-readable string representing the error or NULL for an
1474 libinput_config_status_to_str(enum libinput_config_status status);
1479 enum libinput_config_tap_state {
1480 LIBINPUT_CONFIG_TAP_DISABLED, /**< Tapping is to be disabled, or is
1481 currently disabled */
1482 LIBINPUT_CONFIG_TAP_ENABLED, /**< Tapping is to be enabled, or is
1483 currently enabled */
1489 * Check if the device supports tap-to-click. See
1490 * libinput_device_config_tap_set_enabled() for more information.
1492 * @param device The device to configure
1493 * @return The number of fingers that can generate a tap event, or 0 if the
1494 * device does not support tapping.
1496 * @see libinput_device_config_tap_set_enabled
1497 * @see libinput_device_config_tap_get_enabled
1498 * @see libinput_device_config_tap_get_default_enabled
1501 libinput_device_config_tap_get_finger_count(struct libinput_device *device);
1506 * Enable or disable tap-to-click on this device, with a default mapping of
1507 * 1, 2, 3 finger tap mapping to left, right, middle click, respectively.
1508 * Tapping is limited by the number of simultaneous touches
1509 * supported by the device, see
1510 * libinput_device_config_tap_get_finger_count().
1512 * @param device The device to configure
1513 * @param enable @ref LIBINPUT_CONFIG_TAP_ENABLED to enable tapping or @ref
1514 * LIBINPUT_CONFIG_TAP_DISABLED to disable tapping
1516 * @return A config status code. Disabling tapping on a device that does not
1517 * support tapping always succeeds.
1519 * @see libinput_device_config_tap_get_finger_count
1520 * @see libinput_device_config_tap_get_enabled
1521 * @see libinput_device_config_tap_get_default_enabled
1523 enum libinput_config_status
1524 libinput_device_config_tap_set_enabled(struct libinput_device *device,
1525 enum libinput_config_tap_state enable);
1530 * Check if tap-to-click is enabled on this device. If the device does not
1531 * support tapping, this function always returns 0.
1533 * @param device The device to configure
1535 * @return @ref LIBINPUT_CONFIG_TAP_ENABLED if tapping is currently enabled,
1536 * or @ref LIBINPUT_CONFIG_TAP_DISABLED is currently disabled
1538 * @see libinput_device_config_tap_get_finger_count
1539 * @see libinput_device_config_tap_set_enabled
1540 * @see libinput_device_config_tap_get_default_enabled
1542 enum libinput_config_tap_state
1543 libinput_device_config_tap_get_enabled(struct libinput_device *device);
1548 * Return the default setting for whether tapping is enabled on this device.
1550 * @param device The device to configure
1551 * @return @ref LIBINPUT_CONFIG_TAP_ENABLED if tapping is enabled by default,
1552 * or @ref LIBINPUT_CONFIG_TAP_DISABLED is disabled by default
1554 * @see libinput_device_config_tap_get_finger_count
1555 * @see libinput_device_config_tap_set_enabled
1556 * @see libinput_device_config_tap_get_enabled
1558 enum libinput_config_tap_state
1559 libinput_device_config_tap_get_default_enabled(struct libinput_device *device);
1564 * Check if the device can be calibrated via a calibration matrix.
1566 * @param device The device to check
1567 * @return non-zero if the device can be calibrated, zero otherwise.
1569 * @see libinput_device_config_calibration_set_matrix
1570 * @see libinput_device_config_calibration_get_matrix
1571 * @see libinput_device_config_calibration_get_default_matrix
1574 libinput_device_config_calibration_has_matrix(struct libinput_device *device);
1579 * Apply the 3x3 transformation matrix to absolute device coordinates. This
1580 * matrix has no effect on relative events.
1582 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1589 * The translation component (c, f) is expected to be normalized to the
1590 * device coordinate range. For example, the matrix
1596 * moves all coordinates by 1 device-width to the right and 1 device-height
1599 * The rotation matrix for rotation around the origin is defined as
1601 * [ cos(a) -sin(a) 0 ]
1602 * [ sin(a) cos(a) 0 ]
1605 * Note that any rotation requires an additional translation component to
1606 * translate the rotated coordinates back into the original device space.
1607 * The rotation matrixes for 90, 180 and 270 degrees clockwise are:
1609 * 90 deg cw: 180 deg cw: 270 deg cw:
1610 * [ 0 -1 1] [ -1 0 1] [ 0 1 0 ]
1611 * [ 1 0 0] [ 0 -1 1] [ -1 0 1 ]
1612 * [ 0 0 1] [ 0 0 1] [ 0 0 1 ]
1615 * @param device The device to configure
1616 * @param matrix An array representing the first two rows of a 3x3 matrix as
1619 * @return A config status code.
1621 * @see libinput_device_config_calibration_has_matrix
1622 * @see libinput_device_config_calibration_get_matrix
1623 * @see libinput_device_config_calibration_get_default_matrix
1625 enum libinput_config_status
1626 libinput_device_config_calibration_set_matrix(struct libinput_device *device,
1627 const float matrix[6]);
1632 * Return the current calibration matrix for this device.
1634 * @param device The device to configure
1635 * @param matrix Set to the array representing the first two rows of a 3x3 matrix as
1636 * described in libinput_device_config_calibration_set_matrix().
1638 * @return 0 if no calibration is set and the returned matrix is the
1639 * identity matrix, 1 otherwise
1641 * @see libinput_device_config_calibration_has_matrix
1642 * @see libinput_device_config_calibration_set_matrix
1643 * @see libinput_device_config_calibration_get_default_matrix
1646 libinput_device_config_calibration_get_matrix(struct libinput_device *device,
1652 * Return the default calibration matrix for this device. On most devices,
1653 * this is the identity matrix. If the udev property
1654 * <b>LIBINPUT_CALIBRATION_MATRIX</b> is set on the respective udev device,
1655 * that property's value becomes the default matrix.
1657 * The udev property is parsed as 6 floating point numbers separated by a
1658 * single space each (scanf(3) format "%f %f %f %f %f %f").
1659 * The 6 values represent the first two rows of the calibration matrix as
1660 * described in libinput_device_config_calibration_set_matrix().
1662 * Example values are:
1664 * ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
1665 * ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
1666 * ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
1667 * ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
1668 * ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 1 0 0" # reflect along y axis
1671 * @param device The device to configure
1672 * @param matrix Set to the array representing the first two rows of a 3x3 matrix as
1673 * described in libinput_device_config_calibration_set_matrix().
1675 * @return 0 if no calibration is set and the returned matrix is the
1676 * identity matrix, 1 otherwise
1678 * @see libinput_device_config_calibration_has_matrix
1679 * @see libinput_device_config_calibration_set_matrix
1680 * @see libinput_device_config_calibration_get_default_matrix
1683 libinput_device_config_calibration_get_default_matrix(struct libinput_device *device,
1687 * The send-event mode of a device defines when a device may generate events
1688 * and pass those events to the caller.
1690 enum libinput_config_send_events_mode {
1692 * Send events from this device normally.
1694 LIBINPUT_CONFIG_SEND_EVENTS_ENABLED = (1 << 0),
1696 * Do not send events through this device. Depending on the device,
1697 * this may close all file descriptors on the device or it may leave
1698 * the file descriptors open and route events through a different
1701 LIBINPUT_CONFIG_SEND_EVENTS_DISABLED = (1 << 1),
1703 * If an external pointer device is plugged in, do not send events
1704 * from this device. This option may be available on built-in
1707 LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE = (1 << 2),
1713 * Return the possible send-event modes for this device. These modes define
1714 * when a device may process and send events.
1716 * @param device The device to configure
1718 * @return A bitmask of possible modes.
1720 * @see libinput_device_config_send_events_set_mode
1721 * @see libinput_device_config_send_events_get_mode
1722 * @see libinput_device_config_send_events_get_default_mode
1725 libinput_device_config_send_events_get_modes(struct libinput_device *device);
1728 * Set the send-event mode for this device. The mode defines when the device
1729 * processes and sends events to the caller.
1731 * The selected mode may not take effect immediately. Events already
1732 * received and processed from this device are unaffected and will be passed
1733 * to the caller on the next call to libinput_get_event().
1735 * If the mode is one of @ref LIBINPUT_CONFIG_SEND_EVENTS_DISABLED or
1736 * @ref LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE, the device
1737 * may wait for or generate events until it is in a neutral state.
1738 * For example, this may include waiting for or generating button release
1741 * If the device is already suspended, this function does nothing and
1742 * returns success. Changing the send-event mode on a device that has been
1743 * removed is permitted.
1745 * @param device The device to configure
1746 * @param mode The send-event mode for this device.
1748 * @return A config status code.
1750 * @see libinput_device_config_send_events_get_modes
1751 * @see libinput_device_config_send_events_get_mode
1752 * @see libinput_device_config_send_events_get_default_mode
1754 enum libinput_config_status
1755 libinput_device_config_send_events_set_mode(struct libinput_device *device,
1756 enum libinput_config_send_events_mode mode);
1759 * Get the send-event mode for this device. The mode defines when the device
1760 * processes and sends events to the caller.
1762 * @param device The device to configure
1763 * @return The current send-event mode for this device.
1765 * @see libinput_device_config_send_events_get_modes
1766 * @see libinput_device_config_send_events_set_mode
1767 * @see libinput_device_config_send_events_get_default_mode
1769 enum libinput_config_send_events_mode
1770 libinput_device_config_send_events_get_mode(struct libinput_device *device);
1773 * Get the default send-event mode for this device. The mode defines when
1774 * the device processes and sends events to the caller.
1776 * @param device The device to configure
1777 * @return The current send-event mode for this device.
1779 * @see libinput_device_config_send_events_get_modes
1780 * @see libinput_device_config_send_events_set_mode
1781 * @see libinput_device_config_send_events_get_default_mode
1783 enum libinput_config_send_events_mode
1784 libinput_device_config_send_events_get_default_mode(struct libinput_device *device);
1789 #endif /* LIBINPUT_H */