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)))
39 * libinput is a generic input device handling library. It abstracts
40 * commonly-used concepts such as keyboard, pointer and touchpad handling
45 * @page tpbuttons Touchpad button behavior
47 * For touchpad devices without physical buttons, libinput enables an
48 * emulated right button area through either of two methods.
50 * Software button areas
51 * =====================
52 * On most touchpads, the bottom area of the touchpad is split into a a left
53 * and a right-button area. Pressing the touchpad down with a finger in
54 * those areas will generate clicks as shown in the diagram below:
57 +------------------------+
63 +------------------------+
65 +------------------------+
68 * Generally, the touchpad will emulate a right-button click if the finger
69 * was set down in the right button area and did not leave the
70 * right button area before clicking, even if another finger was already
71 * down on the touchpad in another area.
72 * A middle click is generated by clicking the touchpad when one finger is
73 * in the bottom left button area, and one finger is in the botton right
75 * The exact behavior of the touchpad is implementation-dependent.
77 * Top software button area
78 * ========================
79 * On selected touchpads, the top area of the touchpad is a separate set of
80 * software buttons split into a left, middle and right button area.
81 * Pressing the touchpad down with a finger in those areas will generate
82 * clicks as shown in the diagram below:
85 +------------------------+
86 | LEFT | MIDDLE | RIGHT |
87 +------------------------+
91 +------------------------+
93 +------------------------+
95 * This behavior is enabled on the Lenovo *40 series (T440, T540, T240...)
96 * and the Lenovo Helix, Yoga S1 and Carbon X1 2nd.
100 * On Apple touchpads, no button areas are provided. Instead, use a
101 * two-finger click for a right button click, and a three-finger click for a
102 * middle button click.
106 * Log priority for internal logging messages.
108 enum libinput_log_priority {
109 LIBINPUT_LOG_PRIORITY_DEBUG = 10,
110 LIBINPUT_LOG_PRIORITY_INFO = 20,
111 LIBINPUT_LOG_PRIORITY_ERROR = 30,
117 * Capabilities on a device. A device may have one or more capabilities
118 * at a time, and capabilities may appear or disappear during the
119 * lifetime of the device.
121 enum libinput_device_capability {
122 LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
123 LIBINPUT_DEVICE_CAP_POINTER = 1,
124 LIBINPUT_DEVICE_CAP_TOUCH = 2
130 * Logical state of a key. Note that the logical state may not represent
131 * the physical state of the key.
133 enum libinput_keyboard_key_state {
134 LIBINPUT_KEYBOARD_KEY_STATE_RELEASED = 0,
135 LIBINPUT_KEYBOARD_KEY_STATE_PRESSED = 1
141 * Mask reflecting LEDs on a device.
144 LIBINPUT_LED_NUM_LOCK = (1 << 0),
145 LIBINPUT_LED_CAPS_LOCK = (1 << 1),
146 LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
152 * Logical state of a physical button. Note that the logical state may not
153 * represent the physical state of the button.
155 enum libinput_button_state {
156 LIBINPUT_BUTTON_STATE_RELEASED = 0,
157 LIBINPUT_BUTTON_STATE_PRESSED = 1
164 * Axes on a device that are not x or y coordinates.
166 enum libinput_pointer_axis {
167 LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = 0,
168 LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = 1
174 * Event type for events returned by libinput_get_event().
176 enum libinput_event_type {
178 * This is not a real event type, and is only used to tell the user that
179 * no new event is available in the queue. See
180 * libinput_next_event_type().
182 LIBINPUT_EVENT_NONE = 0,
185 * Signals that a device has been added to the context. The device will
186 * not be read until the next time the user calls libinput_dispatch()
187 * and data is available.
189 * This allows setting up initial device configuration before any events
192 LIBINPUT_EVENT_DEVICE_ADDED,
195 * Signals that a device has been removed. No more events from the
196 * associated device will be in the queue or be queued after this event.
198 LIBINPUT_EVENT_DEVICE_REMOVED,
200 LIBINPUT_EVENT_KEYBOARD_KEY = 300,
202 LIBINPUT_EVENT_POINTER_MOTION = 400,
203 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
204 LIBINPUT_EVENT_POINTER_BUTTON,
205 LIBINPUT_EVENT_POINTER_AXIS,
207 LIBINPUT_EVENT_TOUCH_DOWN = 500,
208 LIBINPUT_EVENT_TOUCH_UP,
209 LIBINPUT_EVENT_TOUCH_MOTION,
210 LIBINPUT_EVENT_TOUCH_CANCEL,
212 * Signals the end of a set of touchpoints at one device sample
213 * time. This event has no coordinate information attached.
215 LIBINPUT_EVENT_TOUCH_FRAME
219 struct libinput_device;
220 struct libinput_seat;
222 struct libinput_event;
223 struct libinput_event_device_notify;
224 struct libinput_event_keyboard;
225 struct libinput_event_pointer;
228 * @ingroup event_touch
229 * @struct libinput_event_touch
231 * Touch event representing a touch down, move or up, as well as a touch
232 * cancel and touch frame events. Valid event types for this event are @ref
233 * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
234 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
235 * LIBINPUT_EVENT_TOUCH_FRAME.
237 struct libinput_event_touch;
240 * @defgroup event Accessing and destruction of events
248 * @param event An event retrieved by libinput_get_event().
251 libinput_event_destroy(struct libinput_event *event);
256 * Get the type of the event.
258 * @param event An event retrieved by libinput_get_event().
260 enum libinput_event_type
261 libinput_event_get_type(struct libinput_event *event);
266 * Get the libinput context from the event.
268 * @param event The libinput event
269 * @return The libinput context for this event.
272 libinput_event_get_context(struct libinput_event *event);
277 * Return the device associated with this event, if applicable. For device
278 * added/removed events this is the device added or removed. For all other
279 * device events, this is the device that generated the event.
281 * This device is not refcounted and its lifetime is that of the event. Use
282 * libinput_device_ref() before using the device outside of this scope.
284 * @return The device associated with this event
287 struct libinput_device *
288 libinput_event_get_device(struct libinput_event *event);
293 * Return the pointer event that is this input event. If the event type does
294 * not match the pointer event types, this function returns NULL.
296 * The inverse of this function is libinput_event_pointer_get_base_event().
298 * @return A pointer event, or NULL for other events
300 struct libinput_event_pointer *
301 libinput_event_get_pointer_event(struct libinput_event *event);
306 * Return the keyboard event that is this input event. If the event type does
307 * not match the keyboard event types, this function returns NULL.
309 * The inverse of this function is libinput_event_keyboard_get_base_event().
311 * @return A keyboard event, or NULL for other events
313 struct libinput_event_keyboard *
314 libinput_event_get_keyboard_event(struct libinput_event *event);
319 * Return the touch event that is this input event. If the event type does
320 * not match the touch event types, this function returns NULL.
322 * The inverse of this function is libinput_event_touch_get_base_event().
324 * @return A touch event, or NULL for other events
326 struct libinput_event_touch *
327 libinput_event_get_touch_event(struct libinput_event *event);
332 * Return the device event that is this input event. If the event type does
333 * not match the device event types, this function returns NULL.
335 * The inverse of this function is
336 * libinput_event_device_notify_get_base_event().
338 * @return A device event, or NULL for other events
340 struct libinput_event_device_notify *
341 libinput_event_get_device_notify_event(struct libinput_event *event);
346 * @return The generic libinput_event of this event
348 struct libinput_event *
349 libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
352 * @defgroup event_keyboard Keyboard events
354 * Key events are generated when a key changes its logical state, usually by
355 * being pressed or released.
359 * @ingroup event_keyboard
361 * @return The event time for this event
364 libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
367 * @ingroup event_keyboard
369 * @return The keycode that triggered this key event
372 libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
375 * @ingroup event_keyboard
377 * @return The state change of the key
379 enum libinput_keyboard_key_state
380 libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
384 * @ingroup event_keyboard
386 * @return The generic libinput_event of this event
388 struct libinput_event *
389 libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
392 * @ingroup event_keyboard
394 * For the key of a LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
395 * of keys pressed on all devices on the associated seat after the event was
398 " @note It is an application bug to call this function for events other than
399 * LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
401 * @return the seat wide pressed key count for the key of this event
404 libinput_event_keyboard_get_seat_key_count(
405 struct libinput_event_keyboard *event);
408 * @defgroup event_pointer Pointer events
410 * Pointer events reflect motion, button and scroll events, as well as
411 * events from other axes.
415 * @ingroup event_pointer
417 * @return The event time for this event
420 libinput_event_pointer_get_time(struct libinput_event_pointer *event);
423 * @ingroup event_pointer
425 * Return the delta between the last event and the current event. For pointer
426 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
429 * @note It is an application bug to call this function for events other than
430 * LIBINPUT_EVENT_POINTER_MOTION.
432 * @return the relative x movement since the last event
435 libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
438 * @ingroup event_pointer
440 * Return the delta between the last event and the current event. For pointer
441 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
444 * @note It is an application bug to call this function for events other than
445 * LIBINPUT_EVENT_POINTER_MOTION.
447 * @return the relative y movement since the last event
450 libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
453 * @ingroup event_pointer
455 * Return the current absolute x coordinate of the pointer event, in mm from
456 * the top left corner of the device. To get the corresponding output screen
457 * coordinate, use libinput_event_pointer_get_x_transformed().
459 * For pointer events that are not of type
460 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
462 * @note It is an application bug to call this function for events other than
463 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
465 * @return the current absolute x coordinate
468 libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
471 * @ingroup event_pointer
473 * Return the current absolute y coordinate of the pointer event, in mm from
474 * the top left corner of the device. To get the corresponding output screen
475 * coordinate, use libinput_event_pointer_get_x_transformed().
477 * For pointer events that are not of type
478 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
480 * @note It is an application bug to call this function for events other than
481 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
483 * @return the current absolute y coordinate
486 libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
489 * @ingroup event_pointer
491 * Return the current absolute x coordinate of the pointer event, transformed to
492 * screen coordinates.
494 * For pointer events that are not of type
495 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
498 * @note It is an application bug to call this function for events other than
499 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
501 * @param event The libinput pointer event
502 * @param width The current output screen width
503 * @return the current absolute x coordinate transformed to a screen coordinate
506 libinput_event_pointer_get_absolute_x_transformed(
507 struct libinput_event_pointer *event,
511 * @ingroup event_pointer
513 * Return the current absolute y coordinate of the pointer event, transformed to
514 * screen coordinates.
516 * For pointer events that are not of type
517 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
520 * @note It is an application bug to call this function for events other than
521 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
523 * @param event The libinput pointer event
524 * @param height The current output screen height
525 * @return the current absolute y coordinate transformed to a screen coordinate
528 libinput_event_pointer_get_absolute_y_transformed(
529 struct libinput_event_pointer *event,
533 * @ingroup event_pointer
535 * Return the button that triggered this event.
536 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
537 * this function returns 0.
539 * @note It is an application bug to call this function for events other than
540 * LIBINPUT_EVENT_POINTER_BUTTON.
542 * @return the button triggering this event
545 libinput_event_pointer_get_button(struct libinput_event_pointer *event);
548 * @ingroup event_pointer
550 * Return the button state that triggered this event.
551 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
552 * this function returns 0.
554 * @note It is an application bug to call this function for events other than
555 * LIBINPUT_EVENT_POINTER_BUTTON.
557 * @return the button state triggering this event
559 enum libinput_button_state
560 libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
563 * @ingroup event_pointer
565 * For the button of a LIBINPUT_EVENT_POINTER_BUTTON event, return the total
566 * number of buttons pressed on all devices on the associated seat after the
567 * the event was triggered.
569 " @note It is an application bug to call this function for events other than
570 * LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function returns 0.
572 * @return the seat wide pressed button count for the key of this event
575 libinput_event_pointer_get_seat_button_count(
576 struct libinput_event_pointer *event);
579 * @ingroup event_pointer
581 * Return the axis that triggered this event.
582 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
583 * this function returns 0.
585 * @note It is an application bug to call this function for events other than
586 * LIBINPUT_EVENT_POINTER_AXIS.
588 * @return the axis triggering this event
590 enum libinput_pointer_axis
591 libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
594 * @ingroup event_pointer
596 * Return the axis value of the given axis. The interpretation of the value
597 * is dependent on the axis. For the two scrolling axes
598 * LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL and
599 * LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL, the value of the event is in
600 * relative scroll units, with the positive direction being down or right,
601 * respectively. The dimension of a scroll unit is equal to one unit of
602 * motion in the respective axis, where applicable (e.g. touchpad two-finger
605 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
606 * this function returns 0.
608 * @note It is an application bug to call this function for events other than
609 * LIBINPUT_EVENT_POINTER_AXIS.
611 * @return the axis value of this event
614 libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
617 * @ingroup event_pointer
619 * @return The generic libinput_event of this event
621 struct libinput_event *
622 libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
626 * @defgroup event_touch Touch events
628 * Events from absolute touch devices.
632 * @ingroup event_touch
634 * @return The event time for this event
637 libinput_event_touch_get_time(struct libinput_event_touch *event);
640 * @ingroup event_touch
642 * Get the slot of this touch event. See the kernel's multitouch
643 * protocol B documentation for more information.
645 * If the touch event has no assigned slot, for example if it is from a
646 * single touch device, this function returns -1.
648 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
649 * LIBINPUT_EVENT_TOUCH_FRAME.
651 * @return The slot of this touch event
654 libinput_event_touch_get_slot(struct libinput_event_touch *event);
657 * @ingroup event_touch
659 * Get the seat slot of the touch event. A seat slot is a non-negative seat
660 * wide unique identifier of an active touch point.
662 * Events from single touch devices will be represented as one individual
663 * touch point per device.
665 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
666 * LIBINPUT_EVENT_TOUCH_FRAME.
668 * @return The seat slot of the touch event
671 libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
674 * @ingroup event_touch
676 * Return the current absolute x coordinate of the touch event, in mm from
677 * the top left corner of the device. To get the corresponding output screen
678 * coordinate, use libinput_event_touch_get_x_transformed().
680 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
681 * LIBINPUT_EVENT_TOUCH_MOTION.
683 * @param event The libinput touch event
684 * @return the current absolute x coordinate
687 libinput_event_touch_get_x(struct libinput_event_touch *event);
690 * @ingroup event_touch
692 * Return the current absolute y coordinate of the touch event, in mm from
693 * the top left corner of the device. To get the corresponding output screen
694 * coordinate, use libinput_event_touch_get_y_transformed().
696 * For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
698 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
699 * LIBINPUT_EVENT_TOUCH_MOTION.
701 * @param event The libinput touch event
702 * @return the current absolute y coordinate
705 libinput_event_touch_get_y(struct libinput_event_touch *event);
708 * @ingroup event_touch
710 * Return the current absolute x coordinate of the touch event, transformed to
711 * screen coordinates.
713 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
714 * LIBINPUT_EVENT_TOUCH_MOTION.
716 * @param event The libinput touch event
717 * @param width The current output screen width
718 * @return the current absolute x coordinate transformed to a screen coordinate
721 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
725 * @ingroup event_touch
727 * Return the current absolute y coordinate of the touch event, transformed to
728 * screen coordinates.
730 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
731 * LIBINPUT_EVENT_TOUCH_MOTION.
733 * @param event The libinput touch event
734 * @param height The current output screen height
735 * @return the current absolute y coordinate transformed to a screen coordinate
738 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
742 * @ingroup event_touch
744 * @return The generic libinput_event of this event
746 struct libinput_event *
747 libinput_event_touch_get_base_event(struct libinput_event_touch *event);
750 * @defgroup base Initialization and manipulation of libinput contexts
753 struct libinput_interface {
755 * Open the device at the given path with the flags provided and
758 * @param path The device path to open
759 * @param flags Flags as defined by open(2)
760 * @param user_data The user_data provided in
761 * libinput_udev_create_for_seat()
763 * @return the file descriptor, or a negative errno on failure.
765 int (*open_restricted)(const char *path, int flags, void *user_data);
767 * Close the file descriptor.
769 * @param fd The file descriptor to close
770 * @param user_data The user_data provided in
771 * libinput_udev_create_for_seat()
773 void (*close_restricted)(int fd, void *user_data);
779 * Create a new libinput context from udev, for input devices matching
780 * the given seat ID. New devices or devices removed will appear as events
781 * during libinput_dispatch.
783 * libinput_udev_create_for_seat() succeeds even if no input device is
784 * available in this seat, or if devices are available but fail to open in
785 * @ref libinput_interface::open_restricted. Devices that do not have the
786 * minimum capabilities to be recognized as pointer, keyboard or touch
787 * device are ignored. Such devices and those that failed to open
788 * ignored until the next call to libinput_resume().
790 * @param interface The callback interface
791 * @param user_data Caller-specific data passed to the various callback
793 * @param udev An already initialized udev context
794 * @param seat_id A seat identifier. This string must not be NULL.
796 * @return An initialized libinput context, ready to handle events or NULL on
800 libinput_udev_create_for_seat(const struct libinput_interface *interface,
803 const char *seat_id);
808 * Create a new libinput context that requires the caller to manually add or
809 * remove devices with libinput_path_add_device() and
810 * libinput_path_remove_device().
812 * The context is fully initialized but will not generate events until at
813 * least one device has been added.
815 * @param interface The callback interface
816 * @param user_data Caller-specific data passed to the various callback
819 * @return An initialized, empty libinput context.
822 libinput_path_create_context(const struct libinput_interface *interface,
828 * Add a device to a libinput context initialized with
829 * libinput_path_create_context(). If successful, the device will be
830 * added to the internal list and re-opened on libinput_resume(). The device
831 * can be removed with libinput_path_remove_device().
833 * If the device was successfully initialized, it is returned in the device
834 * argument. The lifetime of the returned device pointer is limited until
835 * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent
838 * @param libinput A previously initialized libinput context
839 * @param path Path to an input device
840 * @return The newly initiated device on success, or NULL on failure.
842 * @note It is an application bug to call this function on a libinput
843 * context initialized with libinput_udev_create_for_seat().
845 struct libinput_device *
846 libinput_path_add_device(struct libinput *libinput,
852 * Remove a device from a libinput context initialized with
853 * libinput_path_create_context() or added to such a context with
854 * libinput_path_add_device().
856 * Events already processed from this input device are kept in the queue,
857 * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
860 * If no matching device exists, this function does nothing.
862 * @param device A libinput device
864 * @note It is an application bug to call this function on a libinput
865 * context initialized with libinput_udev_create_for_seat().
868 libinput_path_remove_device(struct libinput_device *device);
873 * libinput keeps a single file descriptor for all events. Call into
874 * libinput_dispatch() if any events become available on this fd.
876 * @return the file descriptor used to notify of pending events.
879 libinput_get_fd(struct libinput *libinput);
884 * Main event dispatchment function. Reads events of the file descriptors
885 * and processes them internally. Use libinput_get_event() to retrieve the
888 * Dispatching does not necessarily queue libinput events.
890 * @param libinput A previously initialized libinput context
892 * @return 0 on success, or a negative errno on failure
895 libinput_dispatch(struct libinput *libinput);
900 * Retrieve the next event from libinput's internal event queue.
902 * After handling the retrieved event, the caller must destroy it using
903 * libinput_event_destroy().
905 * @param libinput A previously initialized libinput context
906 * @return The next available event, or NULL if no event is available.
908 struct libinput_event *
909 libinput_get_event(struct libinput *libinput);
914 * Return the type of the next event in the internal queue. This function
915 * does not pop the event off the queue and the next call to
916 * libinput_get_event() returns that event.
918 * @param libinput A previously initialized libinput context
919 * @return The event type of the next available event or LIBINPUT_EVENT_NONE
920 * if no event is availble.
922 enum libinput_event_type
923 libinput_next_event_type(struct libinput *libinput);
928 * @param libinput A previously initialized libinput context
929 * @return the caller-specific data previously assigned in
930 * libinput_create_udev().
933 libinput_get_user_data(struct libinput *libinput);
938 * Resume a suspended libinput context. This re-enables device
939 * monitoring and adds existing devices.
941 * @param libinput A previously initialized libinput context
942 * @see libinput_suspend
944 * @return 0 on success or -1 on failure
947 libinput_resume(struct libinput *libinput);
952 * Suspend monitoring for new devices and close existing devices.
953 * This all but terminates libinput but does keep the context
954 * valid to be resumed with libinput_resume().
956 * @param libinput A previously initialized libinput context
959 libinput_suspend(struct libinput *libinput);
964 * Destroy the libinput context. After this, object references associated with
965 * the destroyed context are invalid and may not be interacted with.
967 * @param libinput A previously initialized libinput context
970 libinput_destroy(struct libinput *libinput);
975 * Set the global log priority. Messages with priorities equal to or
976 * higher than the argument will be printed to the current log handler.
978 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
980 * @param priority The minimum priority of log messages to print.
982 * @see libinput_log_set_handler
983 * @see libinput_log_get_priority
986 libinput_log_set_priority(enum libinput_log_priority priority);
991 * Get the global log priority. Messages with priorities equal to or
992 * higher than the argument will be printed to the current log handler.
994 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
996 * @return The minimum priority of log messages to print.
998 * @see libinput_log_set_handler
999 * @see libinput_log_set_priority
1001 enum libinput_log_priority
1002 libinput_log_get_priority(void);
1007 * Log handler type for custom logging.
1009 * @param priority The priority of the current message
1010 * @param user_data Caller-specific data pointer as previously passed into
1011 * libinput_log_set_handler()
1012 * @param format Message format in printf-style
1013 * @param args Message arguments
1015 * @see libinput_set_log_priority
1016 * @see libinput_log_set_handler
1018 typedef void (*libinput_log_handler)(enum libinput_log_priority priority,
1020 const char *format, va_list args)
1021 LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
1026 * Set the global log handler. Messages with priorities equal to or higher
1027 * than the current log priority will be passed to the given
1030 * The default log handler prints to stderr.
1032 * @param log_handler The log handler for library messages.
1033 * @param user_data Caller-specific data pointer, passed into the log
1036 * @see libinput_log_set_handler
1039 libinput_log_set_handler(libinput_log_handler log_handler,
1043 * @defgroup seat Initialization and manipulation of seats
1045 * A seat has two identifiers, the physical name and the logical name. The
1046 * physical name is summarized as the list of devices a process on the same
1047 * physical seat has access to.
1049 * The logical seat name is the seat name for a logical group of devices. A
1050 * compositor may use that to create additonal seats as independent device
1051 * sets. Alternatively, a compositor may limit itself to a single logical
1052 * seat, leaving a second compositor to manage devices on the other logical
1056 * +---+--------+------------+------------------------+------------+
1057 * | | event0 | | | log seat A |
1058 * | K +--------+ | +------------+
1059 * | e | event1 | phys seat0 | libinput context 1 | |
1060 * | r +--------+ | | log seat B |
1061 * | n | event2 | | | |
1062 * | e +--------+------------+------------------------+------------+
1063 * | l | event3 | phys seat1 | libinput context 2 | log seat C |
1064 * +---+--------+------------+------------------------+------------+
1071 * Increase the refcount of the seat. A seat will be freed whenever the
1072 * refcount reaches 0. This may happen during dispatch if the
1073 * seat was removed from the system. A caller must ensure to reference
1074 * the seat correctly to avoid dangling pointers.
1076 * @param seat A previously obtained seat
1079 libinput_seat_ref(struct libinput_seat *seat);
1084 * Decrease the refcount of the seat. A seat will be freed whenever the
1085 * refcount reaches 0. This may happen during dispatch if the
1086 * seat was removed from the system. A caller must ensure to reference
1087 * the seat correctly to avoid dangling pointers.
1089 * @param seat A previously obtained seat
1092 libinput_seat_unref(struct libinput_seat *seat);
1097 * Set caller-specific data associated with this seat. libinput does
1098 * not manage, look at, or modify this data. The caller must ensure the
1101 * @param seat A previously obtained seat
1102 * @param user_data Caller-specific data pointer
1103 * @see libinput_seat_get_user_data
1106 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
1111 * Get the caller-specific data associated with this seat, if any.
1113 * @param seat A previously obtained seat
1114 * @return Caller-specific data pointer or NULL if none was set
1115 * @see libinput_seat_set_user_data
1118 libinput_seat_get_user_data(struct libinput_seat *seat);
1123 * Return the physical name of the seat. For libinput contexts created from
1124 * udev, this is always the same value as passed into
1125 * libinput_udev_create_for_seat() and all seats from that context will have
1126 * the same physical name.
1128 * The physical name of the seat is one that is usually set by the system or
1129 * lower levels of the stack. In most cases, this is the base filter for
1130 * devices - devices assigned to seats outside the current seat will not
1131 * be available to the caller.
1133 * @param seat A previously obtained seat
1134 * @return the physical name of this seat
1137 libinput_seat_get_physical_name(struct libinput_seat *seat);
1142 * Return the logical name of the seat. This is an identifier to group sets
1143 * of devices within the compositor.
1145 * @param seat A previously obtained seat
1146 * @return the logical name of this seat
1149 libinput_seat_get_logical_name(struct libinput_seat *seat);
1152 * @defgroup device Initialization and manipulation of input devices
1158 * Increase the refcount of the input device. An input device will be freed
1159 * whenever the refcount reaches 0. This may happen during dispatch if the
1160 * device was removed from the system. A caller must ensure to reference
1161 * the device correctly to avoid dangling pointers.
1163 * @param device A previously obtained device
1166 libinput_device_ref(struct libinput_device *device);
1171 * Decrease the refcount of the input device. An input device will be freed
1172 * whenever the refcount reaches 0. This may happen during dispatch if the
1173 * device was removed from the system. A caller must ensure to reference
1174 * the device correctly to avoid dangling pointers.
1176 * @param device A previously obtained device
1179 libinput_device_unref(struct libinput_device *device);
1184 * Set caller-specific data associated with this input device. libinput does
1185 * not manage, look at, or modify this data. The caller must ensure the
1188 * @param device A previously obtained device
1189 * @param user_data Caller-specific data pointer
1190 * @see libinput_device_get_user_data
1193 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1198 * Get the caller-specific data associated with this input device, if any.
1200 * @param device A previously obtained device
1201 * @return Caller-specific data pointer or NULL if none was set
1202 * @see libinput_device_set_user_data
1205 libinput_device_get_user_data(struct libinput_device *device);
1210 * Get the system name of the device.
1212 * @param device A previously obtained device
1213 * @return System name of the device
1216 libinput_device_get_sysname(struct libinput_device *device);
1221 * A device may be mapped to a single output, or all available outputs. If a
1222 * device is mapped to a single output only, a relative device may not move
1223 * beyond the boundaries of this output. An absolute device has its input
1224 * coordinates mapped to the extents of this output.
1226 * @return the name of the output this device is mapped to, or NULL if no
1230 libinput_device_get_output_name(struct libinput_device *device);
1235 * Get the seat associated with this input device.
1237 * A seat can be uniquely identified by the physical and logical seat name.
1238 * There will ever be only one seat instance with a given physical and logical
1239 * seat name pair at any given time, but if no external reference is kept, it
1240 * may be destroyed if no device belonging to it is left.
1242 * @param device A previously obtained device
1243 * @return The seat this input device belongs to
1245 struct libinput_seat *
1246 libinput_device_get_seat(struct libinput_device *device);
1251 * Update the LEDs on the device, if any. If the device does not have
1252 * LEDs, or does not have one or more of the LEDs given in the mask, this
1253 * function does nothing.
1255 * @param device A previously obtained device
1256 * @param leds A mask of the LEDs to set, or unset.
1259 libinput_device_led_update(struct libinput_device *device,
1260 enum libinput_led leds);
1265 * Set the bitmask in keys to the bitmask of the keys present on the device
1266 * (see linux/input.h), up to size characters.
1268 * @param device A current input device
1269 * @param keys An array filled with the bitmask for the keys
1270 * @param size Size of the keys array
1272 * @return The number of valid bytes in keys, or a negative errno on failure
1275 libinput_device_get_keys(struct libinput_device *device,
1276 char *keys, size_t size);
1281 * Apply the 3x3 transformation matrix to absolute device coordinates. This
1282 * matrix has no effect on relative events.
1284 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1292 libinput_device_calibrate(struct libinput_device *device,
1293 float calibration[6]);
1298 * Check if the given device has the specified capability
1300 * @return 1 if the given device has the capability or 0 if not
1303 libinput_device_has_capability(struct libinput_device *device,
1304 enum libinput_device_capability capability);
1310 #endif /* LIBINPUT_H */