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 * @ingroup fixed_point
44 * libinput 24.8 fixed point real number.
46 typedef int32_t li_fixed_t;
49 * Log priority for internal logging messages.
51 enum libinput_log_priority {
52 LIBINPUT_LOG_PRIORITY_DEBUG = 10,
53 LIBINPUT_LOG_PRIORITY_INFO = 20,
54 LIBINPUT_LOG_PRIORITY_ERROR = 30,
60 * Capabilities on a device. A device may have one or more capabilities
61 * at a time, and capabilities may appear or disappear during the
62 * lifteime of the device.
64 enum libinput_device_capability {
65 LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
66 LIBINPUT_DEVICE_CAP_POINTER = 1,
67 LIBINPUT_DEVICE_CAP_TOUCH = 2
73 * Logical state of a key. Note that the logical state may not represent
74 * the physical state of the key.
76 enum libinput_keyboard_key_state {
77 LIBINPUT_KEYBOARD_KEY_STATE_RELEASED = 0,
78 LIBINPUT_KEYBOARD_KEY_STATE_PRESSED = 1
84 * Mask reflecting LEDs on a device.
87 LIBINPUT_LED_NUM_LOCK = (1 << 0),
88 LIBINPUT_LED_CAPS_LOCK = (1 << 1),
89 LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
95 * Logical state of a physical button. Note that the logical state may not
96 * represent the physical state of the button.
98 enum libinput_pointer_button_state {
99 LIBINPUT_POINTER_BUTTON_STATE_RELEASED = 0,
100 LIBINPUT_POINTER_BUTTON_STATE_PRESSED = 1
107 * Axes on a device that are not x or y coordinates.
109 enum libinput_pointer_axis {
110 LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = 0,
111 LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = 1
117 * Event type for events returned by libinput_get_event().
119 enum libinput_event_type {
121 * This is not a real event type, and is only used to tell the user that
122 * no new event is available in the queue. See
123 * libinput_next_event_type().
125 LIBINPUT_EVENT_NONE = 0,
128 * Signals that a device has been added to the context. The device will
129 * not be read until the next time the user calls libinput_dispatch()
130 * and data is available.
132 * This allows setting up initial device configuration before any events
135 LIBINPUT_EVENT_DEVICE_ADDED,
138 * Signals that a device has been removed. No more events from the
139 * associated device will be in the queue or be queued after this event.
141 LIBINPUT_EVENT_DEVICE_REMOVED,
143 LIBINPUT_EVENT_KEYBOARD_KEY = 300,
145 LIBINPUT_EVENT_POINTER_MOTION = 400,
146 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
147 LIBINPUT_EVENT_POINTER_BUTTON,
148 LIBINPUT_EVENT_POINTER_AXIS,
150 LIBINPUT_EVENT_TOUCH_DOWN = 500,
151 LIBINPUT_EVENT_TOUCH_UP,
152 LIBINPUT_EVENT_TOUCH_MOTION,
153 LIBINPUT_EVENT_TOUCH_CANCEL,
155 * Signals the end of a set of touchpoints at one device sample
156 * time. This event has no coordinate information attached.
158 LIBINPUT_EVENT_TOUCH_FRAME
162 struct libinput_device;
163 struct libinput_seat;
165 struct libinput_event;
166 struct libinput_event_device_notify;
167 struct libinput_event_keyboard;
168 struct libinput_event_pointer;
171 * @ingroup event_touch
172 * @struct libinput_event_touch
174 * Touch event representing a touch down, move or up, as well as a touch
175 * cancel and touch frame events. Valid event types for this event are @ref
176 * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
177 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
178 * LIBINPUT_EVENT_TOUCH_FRAME.
180 struct libinput_event_touch;
183 * @defgroup fixed_point Fixed point utilities
187 * @ingroup fixed_point
189 * Convert li_fixed_t to a double
191 * @param f fixed point number
192 * @return Converted double
195 li_fixed_to_double (li_fixed_t f)
202 u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f;
204 return u.d - (3LL << 43);
208 * @ingroup fixed_point
210 * Convert li_fixed_t to a int. The fraction part is discarded.
212 * @param f fixed point number
213 * @return Converted int
216 li_fixed_to_int(li_fixed_t f)
222 * @defgroup event Acessing and destruction of events
230 * @param event An event retrieved by libinput_get_event().
233 libinput_event_destroy(struct libinput_event *event);
238 * Get the type of the event.
240 * @param event An event retrieved by libinput_get_event().
242 enum libinput_event_type
243 libinput_event_get_type(struct libinput_event *event);
248 * Get the libinput context from the event.
250 * @param event The libinput event
251 * @return The libinput context for this event.
254 libinput_event_get_context(struct libinput_event *event);
259 * Return the device associated with this event, if applicable. For device
260 * added/removed events this is the device added or removed. For all other
261 * device events, this is the device that generated the event.
263 * This device is not refcounted and its lifetime is that of the event. Use
264 * libinput_device_ref() before using the device outside of this scope.
266 * @return The device associated with this event
269 struct libinput_device *
270 libinput_event_get_device(struct libinput_event *event);
275 * Return the pointer event that is this input event. If the event type does
276 * not match the pointer event types, this function returns NULL.
278 * The inverse of this function is libinput_event_pointer_get_base_event().
280 * @return A pointer event, or NULL for other events
282 struct libinput_event_pointer *
283 libinput_event_get_pointer_event(struct libinput_event *event);
288 * Return the keyboard event that is this input event. If the event type does
289 * not match the keyboard event types, this function returns NULL.
291 * The inverse of this function is libinput_event_keyboard_get_base_event().
293 * @return A keyboard event, or NULL for other events
295 struct libinput_event_keyboard *
296 libinput_event_get_keyboard_event(struct libinput_event *event);
301 * Return the touch event that is this input event. If the event type does
302 * not match the touch event types, this function returns NULL.
304 * The inverse of this function is libinput_event_touch_get_base_event().
306 * @return A touch event, or NULL for other events
308 struct libinput_event_touch *
309 libinput_event_get_touch_event(struct libinput_event *event);
314 * Return the device event that is this input event. If the event type does
315 * not match the device event types, this function returns NULL.
317 * The inverse of this function is
318 * libinput_event_device_notify_get_base_event().
320 * @return A device event, or NULL for other events
322 struct libinput_event_device_notify *
323 libinput_event_get_device_notify_event(struct libinput_event *event);
328 * @return The generic libinput_event of this event
330 struct libinput_event *
331 libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
334 * @defgroup event_keyboard Keyboard events
336 * Key events are generated when a key changes its logical state, usually by
337 * being pressed or released.
341 * @ingroup event_keyboard
343 * @return The event time for this event
346 libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
349 * @ingroup event_keyboard
351 * @return The keycode that triggered this key event
354 libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
357 * @ingroup event_keyboard
359 * @return The state change of the key
361 enum libinput_keyboard_key_state
362 libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
366 * @ingroup event_keyboard
368 * @return The generic libinput_event of this event
370 struct libinput_event *
371 libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
374 * @defgroup event_pointer Pointer events
376 * Pointer events reflect motion, button and scroll events, as well as
377 * events from other axes.
381 * @ingroup event_pointer
383 * @return The event time for this event
386 libinput_event_pointer_get_time(struct libinput_event_pointer *event);
389 * @ingroup event_pointer
391 * Return the delta between the last event and the current event. For pointer
392 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
395 * @note It is an application bug to call this function for events other than
396 * LIBINPUT_EVENT_POINTER_MOTION.
398 * @return the relative x movement since the last event
401 libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
404 * @ingroup event_pointer
406 * Return the delta between the last event and the current event. For pointer
407 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
410 * @note It is an application bug to call this function for events other than
411 * LIBINPUT_EVENT_POINTER_MOTION.
413 * @return the relative y movement since the last event
416 libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
419 * @ingroup event_pointer
421 * Return the current absolute x coordinate of the pointer event.
423 * The coordinate is in a device specific coordinate space; to get the
424 * corresponding output screen coordinate, use
425 * libinput_event_pointer_get_x_transformed().
427 * For pointer events that are not of type
428 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
430 * @note It is an application bug to call this function for events other than
431 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
433 * @return the current absolute x coordinate
436 libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
439 * @ingroup event_pointer
441 * Return the current absolute y coordinate of the pointer event.
443 * The coordinate is in a device specific coordinate space; to get the
444 * corresponding output screen coordinate, use
445 * libinput_event_pointer_get_y_transformed().
447 * For pointer events that are not of type
448 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
450 * @note It is an application bug to call this function for events other than
451 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
453 * @return the current absolute y coordinate
456 libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
459 * @ingroup event_pointer
461 * Return the current absolute x coordinate of the pointer event, transformed to
462 * screen coordinates.
464 * For pointer events that are not of type
465 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
468 * @note It is an application bug to call this function for events other than
469 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
471 * @param event The libinput pointer event
472 * @param width The current output screen width
473 * @return the current absolute x coordinate transformed to a screen coordinate
476 libinput_event_pointer_get_absolute_x_transformed(
477 struct libinput_event_pointer *event,
481 * @ingroup event_pointer
483 * Return the current absolute y coordinate of the pointer event, transformed to
484 * screen coordinates.
486 * For pointer events that are not of type
487 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
490 * @note It is an application bug to call this function for events other than
491 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
493 * @param event The libinput pointer event
494 * @param height The current output screen height
495 * @return the current absolute y coordinate transformed to a screen coordinate
498 libinput_event_pointer_get_absolute_y_transformed(
499 struct libinput_event_pointer *event,
503 * @ingroup event_pointer
505 * Return the button that triggered this event.
506 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
507 * this function returns 0.
509 * @note It is an application bug to call this function for events other than
510 * LIBINPUT_EVENT_POINTER_BUTTON.
512 * @return the button triggering this event
515 libinput_event_pointer_get_button(struct libinput_event_pointer *event);
518 * @ingroup event_pointer
520 * Return the button state that triggered this event.
521 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
522 * this function returns 0.
524 * @note It is an application bug to call this function for events other than
525 * LIBINPUT_EVENT_POINTER_BUTTON.
527 * @return the button state triggering this event
529 enum libinput_pointer_button_state
530 libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
533 * @ingroup event_pointer
535 * Return the axis that triggered this event.
536 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
537 * this function returns 0.
539 * @note It is an application bug to call this function for events other than
540 * LIBINPUT_EVENT_POINTER_AXIS.
542 * @return the axis triggering this event
544 enum libinput_pointer_axis
545 libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
548 * @ingroup event_pointer
550 * Return the axis value of the given axis. The interpretation of the value
551 * is dependent on the axis. For the two scrolling axes
552 * LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL and
553 * LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL, the value of the event is in
554 * relative scroll units, with the positive direction being down or right,
555 * respectively. The dimension of a scroll unit is equal to one unit of
556 * motion in the respective axis, where applicable (e.g. touchpad two-finger
559 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
560 * this function returns 0.
562 * @note It is an application bug to call this function for events other than
563 * LIBINPUT_EVENT_POINTER_AXIS.
565 * @return the axis value of this event
568 libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
571 * @ingroup event_pointer
573 * @return The generic libinput_event of this event
575 struct libinput_event *
576 libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
580 * @defgroup event_touch Touch events
582 * Events from absolute touch devices.
586 * @ingroup event_touch
588 * @return The event time for this event
591 libinput_event_touch_get_time(struct libinput_event_touch *event);
594 * @ingroup event_touch
596 * Get the slot of this touch event. See the kernel's multitouch
597 * protocol B documentation for more information.
599 * If the touch event has no assigned slot, for example if it is from a
600 * single touch device, this function returns -1.
602 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
603 * LIBINPUT_EVENT_TOUCH_FRAME.
605 * @return The slot of this touch event
608 libinput_event_touch_get_slot(struct libinput_event_touch *event);
611 * @ingroup event_touch
613 * Get the seat slot of the touch event. A seat slot is a non-negative seat
614 * wide unique identifier of an active touch point.
616 * Events from single touch devices will be represented as one individual
617 * touch point per device.
619 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
620 * LIBINPUT_EVENT_TOUCH_FRAME.
622 * @return The seat slot of the touch event
625 libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
628 * @ingroup event_touch
630 * Return the current absolute x coordinate of the touch event.
632 * The coordinate is in a device specific coordinate space; to get the
633 * corresponding output screen coordinate, use
634 * libinput_event_touch_get_x_transformed().
636 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
637 * LIBINPUT_EVENT_TOUCH_MOTION.
639 * @param event The libinput touch event
640 * @return the current absolute x coordinate
643 libinput_event_touch_get_x(struct libinput_event_touch *event);
646 * @ingroup event_touch
648 * Return the current absolute y coordinate of the touch event.
650 * The coordinate is in a device specific coordinate space; to get the
651 * corresponding output screen coordinate, use
652 * libinput_event_touch_get_y_transformed().
654 * For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
656 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
657 * LIBINPUT_EVENT_TOUCH_MOTION.
659 * @param event The libinput touch event
660 * @return the current absolute y coordinate
663 libinput_event_touch_get_y(struct libinput_event_touch *event);
666 * @ingroup event_touch
668 * Return the current absolute x coordinate of the touch event, transformed to
669 * screen coordinates.
671 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
672 * LIBINPUT_EVENT_TOUCH_MOTION.
674 * @param event The libinput touch event
675 * @param width The current output screen width
676 * @return the current absolute x coordinate transformed to a screen coordinate
679 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
683 * @ingroup event_touch
685 * Return the current absolute y coordinate of the touch event, transformed to
686 * screen coordinates.
688 * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
689 * LIBINPUT_EVENT_TOUCH_MOTION.
691 * @param event The libinput touch event
692 * @param height The current output screen height
693 * @return the current absolute y coordinate transformed to a screen coordinate
696 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
700 * @ingroup event_touch
702 * @return The generic libinput_event of this event
704 struct libinput_event *
705 libinput_event_touch_get_base_event(struct libinput_event_touch *event);
708 * @defgroup base Initialization and manipulation of libinput contexts
711 struct libinput_interface {
713 * Open the device at the given path with the flags provided and
716 * @param path The device path to open
717 * @param flags Flags as defined by open(2)
718 * @param user_data The user_data provided in
719 * libinput_udev_create_for_seat()
721 * @return the file descriptor, or a negative errno on failure.
723 int (*open_restricted)(const char *path, int flags, void *user_data);
725 * Close the file descriptor.
727 * @param fd The file descriptor to close
728 * @param user_data The user_data provided in
729 * libinput_udev_create_for_seat()
731 void (*close_restricted)(int fd, void *user_data);
737 * Create a new libinput context from udev, for input devices matching
738 * the given seat ID. New devices or devices removed will appear as events
739 * during libinput_dispatch.
741 * libinput_udev_create_for_seat() succeeds even if no input device is
742 * available in this seat, or if devices are available but fail to open in
743 * @ref libinput_interface::open_restricted. Devices that do not have the
744 * minimum capabilities to be recognized as pointer, keyboard or touch
745 * device are ignored. Such devices and those that failed to open
746 * ignored until the next call to libinput_resume().
748 * @param interface The callback interface
749 * @param user_data Caller-specific data passed to the various callback
751 * @param udev An already initialized udev context
752 * @param seat_id A seat identifier. This string must not be NULL.
754 * @return An initialized libinput context, ready to handle events or NULL on
758 libinput_udev_create_for_seat(const struct libinput_interface *interface,
761 const char *seat_id);
766 * Create a new libinput context that requires the caller to manually add or
767 * remove devices with libinput_path_add_device() and
768 * libinput_path_remove_device().
770 * The context is fully initialized but will not generate events until at
771 * least one device has been added.
773 * @param interface The callback interface
774 * @param user_data Caller-specific data passed to the various callback
777 * @return An initialized, empty libinput context.
780 libinput_path_create_context(const struct libinput_interface *interface,
786 * Add a device to a libinput context initialized with
787 * libinput_path_create_from_device(). If successful, the device will be
788 * added to the internal list and re-opened on libinput_resume(). The device
789 * can be removed with libinput_path_remove_device().
791 * If the device was successfully initialized, it is returned in the device
792 * argument. The lifetime of the returned device pointer is limited until
793 * the next linput_dispatch(), use libinput_device_ref() to keep a permanent
796 * @param libinput A previously initialized libinput context
797 * @param path Path to an input device
798 * @return The newly initiated device on success, or NULL on failure.
800 * @note It is an application bug to call this function on a libinput
801 * context initialize with libinput_udev_create_for_seat().
803 struct libinput_device *
804 libinput_path_add_device(struct libinput *libinput,
810 * Remove a device from a libinput context initialized with
811 * libinput_path_create_from_device() or added to such a context with
812 * libinput_path_add_device().
814 * Events already processed from this input device are kept in the queue,
815 * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
818 * If no matching device exists, this function does nothing.
820 * @param device A libinput device
822 * @note It is an application bug to call this function on a libinput
823 * context initialize with libinput_udev_create_for_seat().
826 libinput_path_remove_device(struct libinput_device *device);
831 * libinput keeps a single file descriptor for all events. Call into
832 * libinput_dispatch() if any events become available on this fd.
834 * @return the file descriptor used to notify of pending events.
837 libinput_get_fd(struct libinput *libinput);
842 * Main event dispatchment function. Reads events of the file descriptors
843 * and processes them internally. Use libinput_get_event() to retrieve the
846 * Dispatching does not necessarily queue libinput events.
848 * @param libinput A previously initialized libinput context
850 * @return 0 on success, or a negative errno on failure
853 libinput_dispatch(struct libinput *libinput);
858 * Retrieve the next event from libinput's internal event queue.
860 * After handling the retrieved event, the caller must destroy it using
861 * libinput_event_destroy().
863 * @param libinput A previously initialized libinput context
864 * @return The next available event, or NULL if no event is available.
866 struct libinput_event *
867 libinput_get_event(struct libinput *libinput);
872 * Return the type of the next event in the internal queue. This function
873 * does not pop the event off the queue and the next call to
874 * libinput_get_event() returns that event.
876 * @param libinput A previously initialized libinput context
877 * @return The event type of the next available event or LIBINPUT_EVENT_NONE
878 * if no event is availble.
880 enum libinput_event_type
881 libinput_next_event_type(struct libinput *libinput);
886 * @param libinput A previously initialized libinput context
887 * @return the caller-specific data previously assigned in
888 * libinput_create_udev().
891 libinput_get_user_data(struct libinput *libinput);
896 * Resume a suspended libinput context. This re-enables device
897 * monitoring and adds existing devices.
899 * @param libinput A previously initialized libinput context
900 * @see libinput_suspend
902 * @return 0 on success or -1 on failure
905 libinput_resume(struct libinput *libinput);
910 * Suspend monitoring for new devices and close existing devices.
911 * This all but terminates libinput but does keep the context
912 * valid to be resumed with libinput_resume().
914 * @param libinput A previously initialized libinput context
917 libinput_suspend(struct libinput *libinput);
922 * Destroy the libinput context. After this, object references associated with
923 * the destroyed context are invalid and may not be interacted with.
925 * @param libinput A previously initialized libinput context
928 libinput_destroy(struct libinput *libinput);
933 * Set the global log priority. Messages with priorities equal to or
934 * higher than the argument will be printed to the current log handler.
936 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
938 * @param priority The minimum priority of log messages to print.
940 * @see libinput_log_set_handler
943 libinput_log_set_priority(enum libinput_log_priority priority);
948 * Get the global log priority. Messages with priorities equal to or
949 * higher than the argument will be printed to the current log handler.
951 * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
953 * @return The minimum priority of log messages to print.
955 * @see libinput_log_set_handler
957 enum libinput_log_priority
958 libinput_log_get_priority(void);
963 * Log handler type for custom logging.
965 * @param priority The priority of the current message
966 * @param user_data Caller-specific data pointer as previously passed into
967 * libinput_log_set_handler()
968 * @param format Message format in printf-style
969 * @param args Message arguments
971 * @see libinput_set_log_priority
972 * @see libinput_log_set_handler
974 typedef void (*libinput_log_handler)(enum libinput_log_priority priority,
976 const char *format, va_list args);
981 * Set the global log handler. Messages with priorities equal to or higher
982 * than the current log priority will be passed to the given
985 * The default log handler prints to stderr.
987 * @param log_handler The log handler for library messages.
988 * @param user_data Caller-specific data pointer, passed into the log
991 * @see libinput_log_set_handler
994 libinput_log_set_handler(libinput_log_handler log_handler,
998 * @defgroup seat Initialization and manipulation of seats
1000 * A seat has two identifiers, the physical name and the logical name. The
1001 * physical name is summarized as the list of devices a process on the same
1002 * physical seat has access to.
1004 * The logical seat name is the seat name for a logical group of devices. A
1005 * compositor may use that to create additonal seats as independent device
1006 * sets. Alternatively, a compositor may limit itself to a single logical
1007 * seat, leaving a second compositor to manage devices on the other logical
1011 * +---+--------+------------+------------------------+------------+
1012 * | | event0 | | | log seat A |
1013 * | K +--------+ | +------------+
1014 * | e | event1 | phys seat0 | libinput context 1 | |
1015 * | r +--------+ | | log seat B |
1016 * | n | event2 | | | |
1017 * | e +--------+------------+------------------------+------------+
1018 * | l | event3 | phys seat1 | libinput context 2 | log seat C |
1019 * +---+--------+------------+------------------------+------------+
1026 * Increase the refcount of the seat. A seat will be freed whenever the
1027 * refcount reaches 0. This may happen during dispatch if the
1028 * seat was removed from the system. A caller must ensure to reference
1029 * the seat correctly to avoid dangling pointers.
1031 * @param seat A previously obtained seat
1034 libinput_seat_ref(struct libinput_seat *seat);
1039 * Decrease the refcount of the seat. A seat will be freed whenever the
1040 * refcount reaches 0. This may happen during dispatch if the
1041 * seat was removed from the system. A caller must ensure to reference
1042 * the seat correctly to avoid dangling pointers.
1044 * @param seat A previously obtained seat
1047 libinput_seat_unref(struct libinput_seat *seat);
1052 * Set caller-specific data associated with this seat. libinput does
1053 * not manage, look at, or modify this data. The caller must ensure the
1056 * @param seat A previously obtained seat
1057 * @param user_data Caller-specific data pointer
1058 * @see libinput_seat_get_user_data
1061 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
1066 * Get the caller-specific data associated with this seat, if any.
1068 * @param seat A previously obtained seat
1069 * @return Caller-specific data pointer or NULL if none was set
1070 * @see libinput_seat_set_user_data
1073 libinput_seat_get_user_data(struct libinput_seat *seat);
1078 * Return the physical name of the seat. For libinput contexts created from
1079 * udev, this is always the same value as passed into
1080 * libinput_udev_create_for_seat() and all seats from that context will have
1081 * the same physical name.
1083 * The physical name of the seat is one that is usually set by the system or
1084 * lower levels of the stack. In most cases, this is the base filter for
1085 * devices - devices assigned to seats outside the current seat will not
1086 * be available to the caller.
1088 * @param seat A previously obtained seat
1089 * @return the physical name of this seat
1092 libinput_seat_get_physical_name(struct libinput_seat *seat);
1097 * Return the logical name of the seat. This is an identifier to group sets
1098 * of devices within the compositor.
1100 * @param seat A previously obtained seat
1101 * @return the logical name of this seat
1104 libinput_seat_get_logical_name(struct libinput_seat *seat);
1107 * @defgroup device Initialization and manipulation of input devices
1113 * Increase the refcount of the input device. An input device will be freed
1114 * whenever the refcount reaches 0. This may happen during dispatch if the
1115 * device was removed from the system. A caller must ensure to reference
1116 * the device correctly to avoid dangling pointers.
1118 * @param device A previously obtained device
1121 libinput_device_ref(struct libinput_device *device);
1126 * Decrease the refcount of the input device. An input device will be freed
1127 * whenever the refcount reaches 0. This may happen during dispatch if the
1128 * device was removed from the system. A caller must ensure to reference
1129 * the device correctly to avoid dangling pointers.
1131 * @param device A previously obtained device
1134 libinput_device_unref(struct libinput_device *device);
1139 * Set caller-specific data associated with this input device. libinput does
1140 * not manage, look at, or modify this data. The caller must ensure the
1143 * @param device A previously obtained device
1144 * @param user_data Caller-specific data pointer
1145 * @see libinput_device_get_user_data
1148 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1153 * Get the caller-specific data associated with this input device, if any.
1155 * @param device A previously obtained device
1156 * @return Caller-specific data pointer or NULL if none was set
1157 * @see libinput_device_set_user_data
1160 libinput_device_get_user_data(struct libinput_device *device);
1165 * Get the system name of the device.
1167 * @param device A previously obtained device
1168 * @return System name of the device
1171 libinput_device_get_sysname(struct libinput_device *device);
1176 * A device may be mapped to a single output, or all available outputs. If a
1177 * device is mapped to a single output only, a relative device may not move
1178 * beyond the boundaries of this output. An absolute device has its input
1179 * coordinates mapped to the extents of this output.
1181 * @return the name of the output this device is mapped to, or NULL if no
1185 libinput_device_get_output_name(struct libinput_device *device);
1190 * Get the seat associated with this input device.
1192 * A seat can be uniquely identified by the physical and logical seat name.
1193 * There will ever be only one seat instance with a given physical and logical
1194 * seat name pair at any given time, but if no external reference is kept, it
1195 * may be destroyed if no device belonging to it is left.
1197 * @param device A previously obtained device
1198 * @return The seat this input device belongs to
1200 struct libinput_seat *
1201 libinput_device_get_seat(struct libinput_device *device);
1206 * Update the LEDs on the device, if any. If the device does not have
1207 * LEDs, or does not have one or more of the LEDs given in the mask, this
1208 * function does nothing.
1210 * @param device A previously obtained device
1211 * @param leds A mask of the LEDs to set, or unset.
1214 libinput_device_led_update(struct libinput_device *device,
1215 enum libinput_led leds);
1220 * Set the bitmask in keys to the bitmask of the keys present on the device
1221 * (see linux/input.h), up to size characters.
1223 * @param device A current input device
1224 * @param keys An array filled with the bitmask for the keys
1225 * @param size Size of the keys array
1227 * @return The number of valid bytes in keys, or a negative errno on failure
1230 libinput_device_get_keys(struct libinput_device *device,
1231 char *keys, size_t size);
1236 * Apply the 3x3 transformation matrix to absolute device coordinates. This
1237 * matrix has no effect on relative events.
1239 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1247 libinput_device_calibrate(struct libinput_device *device,
1248 float calibration[6]);
1253 * Check if the given device has the specified capability
1255 * @return 1 if the given device has the capability or 0 if not
1258 libinput_device_has_capability(struct libinput_device *device,
1259 enum libinput_device_capability capability);
1265 #endif /* LIBINPUT_H */