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.
36 * libinput is a generic input device handling library. It abstracts
37 * commonly-used concepts such as keyboard, pointer and touchpad handling
42 * @page tpbuttons Touchpad button behavior
44 * For touchpad devices without physical buttons, libinput enables an
45 * emulated right button area through either of two methods.
47 * Software button areas
48 * =====================
49 * On most touchpads, the bottom area of the touchpad is split into a a left
50 * and a right-button area. Pressing the touchpad down with a finger in
51 * those areas will generate clicks as shown in the diagram below:
54 +------------------------+
60 +------------------------+
62 +------------------------+
65 * Generally, the touchpad will emulate a right-button click if the finger
66 * was set down in the right button area and did not leave the
67 * right button area before clicking, even if another finger was already
68 * down on the touchpad in another area.
69 * A middle click is generated by clicking the touchpad when one finger is
70 * in the bottom left button area, and one finger is in the botton right
72 * The exact behavior of the touchpad is implementation-dependent.
76 * On Apple touchpads, no button areas are provided. Instead, use a
77 * two-finger click for a right button click, and a three-finger click for a
78 * middle button click.
82 * @ingroup fixed_point
84 * libinput 24.8 fixed point real number.
86 typedef int32_t li_fixed_t;
89 * Log priority for internal logging messages.
91 enum libinput_log_priority {
92 LIBINPUT_LOG_PRIORITY_DEBUG = 10,
93 LIBINPUT_LOG_PRIORITY_INFO = 20,
94 LIBINPUT_LOG_PRIORITY_ERROR = 30,
100 * Capabilities on a device. A device may have one or more capabilities
101 * at a time, and capabilities may appear or disappear during the
102 * lifetime of the device.
104 enum libinput_device_capability {
105 LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
106 LIBINPUT_DEVICE_CAP_POINTER = 1,
107 LIBINPUT_DEVICE_CAP_TOUCH = 2
113 * Logical state of a key. Note that the logical state may not represent
114 * the physical state of the key.
116 enum libinput_keyboard_key_state {
117 LIBINPUT_KEYBOARD_KEY_STATE_RELEASED = 0,
118 LIBINPUT_KEYBOARD_KEY_STATE_PRESSED = 1
124 * Mask reflecting LEDs on a device.
127 LIBINPUT_LED_NUM_LOCK = (1 << 0),
128 LIBINPUT_LED_CAPS_LOCK = (1 << 1),
129 LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
135 * Logical state of a physical button. Note that the logical state may not
136 * represent the physical state of the button.
138 enum libinput_pointer_button_state {
139 LIBINPUT_POINTER_BUTTON_STATE_RELEASED = 0,
140 LIBINPUT_POINTER_BUTTON_STATE_PRESSED = 1
147 * Axes on a device that are not x or y coordinates.
149 enum libinput_pointer_axis {
150 LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = 0,
151 LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = 1
157 * Event type for events returned by libinput_get_event().
159 enum libinput_event_type {
161 * This is not a real event type, and is only used to tell the user that
162 * no new event is available in the queue. See
163 * libinput_next_event_type().
165 LIBINPUT_EVENT_NONE = 0,
168 * Signals that a device has been added to the context. The device will
169 * not be read until the next time the user calls libinput_dispatch()
170 * and data is available.
172 * This allows setting up initial device configuration before any events
175 LIBINPUT_EVENT_DEVICE_ADDED,
178 * Signals that a device has been removed. No more events from the
179 * associated device will be in the queue or be queued after this event.
181 LIBINPUT_EVENT_DEVICE_REMOVED,
183 LIBINPUT_EVENT_KEYBOARD_KEY = 300,
185 LIBINPUT_EVENT_POINTER_MOTION = 400,
186 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
187 LIBINPUT_EVENT_POINTER_BUTTON,
188 LIBINPUT_EVENT_POINTER_AXIS,
190 LIBINPUT_EVENT_TOUCH_DOWN = 500,
191 LIBINPUT_EVENT_TOUCH_UP,
192 LIBINPUT_EVENT_TOUCH_MOTION,
193 LIBINPUT_EVENT_TOUCH_CANCEL,
195 * Signals the end of a set of touchpoints at one device sample
196 * time. This event has no coordinate information attached.
198 LIBINPUT_EVENT_TOUCH_FRAME
202 struct libinput_device;
203 struct libinput_seat;
205 struct libinput_event;
206 struct libinput_event_device_notify;
207 struct libinput_event_keyboard;
208 struct libinput_event_pointer;
211 * @ingroup event_touch
212 * @struct libinput_event_touch
214 * Touch event representing a touch down, move or up, as well as a touch
215 * cancel and touch frame events. Valid event types for this event are @ref
216 * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
217 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
218 * LIBINPUT_EVENT_TOUCH_FRAME.
220 struct libinput_event_touch;
223 * @defgroup fixed_point Fixed point utilities
227 * @ingroup fixed_point
229 * Convert li_fixed_t to a double
231 * @param f fixed point number
232 * @return Converted double
235 li_fixed_to_double (li_fixed_t f)
242 u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f;
244 return u.d - (3LL << 43);
248 * @ingroup fixed_point
250 * Convert li_fixed_t to a int. The fraction part is discarded.
252 * @param f fixed point number
253 * @return Converted int
256 li_fixed_to_int(li_fixed_t f)
262 * @defgroup event Acessing and destruction of events
270 * @param event An event retrieved by libinput_get_event().
273 libinput_event_destroy(struct libinput_event *event);
278 * Get the type of the event.
280 * @param event An event retrieved by libinput_get_event().
282 enum libinput_event_type
283 libinput_event_get_type(struct libinput_event *event);
288 * Get the libinput context from the event.
290 * @param event The libinput event
291 * @return The libinput context for this event.
294 libinput_event_get_context(struct libinput_event *event);
299 * Return the device associated with this event, if applicable. For device
300 * added/removed events this is the device added or removed. For all other
301 * device events, this is the device that generated the event.
303 * This device is not refcounted and its lifetime is that of the event. Use
304 * libinput_device_ref() before using the device outside of this scope.
306 * @return The device associated with this event
309 struct libinput_device *
310 libinput_event_get_device(struct libinput_event *event);
315 * Return the pointer event that is this input event. If the event type does
316 * not match the pointer event types, this function returns NULL.
318 * The inverse of this function is libinput_event_pointer_get_base_event().
320 * @return A pointer event, or NULL for other events
322 struct libinput_event_pointer *
323 libinput_event_get_pointer_event(struct libinput_event *event);
328 * Return the keyboard event that is this input event. If the event type does
329 * not match the keyboard event types, this function returns NULL.
331 * The inverse of this function is libinput_event_keyboard_get_base_event().
333 * @return A keyboard event, or NULL for other events
335 struct libinput_event_keyboard *
336 libinput_event_get_keyboard_event(struct libinput_event *event);
341 * Return the touch event that is this input event. If the event type does
342 * not match the touch event types, this function returns NULL.
344 * The inverse of this function is libinput_event_touch_get_base_event().
346 * @return A touch event, or NULL for other events
348 struct libinput_event_touch *
349 libinput_event_get_touch_event(struct libinput_event *event);
354 * Return the device event that is this input event. If the event type does
355 * not match the device event types, this function returns NULL.
357 * The inverse of this function is
358 * libinput_event_device_notify_get_base_event().
360 * @return A device event, or NULL for other events
362 struct libinput_event_device_notify *
363 libinput_event_get_device_notify_event(struct libinput_event *event);
368 * @return The generic libinput_event of this event
370 struct libinput_event *
371 libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
374 * @defgroup event_keyboard Keyboard events
376 * Key events are generated when a key changes its logical state, usually by
377 * being pressed or released.
381 * @ingroup event_keyboard
383 * @return The event time for this event
386 libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
389 * @ingroup event_keyboard
391 * @return The keycode that triggered this key event
394 libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
397 * @ingroup event_keyboard
399 * @return The state change of the key
401 enum libinput_keyboard_key_state
402 libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
406 * @ingroup event_keyboard
408 * @return The generic libinput_event of this event
410 struct libinput_event *
411 libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
414 * @ingroup event_keyboard
416 * For the key of a LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
417 * of keys pressed on all devices on the associated seat after the event was
420 " @note It is an application bug to call this function for events other than
421 * LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
423 * @return the seat wide pressed key count for the key of this event
426 libinput_event_keyboard_get_seat_key_count(
427 struct libinput_event_keyboard *event);
430 * @defgroup event_pointer Pointer events
432 * Pointer events reflect motion, button and scroll events, as well as
433 * events from other axes.
437 * @ingroup event_pointer
439 * @return The event time for this event
442 libinput_event_pointer_get_time(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 x movement since the last event
457 libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
460 * @ingroup event_pointer
462 * Return the delta between the last event and the current event. For pointer
463 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
466 * @note It is an application bug to call this function for events other than
467 * LIBINPUT_EVENT_POINTER_MOTION.
469 * @return the relative y movement since the last event
472 libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
475 * @ingroup event_pointer
477 * Return the current absolute x coordinate of the pointer event.
479 * The coordinate is in a device specific coordinate space; to get the
480 * corresponding output screen coordinate, use
481 * libinput_event_pointer_get_x_transformed().
483 * For pointer events that are not of type
484 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
486 * @note It is an application bug to call this function for events other than
487 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
489 * @return the current absolute x coordinate
492 libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
495 * @ingroup event_pointer
497 * Return the current absolute y coordinate of the pointer event.
499 * The coordinate is in a device specific coordinate space; to get the
500 * corresponding output screen coordinate, use
501 * libinput_event_pointer_get_y_transformed().
503 * For pointer events that are not of type
504 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
506 * @note It is an application bug to call this function for events other than
507 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
509 * @return the current absolute y coordinate
512 libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
515 * @ingroup event_pointer
517 * Return the current absolute x coordinate of the pointer event, transformed to
518 * screen coordinates.
520 * For pointer events that are not of type
521 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
524 * @note It is an application bug to call this function for events other than
525 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
527 * @param event The libinput pointer event
528 * @param width The current output screen width
529 * @return the current absolute x coordinate transformed to a screen coordinate
532 libinput_event_pointer_get_absolute_x_transformed(
533 struct libinput_event_pointer *event,
537 * @ingroup event_pointer
539 * Return the current absolute y coordinate of the pointer event, transformed to
540 * screen coordinates.
542 * For pointer events that are not of type
543 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
546 * @note It is an application bug to call this function for events other than
547 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
549 * @param event The libinput pointer event
550 * @param height The current output screen height
551 * @return the current absolute y coordinate transformed to a screen coordinate
554 libinput_event_pointer_get_absolute_y_transformed(
555 struct libinput_event_pointer *event,
559 * @ingroup event_pointer
561 * Return the button that triggered this event.
562 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
563 * this function returns 0.
565 * @note It is an application bug to call this function for events other than
566 * LIBINPUT_EVENT_POINTER_BUTTON.
568 * @return the button triggering this event
571 libinput_event_pointer_get_button(struct libinput_event_pointer *event);
574 * @ingroup event_pointer
576 * Return the button state that triggered this event.
577 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
578 * this function returns 0.
580 * @note It is an application bug to call this function for events other than
581 * LIBINPUT_EVENT_POINTER_BUTTON.
583 * @return the button state triggering this event
585 enum libinput_pointer_button_state
586 libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
589 * @ingroup event_pointer
591 * For the button of a LIBINPUT_EVENT_POINTER_BUTTON event, return the total
592 * number of buttons pressed on all devices on the associated seat after the
593 * the event was triggered.
595 " @note It is an application bug to call this function for events other than
596 * LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function returns 0.
598 * @return the seat wide pressed button count for the key of this event
601 libinput_event_pointer_get_seat_button_count(
602 struct libinput_event_pointer *event);
605 * @ingroup event_pointer
607 * Return the axis that triggered this event.
608 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
609 * this function returns 0.
611 * @note It is an application bug to call this function for events other than
612 * LIBINPUT_EVENT_POINTER_AXIS.
614 * @return the axis triggering this event
616 enum libinput_pointer_axis
617 libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
620 * @ingroup event_pointer
622 * Return the axis value of the given axis. The interpretation of the value
623 * is dependent on the axis. For the two scrolling axes
624 * LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL and
625 * LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL, the value of the event is in
626 * relative scroll units, with the positive direction being down or right,
627 * respectively. The dimension of a scroll unit is equal to one unit of
628 * motion in the respective axis, where applicable (e.g. touchpad two-finger
631 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
632 * this function returns 0.
634 * @note It is an application bug to call this function for events other than
635 * LIBINPUT_EVENT_POINTER_AXIS.
637 * @return the axis value of this event
640 libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
643 * @ingroup event_pointer
645 * @return The generic libinput_event of this event
647 struct libinput_event *
648 libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
652 * @defgroup event_touch Touch events
654 * Events from absolute touch devices.
658 * @ingroup event_touch
660 * @return The event time for this event
663 libinput_event_touch_get_time(struct libinput_event_touch *event);
666 * @ingroup event_touch
668 * Get the slot of this touch event. See the kernel's multitouch
669 * protocol B documentation for more information.
671 * If the touch event has no assigned slot, for example if it is from a
672 * single touch device, this function returns -1.
674 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
675 * LIBINPUT_EVENT_TOUCH_FRAME.
677 * @return The slot of this touch event
680 libinput_event_touch_get_slot(struct libinput_event_touch *event);
683 * @ingroup event_touch
685 * Get the seat slot of the touch event. A seat slot is a non-negative seat
686 * wide unique identifier of an active touch point.
688 * Events from single touch devices will be represented as one individual
689 * touch point per device.
691 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
692 * LIBINPUT_EVENT_TOUCH_FRAME.
694 * @return The seat slot of the touch event
697 libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
700 * @ingroup event_touch
702 * Return the current absolute x coordinate of the touch event.
704 * The coordinate is in a device specific coordinate space; to get the
705 * corresponding output screen coordinate, use
706 * libinput_event_touch_get_x_transformed().
708 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
709 * LIBINPUT_EVENT_TOUCH_MOTION.
711 * @param event The libinput touch event
712 * @return the current absolute x coordinate
715 libinput_event_touch_get_x(struct libinput_event_touch *event);
718 * @ingroup event_touch
720 * Return the current absolute y coordinate of the touch event.
722 * The coordinate is in a device specific coordinate space; to get the
723 * corresponding output screen coordinate, use
724 * libinput_event_touch_get_y_transformed().
726 * For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
728 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
729 * LIBINPUT_EVENT_TOUCH_MOTION.
731 * @param event The libinput touch event
732 * @return the current absolute y coordinate
735 libinput_event_touch_get_y(struct libinput_event_touch *event);
738 * @ingroup event_touch
740 * Return the current absolute x coordinate of the touch event, transformed to
741 * screen coordinates.
743 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
744 * LIBINPUT_EVENT_TOUCH_MOTION.
746 * @param event The libinput touch event
747 * @param width The current output screen width
748 * @return the current absolute x coordinate transformed to a screen coordinate
751 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
755 * @ingroup event_touch
757 * Return the current absolute y coordinate of the touch event, transformed to
758 * screen coordinates.
760 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
761 * LIBINPUT_EVENT_TOUCH_MOTION.
763 * @param event The libinput touch event
764 * @param height The current output screen height
765 * @return the current absolute y coordinate transformed to a screen coordinate
768 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
772 * @ingroup event_touch
774 * @return The generic libinput_event of this event
776 struct libinput_event *
777 libinput_event_touch_get_base_event(struct libinput_event_touch *event);
780 * @defgroup base Initialization and manipulation of libinput contexts
783 struct libinput_interface {
785 * Open the device at the given path with the flags provided and
788 * @param path The device path to open
789 * @param flags Flags as defined by open(2)
790 * @param user_data The user_data provided in
791 * libinput_udev_create_for_seat()
793 * @return the file descriptor, or a negative errno on failure.
795 int (*open_restricted)(const char *path, int flags, void *user_data);
797 * Close the file descriptor.
799 * @param fd The file descriptor to close
800 * @param user_data The user_data provided in
801 * libinput_udev_create_for_seat()
803 void (*close_restricted)(int fd, void *user_data);
809 * Create a new libinput context from udev, for input devices matching
810 * the given seat ID. New devices or devices removed will appear as events
811 * during libinput_dispatch.
813 * libinput_udev_create_for_seat() succeeds even if no input device is
814 * available in this seat, or if devices are available but fail to open in
815 * @ref libinput_interface::open_restricted. Devices that do not have the
816 * minimum capabilities to be recognized as pointer, keyboard or touch
817 * device are ignored. Such devices and those that failed to open
818 * ignored until the next call to libinput_resume().
820 * @param interface The callback interface
821 * @param user_data Caller-specific data passed to the various callback
823 * @param udev An already initialized udev context
824 * @param seat_id A seat identifier. This string must not be NULL.
826 * @return An initialized libinput context, ready to handle events or NULL on
830 libinput_udev_create_for_seat(const struct libinput_interface *interface,
833 const char *seat_id);
838 * Create a new libinput context that requires the caller to manually add or
839 * remove devices with libinput_path_add_device() and
840 * libinput_path_remove_device().
842 * The context is fully initialized but will not generate events until at
843 * least one device has been added.
845 * @param interface The callback interface
846 * @param user_data Caller-specific data passed to the various callback
849 * @return An initialized, empty libinput context.
852 libinput_path_create_context(const struct libinput_interface *interface,
858 * Add a device to a libinput context initialized with
859 * libinput_path_create_context(). If successful, the device will be
860 * added to the internal list and re-opened on libinput_resume(). The device
861 * can be removed with libinput_path_remove_device().
863 * If the device was successfully initialized, it is returned in the device
864 * argument. The lifetime of the returned device pointer is limited until
865 * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent
868 * @param libinput A previously initialized libinput context
869 * @param path Path to an input device
870 * @return The newly initiated device on success, or NULL on failure.
872 * @note It is an application bug to call this function on a libinput
873 * context initialized with libinput_udev_create_for_seat().
875 struct libinput_device *
876 libinput_path_add_device(struct libinput *libinput,
882 * Remove a device from a libinput context initialized with
883 * libinput_path_create_context() or added to such a context with
884 * libinput_path_add_device().
886 * Events already processed from this input device are kept in the queue,
887 * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
890 * If no matching device exists, this function does nothing.
892 * @param device A libinput device
894 * @note It is an application bug to call this function on a libinput
895 * context initialized with libinput_udev_create_for_seat().
898 libinput_path_remove_device(struct libinput_device *device);
903 * libinput keeps a single file descriptor for all events. Call into
904 * libinput_dispatch() if any events become available on this fd.
906 * @return the file descriptor used to notify of pending events.
909 libinput_get_fd(struct libinput *libinput);
914 * Main event dispatchment function. Reads events of the file descriptors
915 * and processes them internally. Use libinput_get_event() to retrieve the
918 * Dispatching does not necessarily queue libinput events.
920 * @param libinput A previously initialized libinput context
922 * @return 0 on success, or a negative errno on failure
925 libinput_dispatch(struct libinput *libinput);
930 * Retrieve the next event from libinput's internal event queue.
932 * After handling the retrieved event, the caller must destroy it using
933 * libinput_event_destroy().
935 * @param libinput A previously initialized libinput context
936 * @return The next available event, or NULL if no event is available.
938 struct libinput_event *
939 libinput_get_event(struct libinput *libinput);
944 * Return the type of the next event in the internal queue. This function
945 * does not pop the event off the queue and the next call to
946 * libinput_get_event() returns that event.
948 * @param libinput A previously initialized libinput context
949 * @return The event type of the next available event or LIBINPUT_EVENT_NONE
950 * if no event is availble.
952 enum libinput_event_type
953 libinput_next_event_type(struct libinput *libinput);
958 * @param libinput A previously initialized libinput context
959 * @return the caller-specific data previously assigned in
960 * libinput_create_udev().
963 libinput_get_user_data(struct libinput *libinput);
968 * Resume a suspended libinput context. This re-enables device
969 * monitoring and adds existing devices.
971 * @param libinput A previously initialized libinput context
972 * @see libinput_suspend
974 * @return 0 on success or -1 on failure
977 libinput_resume(struct libinput *libinput);
982 * Suspend monitoring for new devices and close existing devices.
983 * This all but terminates libinput but does keep the context
984 * valid to be resumed with libinput_resume().
986 * @param libinput A previously initialized libinput context
989 libinput_suspend(struct libinput *libinput);
994 * Destroy the libinput context. After this, object references associated with
995 * the destroyed context are invalid and may not be interacted with.
997 * @param libinput A previously initialized libinput context
1000 libinput_destroy(struct libinput *libinput);
1005 * Set the global log priority. Messages with priorities equal to or
1006 * higher than the argument will be printed to the current log handler.
1008 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1010 * @param priority The minimum priority of log messages to print.
1012 * @see libinput_log_set_handler
1015 libinput_log_set_priority(enum libinput_log_priority priority);
1020 * Get the global log priority. Messages with priorities equal to or
1021 * higher than the argument will be printed to the current log handler.
1023 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1025 * @return The minimum priority of log messages to print.
1027 * @see libinput_log_set_handler
1029 enum libinput_log_priority
1030 libinput_log_get_priority(void);
1035 * Log handler type for custom logging.
1037 * @param priority The priority of the current message
1038 * @param user_data Caller-specific data pointer as previously passed into
1039 * libinput_log_set_handler()
1040 * @param format Message format in printf-style
1041 * @param args Message arguments
1043 * @see libinput_set_log_priority
1044 * @see libinput_log_set_handler
1046 typedef void (*libinput_log_handler)(enum libinput_log_priority priority,
1048 const char *format, va_list args);
1053 * Set the global log handler. Messages with priorities equal to or higher
1054 * than the current log priority will be passed to the given
1057 * The default log handler prints to stderr.
1059 * @param log_handler The log handler for library messages.
1060 * @param user_data Caller-specific data pointer, passed into the log
1063 * @see libinput_log_set_handler
1066 libinput_log_set_handler(libinput_log_handler log_handler,
1070 * @defgroup seat Initialization and manipulation of seats
1072 * A seat has two identifiers, the physical name and the logical name. The
1073 * physical name is summarized as the list of devices a process on the same
1074 * physical seat has access to.
1076 * The logical seat name is the seat name for a logical group of devices. A
1077 * compositor may use that to create additonal seats as independent device
1078 * sets. Alternatively, a compositor may limit itself to a single logical
1079 * seat, leaving a second compositor to manage devices on the other logical
1083 * +---+--------+------------+------------------------+------------+
1084 * | | event0 | | | log seat A |
1085 * | K +--------+ | +------------+
1086 * | e | event1 | phys seat0 | libinput context 1 | |
1087 * | r +--------+ | | log seat B |
1088 * | n | event2 | | | |
1089 * | e +--------+------------+------------------------+------------+
1090 * | l | event3 | phys seat1 | libinput context 2 | log seat C |
1091 * +---+--------+------------+------------------------+------------+
1098 * Increase the refcount of the seat. A seat will be freed whenever the
1099 * refcount reaches 0. This may happen during dispatch if the
1100 * seat was removed from the system. A caller must ensure to reference
1101 * the seat correctly to avoid dangling pointers.
1103 * @param seat A previously obtained seat
1106 libinput_seat_ref(struct libinput_seat *seat);
1111 * Decrease the refcount of the seat. A seat will be freed whenever the
1112 * refcount reaches 0. This may happen during dispatch if the
1113 * seat was removed from the system. A caller must ensure to reference
1114 * the seat correctly to avoid dangling pointers.
1116 * @param seat A previously obtained seat
1119 libinput_seat_unref(struct libinput_seat *seat);
1124 * Set caller-specific data associated with this seat. libinput does
1125 * not manage, look at, or modify this data. The caller must ensure the
1128 * @param seat A previously obtained seat
1129 * @param user_data Caller-specific data pointer
1130 * @see libinput_seat_get_user_data
1133 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
1138 * Get the caller-specific data associated with this seat, if any.
1140 * @param seat A previously obtained seat
1141 * @return Caller-specific data pointer or NULL if none was set
1142 * @see libinput_seat_set_user_data
1145 libinput_seat_get_user_data(struct libinput_seat *seat);
1150 * Return the physical name of the seat. For libinput contexts created from
1151 * udev, this is always the same value as passed into
1152 * libinput_udev_create_for_seat() and all seats from that context will have
1153 * the same physical name.
1155 * The physical name of the seat is one that is usually set by the system or
1156 * lower levels of the stack. In most cases, this is the base filter for
1157 * devices - devices assigned to seats outside the current seat will not
1158 * be available to the caller.
1160 * @param seat A previously obtained seat
1161 * @return the physical name of this seat
1164 libinput_seat_get_physical_name(struct libinput_seat *seat);
1169 * Return the logical name of the seat. This is an identifier to group sets
1170 * of devices within the compositor.
1172 * @param seat A previously obtained seat
1173 * @return the logical name of this seat
1176 libinput_seat_get_logical_name(struct libinput_seat *seat);
1179 * @defgroup device Initialization and manipulation of input devices
1185 * Increase the refcount of the input device. An input device will be freed
1186 * whenever the refcount reaches 0. This may happen during dispatch if the
1187 * device was removed from the system. A caller must ensure to reference
1188 * the device correctly to avoid dangling pointers.
1190 * @param device A previously obtained device
1193 libinput_device_ref(struct libinput_device *device);
1198 * Decrease the refcount of the input device. An input device will be freed
1199 * whenever the refcount reaches 0. This may happen during dispatch if the
1200 * device was removed from the system. A caller must ensure to reference
1201 * the device correctly to avoid dangling pointers.
1203 * @param device A previously obtained device
1206 libinput_device_unref(struct libinput_device *device);
1211 * Set caller-specific data associated with this input device. libinput does
1212 * not manage, look at, or modify this data. The caller must ensure the
1215 * @param device A previously obtained device
1216 * @param user_data Caller-specific data pointer
1217 * @see libinput_device_get_user_data
1220 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1225 * Get the caller-specific data associated with this input device, if any.
1227 * @param device A previously obtained device
1228 * @return Caller-specific data pointer or NULL if none was set
1229 * @see libinput_device_set_user_data
1232 libinput_device_get_user_data(struct libinput_device *device);
1237 * Get the system name of the device.
1239 * @param device A previously obtained device
1240 * @return System name of the device
1243 libinput_device_get_sysname(struct libinput_device *device);
1248 * A device may be mapped to a single output, or all available outputs. If a
1249 * device is mapped to a single output only, a relative device may not move
1250 * beyond the boundaries of this output. An absolute device has its input
1251 * coordinates mapped to the extents of this output.
1253 * @return the name of the output this device is mapped to, or NULL if no
1257 libinput_device_get_output_name(struct libinput_device *device);
1262 * Get the seat associated with this input device.
1264 * A seat can be uniquely identified by the physical and logical seat name.
1265 * There will ever be only one seat instance with a given physical and logical
1266 * seat name pair at any given time, but if no external reference is kept, it
1267 * may be destroyed if no device belonging to it is left.
1269 * @param device A previously obtained device
1270 * @return The seat this input device belongs to
1272 struct libinput_seat *
1273 libinput_device_get_seat(struct libinput_device *device);
1278 * Update the LEDs on the device, if any. If the device does not have
1279 * LEDs, or does not have one or more of the LEDs given in the mask, this
1280 * function does nothing.
1282 * @param device A previously obtained device
1283 * @param leds A mask of the LEDs to set, or unset.
1286 libinput_device_led_update(struct libinput_device *device,
1287 enum libinput_led leds);
1292 * Set the bitmask in keys to the bitmask of the keys present on the device
1293 * (see linux/input.h), up to size characters.
1295 * @param device A current input device
1296 * @param keys An array filled with the bitmask for the keys
1297 * @param size Size of the keys array
1299 * @return The number of valid bytes in keys, or a negative errno on failure
1302 libinput_device_get_keys(struct libinput_device *device,
1303 char *keys, size_t size);
1308 * Apply the 3x3 transformation matrix to absolute device coordinates. This
1309 * matrix has no effect on relative events.
1311 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1319 libinput_device_calibrate(struct libinput_device *device,
1320 float calibration[6]);
1325 * Check if the given device has the specified capability
1327 * @return 1 if the given device has the capability or 0 if not
1330 libinput_device_has_capability(struct libinput_device *device,
1331 enum libinput_device_capability capability);
1337 #endif /* LIBINPUT_H */