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.
32 * libinput is a generic input device handling library. It abstracts
33 * commonly-used concepts such as keyboard, pointer and touchpad handling
38 * @ingroup fixed_point
40 * libinput 24.8 fixed point real number.
42 typedef int32_t li_fixed_t;
47 * Capabilities on a device. A device may have one or more capabilities
48 * at a time, and capabilities may appear or disappear during the
49 * lifteime of the device.
51 enum libinput_device_capability {
52 LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
53 LIBINPUT_DEVICE_CAP_POINTER = 1,
54 LIBINPUT_DEVICE_CAP_TOUCH = 2
60 * Logical state of a key. Note that the logical state may not represent
61 * the physical state of the key.
63 enum libinput_keyboard_key_state {
64 LIBINPUT_KEYBOARD_KEY_STATE_RELEASED = 0,
65 LIBINPUT_KEYBOARD_KEY_STATE_PRESSED = 1
71 * Mask reflecting LEDs on a device.
74 LIBINPUT_LED_NUM_LOCK = (1 << 0),
75 LIBINPUT_LED_CAPS_LOCK = (1 << 1),
76 LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
82 * Logical state of a physical button. Note that the logical state may not
83 * represent the physical state of the button.
85 enum libinput_pointer_button_state {
86 LIBINPUT_POINTER_BUTTON_STATE_RELEASED = 0,
87 LIBINPUT_POINTER_BUTTON_STATE_PRESSED = 1
94 * Axes on a device that are not x or y coordinates.
96 enum libinput_pointer_axis {
97 LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = 0,
98 LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = 1
104 * Logical touch state of a touch point. A touch point usually follows the
105 * sequence down, motion, up, with the number of motion events being zero or
106 * greater. If a touch point was used for gesture interpretation internally
107 * and will not generate any further events, the touchpoint is cancelled.
109 enum libinput_touch_type {
110 LIBINPUT_TOUCH_TYPE_DOWN = 0,
111 LIBINPUT_TOUCH_TYPE_UP = 1,
112 LIBINPUT_TOUCH_TYPE_MOTION = 2,
113 LIBINPUT_TOUCH_TYPE_CANCEL = 4
119 * Event type for events returned by libinput_get_event().
121 enum libinput_event_type {
123 * This is not a real event type, and is only used to tell the user that
124 * no new event is available in the queue. See
125 * libinput_next_event_type().
127 LIBINPUT_EVENT_NONE = 0,
130 * Signals that a device has been added to the context. The device will
131 * not be read until the next time the user calls libinput_dispatch()
132 * and data is available.
134 * This allows setting up initial device configuration before any events
137 LIBINPUT_EVENT_DEVICE_ADDED,
140 * Signals that a device has been removed. No more events from the
141 * associated device will be in the queue or be queued after this event.
143 LIBINPUT_EVENT_DEVICE_REMOVED,
145 LIBINPUT_EVENT_KEYBOARD_KEY = 300,
147 LIBINPUT_EVENT_POINTER_MOTION = 400,
148 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
149 LIBINPUT_EVENT_POINTER_BUTTON,
150 LIBINPUT_EVENT_POINTER_AXIS,
152 LIBINPUT_EVENT_TOUCH_TOUCH = 500,
154 * Signals the end of a set of touchpoints at one device sample
155 * time. This event has no coordinate information attached.
157 LIBINPUT_EVENT_TOUCH_FRAME
161 struct libinput_device;
162 struct libinput_seat;
164 struct libinput_event;
165 struct libinput_event_device_notify;
166 struct libinput_event_keyboard;
167 struct libinput_event_pointer;
170 * @ingroup event_touch
171 * @struct libinput_event_touch
173 * Touch event representing a touch down, move or up, as well as a touch
174 * cancel and touch frame events. Valid event types for this event are @ref
175 * LIBINPUT_EVENT_TOUCH_TOUCH and @ref LIBINPUT_EVENT_TOUCH_FRAME.
177 struct libinput_event_touch;
180 * @defgroup fixed_point Fixed point utilities
184 * @ingroup fixed_point
186 * Convert li_fixed_t to a double
188 * @param f fixed point number
189 * @return Converted double
192 li_fixed_to_double (li_fixed_t f)
199 u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f;
201 return u.d - (3LL << 43);
205 * @ingroup fixed_point
207 * Convert li_fixed_t to a int. The fraction part is discarded.
209 * @param f fixed point number
210 * @return Converted int
213 li_fixed_to_int(li_fixed_t f)
219 * @defgroup event Acessing and destruction of events
227 * @param event An event retrieved by libinput_get_event().
230 libinput_event_destroy(struct libinput_event *event);
235 * Get the type of the event.
237 * @param event An event retrieved by libinput_get_event().
239 enum libinput_event_type
240 libinput_event_get_type(struct libinput_event *event);
245 * Get the libinput context from the event.
247 * @param event The libinput event
248 * @return The libinput context for this event.
251 libinput_event_get_context(struct libinput_event *event);
256 * Return the device associated with this event, if applicable. For device
257 * added/removed events this is the device added or removed. For all other
258 * device events, this is the device that generated the event.
260 * This device is not refcounted and its lifetime is that of the event. Use
261 * libinput_device_ref() before using the device outside of this scope.
263 * @return The device associated with this event
266 struct libinput_device *
267 libinput_event_get_device(struct libinput_event *event);
272 * Return the pointer event that is this input event. If the event type does
273 * not match the pointer event types, this function returns NULL.
275 * @return A pointer event, or NULL for other events
277 struct libinput_event_pointer *
278 libinput_event_get_pointer_event(struct libinput_event *event);
283 * Return the keyboard event that is this input event. If the event type does
284 * not match the keyboard event types, this function returns NULL.
286 * @return A keyboard event, or NULL for other events
288 struct libinput_event_keyboard *
289 libinput_event_get_keyboard_event(struct libinput_event *event);
294 * Return the touch event that is this input event. If the event type does
295 * not match the touch event types, this function returns NULL.
297 * @return A touch event, or NULL for other events
299 struct libinput_event_touch *
300 libinput_event_get_touch_event(struct libinput_event *event);
305 * Return the device event that is this input event. If the event type does
306 * not match the device event types, this function returns NULL.
308 * @return A device event, or NULL for other events
310 struct libinput_event_device_notify *
311 libinput_event_get_device_notify_event(struct libinput_event *event);
314 * @defgroup event_keyboard Keyboard events
316 * Key events are generated when a key changes its logical state, usually by
317 * being pressed or released.
321 * @ingroup event_keyboard
323 * @return The event time for this event
326 libinput_event_keyboard_get_time(
327 struct libinput_event_keyboard *event);
330 * @ingroup event_keyboard
332 * @return The keycode that triggered this key event
335 libinput_event_keyboard_get_key(
336 struct libinput_event_keyboard *event);
339 * @ingroup event_keyboard
341 * @return The state change of the key
343 enum libinput_keyboard_key_state
344 libinput_event_keyboard_get_key_state(
345 struct libinput_event_keyboard *event);
348 * @defgroup event_pointer Pointer events
350 * Pointer events reflect motion, button and scroll events, as well as
351 * events from other axes.
355 * @ingroup event_pointer
357 * @return The event time for this event
360 libinput_event_pointer_get_time(
361 struct libinput_event_pointer *event);
364 * @ingroup event_pointer
366 * Return the delta between the last event and the current event. For pointer
367 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
370 * @note It is an application bug to call this function for events other than
371 * LIBINPUT_EVENT_POINTER_MOTION.
373 * @return the relative x movement since the last event
376 libinput_event_pointer_get_dx(
377 struct libinput_event_pointer *event);
380 * @ingroup event_pointer
382 * Return the delta between the last event and the current event. For pointer
383 * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
386 * @note It is an application bug to call this function for events other than
387 * LIBINPUT_EVENT_POINTER_MOTION.
389 * @return the relative y movement since the last event
392 libinput_event_pointer_get_dy(
393 struct libinput_event_pointer *event);
396 * @ingroup event_pointer
398 * Return the current absolute x coordinate of the pointer event.
400 * The coordinate is in a device specific coordinate space; to get the
401 * corresponding output screen coordinate, use
402 * libinput_event_pointer_get_x_transformed().
404 * For pointer events that are not of type
405 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
407 * @note It is an application bug to call this function for events other than
408 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
410 * @return the current absolute x coordinate
413 libinput_event_pointer_get_absolute_x(
414 struct libinput_event_pointer *event);
417 * @ingroup event_pointer
419 * Return the current absolute y coordinate of the pointer event.
421 * The coordinate is in a device specific coordinate space; to get the
422 * corresponding output screen coordinate, use
423 * libinput_event_pointer_get_y_transformed().
425 * For pointer events that are not of type
426 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
428 * @note It is an application bug to call this function for events other than
429 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
431 * @return the current absolute y coordinate
434 libinput_event_pointer_get_absolute_y(
435 struct libinput_event_pointer *event);
438 * @ingroup event_pointer
440 * Return the current absolute x coordinate of the pointer event, transformed to
441 * screen coordinates.
443 * For pointer events that are not of type
444 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
447 * @note It is an application bug to call this function for events other than
448 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
450 * @param event The libinput pointer event
451 * @param width The current output screen width
452 * @return the current absolute x coordinate transformed to a screen coordinate
455 libinput_event_pointer_get_absolute_x_transformed(
456 struct libinput_event_pointer *event,
460 * @ingroup event_pointer
462 * Return the current absolute y coordinate of the pointer event, transformed to
463 * screen coordinates.
465 * For pointer events that are not of type
466 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
469 * @note It is an application bug to call this function for events other than
470 * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
472 * @param event The libinput pointer event
473 * @param height The current output screen height
474 * @return the current absolute y coordinate transformed to a screen coordinate
477 libinput_event_pointer_get_absolute_y_transformed(
478 struct libinput_event_pointer *event,
482 * @ingroup event_pointer
484 * Return the button that triggered this event.
485 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
486 * this function returns 0.
488 * @note It is an application bug to call this function for events other than
489 * LIBINPUT_EVENT_POINTER_BUTTON.
491 * @return the button triggering this event
494 libinput_event_pointer_get_button(
495 struct libinput_event_pointer *event);
498 * @ingroup event_pointer
500 * Return the button state that triggered this event.
501 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
502 * this function returns 0.
504 * @note It is an application bug to call this function for events other than
505 * LIBINPUT_EVENT_POINTER_BUTTON.
507 * @return the button state triggering this event
509 enum libinput_pointer_button_state
510 libinput_event_pointer_get_button_state(
511 struct libinput_event_pointer *event);
514 * @ingroup event_pointer
516 * Return the axis that triggered this event.
517 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
518 * this function returns 0.
520 * @note It is an application bug to call this function for events other than
521 * LIBINPUT_EVENT_POINTER_AXIS.
523 * @return the axis triggering this event
525 enum libinput_pointer_axis
526 libinput_event_pointer_get_axis(
527 struct libinput_event_pointer *event);
530 * @ingroup event_pointer
532 * Return the axis value of the given axis. The interpretation of the value
533 * is dependent on the axis. For the two scrolling axes
534 * LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL and
535 * LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL, the value of the event is in
536 * relative scroll units, with the positive direction being down or right,
537 * respectively. The dimension of a scroll unit is equal to one unit of
538 * motion in the respective axis, where applicable (e.g. touchpad two-finger
541 * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
542 * this function returns 0.
544 * @note It is an application bug to call this function for events other than
545 * LIBINPUT_EVENT_POINTER_AXIS.
547 * @return the axis value of this event
550 libinput_event_pointer_get_axis_value(
551 struct libinput_event_pointer *event);
554 * @defgroup event_touch Touch events
556 * Events from absolute touch devices.
560 * @ingroup event_touch
562 * @return The event time for this event
565 libinput_event_touch_get_time(
566 struct libinput_event_touch *event);
569 * @ingroup event_touch
571 * Get the currently active slot on this device. See the kernel's multitouch
572 * protocol B documentation for more information.
574 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
576 * @return The currently active slot on this multitouch device
579 libinput_event_touch_get_slot(
580 struct libinput_event_touch *event);
583 * @ingroup event_touch
585 * Return the current absolute x coordinate of the touch event.
587 * The coordinate is in a device specific coordinate space; to get the
588 * corresponding output screen coordinate, use
589 * libinput_event_touch_get_x_transformed().
591 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
593 * @param event The libinput touch event
594 * @return the current absolute x coordinate
597 libinput_event_touch_get_x(
598 struct libinput_event_touch *event);
601 * @ingroup event_touch
603 * Return the current absolute y coordinate of the touch event.
605 * The coordinate is in a device specific coordinate space; to get the
606 * corresponding output screen coordinate, use
607 * libinput_event_touch_get_y_transformed().
609 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
611 * @param event The libinput touch event
612 * @return the current absolute y coordinate
615 libinput_event_touch_get_y(
616 struct libinput_event_touch *event);
619 * @ingroup event_touch
621 * Return the current absolute x coordinate of the touch event, transformed to
622 * screen coordinates.
624 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
626 * @param event The libinput touch event
627 * @param width The current output screen width
628 * @return the current absolute x coordinate transformed to a screen coordinate
631 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
635 * @ingroup event_touch
637 * Return the current absolute y coordinate of the touch event, transformed to
638 * screen coordinates.
640 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
642 * @param event The libinput touch event
643 * @param height The current output screen height
644 * @return the current absolute y coordinate transformed to a screen coordinate
647 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
651 * @ingroup event_touch
653 * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
655 * @return the type of touch that occured on the device
657 enum libinput_touch_type
658 libinput_event_touch_get_touch_type(
659 struct libinput_event_touch *event);
662 * @defgroup base Initialization and manipulation of libinput contexts
665 struct libinput_interface {
667 * Open the device at the given path with the flags provided and
670 * @param path The device path to open
671 * @param flags Flags as defined by open(2)
672 * @param user_data The user_data provided in
673 * libinput_udev_create_for_seat()
675 * @return the file descriptor, or a negative errno on failure.
677 int (*open_restricted)(const char *path, int flags, void *user_data);
679 * Close the file descriptor.
681 * @param fd The file descriptor to close
682 * @param user_data The user_data provided in
683 * libinput_udev_create_for_seat()
685 void (*close_restricted)(int fd, void *user_data);
691 * Create a new libinput context from udev, for input devices matching
692 * the given seat ID. New devices or devices removed will appear as events
693 * during libinput_dispatch.
695 * @param interface The callback interface
696 * @param user_data Caller-specific data passed to the various callback
698 * @param udev An already initialized udev context
699 * @param seat_id A seat identifier. This string must not be NULL.
701 * @return An initialized libinput context, ready to handle events or NULL on
705 libinput_udev_create_for_seat(const struct libinput_interface *interface,
708 const char *seat_id);
713 * Create a new libinput context that requires the caller to manually add or
714 * remove devices with libinput_path_add_device() and
715 * libinput_path_remove_device().
717 * The context is fully initialized but will not generate events until at
718 * least one device has been added.
720 * @param interface The callback interface
721 * @param user_data Caller-specific data passed to the various callback
724 * @return An initialized, empty libinput context.
727 libinput_path_create_context(const struct libinput_interface *interface,
733 * Add a device to a libinput context initialized with
734 * libinput_path_create_from_device(). If successful, the device will be
735 * added to the internal list and re-opened on libinput_resume(). The device
736 * can be removed with libinput_path_remove_device().
738 * If the device was successfully initialized, it is returned in the device
739 * argument. The lifetime of the returned device pointer is limited until
740 * the next linput_dispatch(), use libinput_device_ref() to keep a permanent
743 * @param libinput A previously initialized libinput context
744 * @param path Path to an input device
745 * @return The newly initiated device on success, or NULL on failure.
747 * @note It is an application bug to call this function on a libinput
748 * context initialize with libinput_udev_create_for_seat().
750 struct libinput_device *
751 libinput_path_add_device(struct libinput *libinput,
757 * Remove a device from a libinput context initialized with
758 * libinput_path_create_from_device() or added to such a context with
759 * libinput_path_add_device().
761 * Events already processed from this input device are kept in the queue,
762 * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
765 * If no matching device exists, this function does nothing.
767 * @param device A libinput device
769 * @note It is an application bug to call this function on a libinput
770 * context initialize with libinput_udev_create_for_seat().
773 libinput_path_remove_device(struct libinput_device *device);
778 * libinput keeps a single file descriptor for all events. Call into
779 * libinput_dispatch() if any events become available on this fd.
781 * @return the file descriptor used to notify of pending events.
784 libinput_get_fd(struct libinput *libinput);
789 * Main event dispatchment function. Reads events of the file descriptors
790 * and processes them internally. Use libinput_get_event() to retrieve the
793 * Dispatching does not necessarily queue libinput events.
795 * @param libinput A previously initialized libinput context
797 * @return 0 on success, or a negative errno on failure
800 libinput_dispatch(struct libinput *libinput);
805 * Retrieve the next event from libinput's internal event queue.
807 * After handling the retrieved event, the caller must destroy it using
808 * libinput_event_destroy().
810 * @param libinput A previously initialized libinput context
811 * @return The next available event, or NULL if no event is available.
813 struct libinput_event *
814 libinput_get_event(struct libinput *libinput);
819 * Return the type of the next event in the internal queue. This function
820 * does not pop the event off the queue and the next call to
821 * libinput_get_event() returns that event.
823 * @param libinput A previously initialized libinput context
824 * @return The event type of the next available event or LIBINPUT_EVENT_NONE
825 * if no event is availble.
827 enum libinput_event_type
828 libinput_next_event_type(struct libinput *libinput);
833 * @param libinput A previously initialized libinput context
834 * @return the caller-specific data previously assigned in
835 * libinput_create_udev().
838 libinput_get_user_data(struct libinput *libinput);
843 * Resume a suspended libinput context. This re-enables device
844 * monitoring and adds existing devices.
846 * @param libinput A previously initialized libinput context
847 * @see libinput_suspend
849 * @return 0 on success or -1 on failure
852 libinput_resume(struct libinput *libinput);
857 * Suspend monitoring for new devices and close existing devices.
858 * This all but terminates libinput but does keep the context
859 * valid to be resumed with libinput_resume().
861 * @param libinput A previously initialized libinput context
864 libinput_suspend(struct libinput *libinput);
869 * Destroy the libinput context. After this, object references associated with
870 * the destroyed context are invalid and may not be interacted with.
872 * @param libinput A previously initialized libinput context
875 libinput_destroy(struct libinput *libinput);
878 * @defgroup seat Initialization and manipulation of seats
880 * A seat has two identifiers, the physical name and the logical name. The
881 * physical name is summarized as the list of devices a process on the same
882 * physical seat has access to.
884 * The logical seat name is the seat name for a logical group of devices. A
885 * compositor may use that to create additonal seats as independent device
886 * sets. Alternatively, a compositor may limit itself to a single logical
887 * seat, leaving a second compositor to manage devices on the other logical
891 * +---+--------+------------+------------------------+------------+
892 * | | event0 | | | log seat A |
893 * | K +--------+ | +------------+
894 * | e | event1 | phys seat0 | libinput context 1 | |
895 * | r +--------+ | | log seat B |
896 * | n | event2 | | | |
897 * | e +--------+------------+------------------------+------------+
898 * | l | event3 | phys seat1 | libinput context 2 | log seat C |
899 * +---+--------+------------+------------------------+------------+
906 * Increase the refcount of the seat. A seat will be freed whenever the
907 * refcount reaches 0. This may happen during dispatch if the
908 * seat was removed from the system. A caller must ensure to reference
909 * the seat correctly to avoid dangling pointers.
911 * @param seat A previously obtained seat
914 libinput_seat_ref(struct libinput_seat *seat);
919 * Decrease the refcount of the seat. A seat will be freed whenever the
920 * refcount reaches 0. This may happen during dispatch if the
921 * seat was removed from the system. A caller must ensure to reference
922 * the seat correctly to avoid dangling pointers.
924 * @param seat A previously obtained seat
927 libinput_seat_unref(struct libinput_seat *seat);
932 * Set caller-specific data associated with this seat. libinput does
933 * not manage, look at, or modify this data. The caller must ensure the
936 * @param seat A previously obtained seat
937 * @param user_data Caller-specific data pointer
938 * @see libinput_seat_get_user_data
941 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
946 * Get the caller-specific data associated with this seat, if any.
948 * @param seat A previously obtained seat
949 * @return Caller-specific data pointer or NULL if none was set
950 * @see libinput_seat_set_user_data
953 libinput_seat_get_user_data(struct libinput_seat *seat);
958 * Return the physical name of the seat. For libinput contexts created from
959 * udev, this is always the same value as passed into
960 * libinput_udev_create_for_seat() and all seats from that context will have
961 * the same physical name.
963 * The physical name of the seat is one that is usually set by the system or
964 * lower levels of the stack. In most cases, this is the base filter for
965 * devices - devices assigned to seats outside the current seat will not
966 * be available to the caller.
968 * @param seat A previously obtained seat
969 * @return the physical name of this seat
972 libinput_seat_get_physical_name(struct libinput_seat *seat);
977 * Return the logical name of the seat. This is an identifier to group sets
978 * of devices within the compositor.
980 * @param seat A previously obtained seat
981 * @return the logical name of this seat
984 libinput_seat_get_logical_name(struct libinput_seat *seat);
987 * @defgroup device Initialization and manipulation of input devices
993 * Increase the refcount of the input device. An input device will be freed
994 * whenever the refcount reaches 0. This may happen during dispatch if the
995 * device was removed from the system. A caller must ensure to reference
996 * the device correctly to avoid dangling pointers.
998 * @param device A previously obtained device
1001 libinput_device_ref(struct libinput_device *device);
1006 * Decrease the refcount of the input device. An input device will be freed
1007 * whenever the refcount reaches 0. This may happen during dispatch if the
1008 * device was removed from the system. A caller must ensure to reference
1009 * the device correctly to avoid dangling pointers.
1011 * @param device A previously obtained device
1014 libinput_device_unref(struct libinput_device *device);
1019 * Set caller-specific data associated with this input device. libinput does
1020 * not manage, look at, or modify this data. The caller must ensure the
1023 * @param device A previously obtained device
1024 * @param user_data Caller-specific data pointer
1025 * @see libinput_device_get_user_data
1028 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1033 * Get the caller-specific data associated with this input device, if any.
1035 * @param device A previously obtained device
1036 * @return Caller-specific data pointer or NULL if none was set
1037 * @see libinput_device_set_user_data
1040 libinput_device_get_user_data(struct libinput_device *device);
1045 * Get the system name of the device.
1047 * @param device A previously obtained device
1048 * @return System name of the device
1051 libinput_device_get_sysname(struct libinput_device *device);
1056 * A device may be mapped to a single output, or all available outputs. If a
1057 * device is mapped to a single output only, a relative device may not move
1058 * beyond the boundaries of this output. An absolute device has its input
1059 * coordinates mapped to the extents of this output.
1061 * @return the name of the output this device is mapped to, or NULL if no
1065 libinput_device_get_output_name(struct libinput_device *device);
1070 * Get the seat associated with this input device.
1072 * A seat can be uniquely identified by the physical and logical seat name.
1073 * There will ever be only one seat instance with a given physical and logical
1074 * seat name pair at any given time, but if no external reference is kept, it
1075 * may be destroyed if no device belonging to it is left.
1077 * @param device A previously obtained device
1078 * @return The seat this input device belongs to
1080 struct libinput_seat *
1081 libinput_device_get_seat(struct libinput_device *device);
1086 * Update the LEDs on the device, if any. If the device does not have
1087 * LEDs, or does not have one or more of the LEDs given in the mask, this
1088 * function does nothing.
1090 * @param device A previously obtained device
1091 * @param leds A mask of the LEDs to set, or unset.
1094 libinput_device_led_update(struct libinput_device *device,
1095 enum libinput_led leds);
1100 * Set the bitmask in keys to the bitmask of the keys present on the device
1101 * (see linux/input.h), up to size characters.
1103 * @param device A current input device
1104 * @param keys An array filled with the bitmask for the keys
1105 * @param size Size of the keys array
1108 libinput_device_get_keys(struct libinput_device *device,
1109 char *keys, size_t size);
1114 * Apply the 3x3 transformation matrix to absolute device coordinates. This
1115 * matrix has no effect on relative events.
1117 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1125 libinput_device_calibrate(struct libinput_device *device,
1126 float calibration[6]);
1131 * Check if the given device has the specified capability
1133 * @return 1 if the given device has the capability or 0 if not
1136 libinput_device_has_capability(struct libinput_device *device,
1137 enum libinput_device_capability capability);
1139 #endif /* LIBINPUT_H */