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 * A frame event is set after a set of touchpoints that constitute one
110 * logical set of points at a sampling point.
112 enum libinput_touch_type {
113 LIBINPUT_TOUCH_TYPE_DOWN = 0,
114 LIBINPUT_TOUCH_TYPE_UP = 1,
115 LIBINPUT_TOUCH_TYPE_MOTION = 2,
116 LIBINPUT_TOUCH_TYPE_FRAME = 3,
117 LIBINPUT_TOUCH_TYPE_CANCEL = 4
123 * Event type for events returned by libinput_get_event().
125 enum libinput_event_type {
126 LIBINPUT_EVENT_NONE = 0,
127 LIBINPUT_EVENT_ADDED_DEVICE,
128 LIBINPUT_EVENT_REMOVED_DEVICE,
130 LIBINPUT_EVENT_KEYBOARD_KEY = 300,
132 LIBINPUT_EVENT_POINTER_MOTION = 400,
133 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
134 LIBINPUT_EVENT_POINTER_BUTTON,
135 LIBINPUT_EVENT_POINTER_AXIS,
137 LIBINPUT_EVENT_TOUCH_TOUCH = 500
141 struct libinput_device;
142 struct libinput_seat;
144 union libinput_event_target {
145 struct libinput *libinput;
146 struct libinput_seat *seat;
147 struct libinput_device *device;
150 struct libinput_event;
151 struct libinput_event_added_device;
152 struct libinput_event_removed_device;
153 struct libinput_event_keyboard_key;
154 struct libinput_event_pointer_motion;
155 struct libinput_event_pointer_motion_absolute;
156 struct libinput_event_pointer_button;
157 struct libinput_event_pointer_axis;
158 struct libinput_event_touch_touch;
161 * @defgroup fixed_point Fixed point utilities
165 * @ingroup fixed_point
167 * Convert li_fixed_t to a double
169 * @param f fixed point number
170 * @return Converted double
173 li_fixed_to_double (li_fixed_t f)
180 u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f;
182 return u.d - (3LL << 43);
186 * @ingroup fixed_point
188 * Convert li_fixed_t to a int. The fraction part is discarded.
190 * @param f fixed point number
191 * @return Converted int
194 li_fixed_to_int(li_fixed_t f)
200 * @defgroup event Acessing and destruction of events
208 * @param event An event retrieved by libinput_get_event().
211 libinput_event_destroy(struct libinput_event *event);
216 * Get the type of the event.
218 * @param event An event retrieved by libinput_get_event().
220 enum libinput_event_type
221 libinput_event_get_type(struct libinput_event *event);
226 * Get get the target union of the event.
228 * The valid union member depends on the event type. For global events not
229 * related to some seat or device, the target is a libinput struct pointer.
230 * For events associated with a seat, the target is a libinput_seat pointer
231 * and for events associated with a device, the target is a libinput_device
234 * @param event An event retrieved by libinput_get_event().
236 union libinput_event_target
237 libinput_event_get_target(struct libinput_event *event);
242 * Get the libinput context from the event.
244 * @param event The libinput event
245 * @return The libinput context for this event.
248 libinput_event_get_context(struct libinput_event *event);
251 * @defgroup event_added_device Added device event
254 struct libinput_device *
255 libinput_event_added_device_get_device(
256 struct libinput_event_added_device *event);
259 * @defgroup event_removed_device Removed device event
262 struct libinput_device *
263 libinput_event_removed_device_get_device(
264 struct libinput_event_removed_device *event);
267 * @defgroup event_keyboard_key Keyboard key event
271 libinput_event_keyboard_key_get_time(
272 struct libinput_event_keyboard_key *event);
275 libinput_event_keyboard_key_get_key(
276 struct libinput_event_keyboard_key *event);
278 enum libinput_keyboard_key_state
279 libinput_event_keyboard_key_get_state(
280 struct libinput_event_keyboard_key *event);
283 * @defgroup event_pointer_motion Pointer motion event
287 libinput_event_pointer_motion_get_time(
288 struct libinput_event_pointer_motion *event);
291 libinput_event_pointer_motion_get_dx(
292 struct libinput_event_pointer_motion *event);
295 libinput_event_pointer_motion_get_dy(
296 struct libinput_event_pointer_motion *event);
299 * @defgroup event_pointer_motion_absolute Absolute pointer motion event
303 libinput_event_pointer_motion_absolute_get_time(
304 struct libinput_event_pointer_motion_absolute *event);
307 libinput_event_pointer_motion_absolute_get_x(
308 struct libinput_event_pointer_motion_absolute *event);
311 libinput_event_pointer_motion_absolute_get_y(
312 struct libinput_event_pointer_motion_absolute *event);
315 * @defgroup event_pointer_button Pointer button event
319 libinput_event_pointer_button_get_time(
320 struct libinput_event_pointer_button *event);
323 libinput_event_pointer_button_get_button(
324 struct libinput_event_pointer_button *event);
326 enum libinput_pointer_button_state
327 libinput_event_pointer_button_get_state(
328 struct libinput_event_pointer_button *event);
331 * @defgroup event_pointer_axis Pointer axis event
335 libinput_event_pointer_axis_get_time(
336 struct libinput_event_pointer_axis *event);
338 enum libinput_pointer_axis
339 libinput_event_pointer_axis_get_axis(
340 struct libinput_event_pointer_axis *event);
343 libinput_event_pointer_axis_get_value(
344 struct libinput_event_pointer_axis *event);
347 * @defgroup event_pointer_button Pointer button event
351 libinput_event_touch_touch_get_time(
352 struct libinput_event_touch_touch *event);
355 libinput_event_touch_touch_get_slot(
356 struct libinput_event_touch_touch *event);
359 libinput_event_touch_touch_get_x(
360 struct libinput_event_touch_touch *event);
363 libinput_event_touch_touch_get_y(
364 struct libinput_event_touch_touch *event);
366 enum libinput_touch_type
367 libinput_event_touch_touch_get_touch_type(
368 struct libinput_event_touch_touch *event);
371 * @defgroup base Initialization and manipulation of libinput contexts
374 struct libinput_interface {
376 * Open the device at the given path with the flags provided and
379 * @param path The device path to open
380 * @param flags Flags as defined by open(2)
381 * @param user_data The user_data provided in
382 * libinput_create_from_udev()
384 * @return the file descriptor, or a negative errno on failure.
386 int (*open_restricted)(const char *path, int flags, void *user_data);
388 * Close the file descriptor.
390 * @param fd The file descriptor to close
391 * @param user_data The user_data provided in
392 * libinput_create_from_udev()
394 void (*close_restricted)(int fd, void *user_data);
396 void (*get_current_screen_dimensions)(struct libinput_device *device,
405 * Create a new libinput context from udev, for input devices matching
406 * the given seat ID. New devices or devices removed will appear as events
407 * during libinput_dispatch.
409 * @param interface The callback interface
410 * @param user_data Caller-specific data passed to the various callback
412 * @param udev An already initialized udev context
413 * @param seat_id A seat identifier. This string must not be NULL.
415 * @return An initialized libinput context, ready to handle events or NULL on
419 libinput_create_from_udev(const struct libinput_interface *interface,
422 const char *seat_id);
426 * Create a new libinput context from the given path. This context
427 * represents one single device only, it will not respond to new devices
428 * being added and reading from the device after it was removed will fail.
430 * @param interface The callback interface
431 * @param user_data Caller-specific data passed to the various callback
433 * @param path Path to an input device
435 * @return An initialized libinput context, ready to handle events or NULL on
439 libinput_create_from_path(const struct libinput_interface *interface,
446 * libinput keeps a single file descriptor for all events. Call into
447 * libinput_dispatch() if any events become available on this fd.
449 * @return the file descriptor used to notify of pending events.
452 libinput_get_fd(struct libinput *libinput);
457 * Main event dispatchment function. Reads events of the file descriptors
458 * and processes them internally. Use libinput_get_event() to retrieve the
461 * Dispatching does not necessarily queue libinput events.
463 * @param libinput A previously initialized libinput context
465 * @return 0 on success, or a negative errno on failure
468 libinput_dispatch(struct libinput *libinput);
473 * Retrieve the next event from libinput's internal event queue.
475 * After handling the retrieved event, the caller must destroy it using
476 * libinput_event_destroy().
478 * @param libinput A previously initialized libinput context
479 * @return The next available event, or NULL if no event is available.
481 struct libinput_event *
482 libinput_get_event(struct libinput *libinput);
487 * Return the type of the next event in the internal queue. This function
488 * does not pop the event off the queue and the next call to
489 * libinput_get_event() returns that event.
491 * @param libinput A previously initialized libinput context
492 * @return The event type of the next available event or LIBINPUT_EVENT_NONE
493 * if no event is availble.
495 enum libinput_event_type
496 libinput_next_event_type(struct libinput *libinput);
501 * @param libinput A previously initialized libinput context
502 * @return the caller-specific data previously assigned in
503 * libinput_create_udev().
506 libinput_get_user_data(struct libinput *libinput);
511 * Resume a suspended libinput context. This re-enables device
512 * monitoring and adds existing devices.
514 * @param libinput A previously initialized libinput context
515 * @see libinput_suspend
517 * @return 0 on success or -1 on failure
520 libinput_resume(struct libinput *libinput);
525 * Suspend monitoring for new devices and close existing devices.
526 * This all but terminates libinput but does keep the context
527 * valid to be resumed with libinput_resume().
529 * @param libinput A previously initialized libinput context
532 libinput_suspend(struct libinput *libinput);
537 * Destroy the libinput context. After this, object references associated with
538 * the destroyed context are invalid and may not be interacted with.
540 * @param libinput A previously initialized libinput context
543 libinput_destroy(struct libinput *libinput);
546 * @defgroup seat Initialization and manipulation of seats
548 * A seat has two identifiers, the physical name and the logical name. The
549 * physical name is summarized as the list of devices a process on the same
550 * physical seat has access to.
552 * The logical seat name is the seat name for a logical group of devices. A
553 * compositor may use that to create additonal seats as independent device
554 * sets. Alternatively, a compositor may limit itself to a single logical
555 * seat, leaving a second compositor to manage devices on the other logical
559 * +---+--------+------------+------------------------+------------+
560 * | | event0 | | | log seat A |
561 * | K +--------+ | +------------+
562 * | e | event1 | phys seat0 | libinput context 1 | |
563 * | r +--------+ | | log seat B |
564 * | n | event2 | | | |
565 * | e +--------+------------+------------------------+------------+
566 * | l | event3 | phys seat1 | libinput context 2 | log seat C |
567 * +---+--------+------------+------------------------+------------+
574 * Increase the refcount of the seat. A seat will be freed whenever the
575 * refcount reaches 0. This may happen during dispatch if the
576 * seat was removed from the system. A caller must ensure to reference
577 * the seat correctly to avoid dangling pointers.
579 * @param seat A previously obtained seat
582 libinput_seat_ref(struct libinput_seat *seat);
587 * Decrease the refcount of the seat. A seat will be freed whenever the
588 * refcount reaches 0. This may happen during dispatch if the
589 * seat was removed from the system. A caller must ensure to reference
590 * the seat correctly to avoid dangling pointers.
592 * @param seat A previously obtained seat
595 libinput_seat_unref(struct libinput_seat *seat);
600 * Set caller-specific data associated with this seat. libinput does
601 * not manage, look at, or modify this data. The caller must ensure the
604 * @param seat A previously obtained seat
605 * @param user_data Caller-specific data pointer
606 * @see libinput_seat_get_user_data
609 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
614 * Get the caller-specific data associated with this seat, if any.
616 * @param seat A previously obtained seat
617 * @return Caller-specific data pointer or NULL if none was set
618 * @see libinput_seat_set_user_data
621 libinput_seat_get_user_data(struct libinput_seat *seat);
626 * Return the physical name of the seat. For libinput contexts created from
627 * udev, this is always the same value as passed into
628 * libinput_create_from_udev() and all seats from that context will have the
629 * same physical name.
631 * The physical name of the seat is one that is usually set by the system or
632 * lower levels of the stack. In most cases, this is the base filter for
633 * devices - devices assigned to seats outside the current seat will not
634 * be available to the caller.
636 * @param seat A previously obtained seat
637 * @return the physical name of this seat
640 libinput_seat_get_physical_name(struct libinput_seat *seat);
645 * Return the logical name of the seat. This is an identifier to group sets
646 * of devices within the compositor.
648 * @param seat A previously obtained seat
649 * @return the logical name of this seat
652 libinput_seat_get_logical_name(struct libinput_seat *seat);
655 * @defgroup device Initialization and manipulation of input devices
661 * Increase the refcount of the input device. An input device will be freed
662 * whenever the refcount reaches 0. This may happen during dispatch if the
663 * device was removed from the system. A caller must ensure to reference
664 * the device correctly to avoid dangling pointers.
666 * @param device A previously obtained device
669 libinput_device_ref(struct libinput_device *device);
674 * Decrease the refcount of the input device. An input device will be freed
675 * whenever the refcount reaches 0. This may happen during dispatch if the
676 * device was removed from the system. A caller must ensure to reference
677 * the device correctly to avoid dangling pointers.
679 * @param device A previously obtained device
682 libinput_device_unref(struct libinput_device *device);
687 * Set caller-specific data associated with this input device. libinput does
688 * not manage, look at, or modify this data. The caller must ensure the
691 * @param device A previously obtained device
692 * @param user_data Caller-specific data pointer
693 * @see libinput_device_get_user_data
696 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
701 * Get the caller-specific data associated with this input device, if any.
703 * @param device A previously obtained device
704 * @return Caller-specific data pointer or NULL if none was set
705 * @see libinput_device_set_user_data
708 libinput_device_get_user_data(struct libinput_device *device);
713 * Get the system name of the device.
715 * @param device A previously obtained device
716 * @return System name of the device
719 libinput_device_get_sysname(struct libinput_device *device);
724 * A device may be mapped to a single output, or all available outputs. If a
725 * device is mapped to a single output only, a relative device may not move
726 * beyond the boundaries of this output. An absolute device has its input
727 * coordinates mapped to the extents of this output.
729 * @return the name of the output this device is mapped to, or NULL if no
733 libinput_device_get_output_name(struct libinput_device *device);
738 * Get the seat associated with this input device.
740 * @param device A previously obtained device
741 * @return The seat this input device belongs to
743 struct libinput_seat *
744 libinput_device_get_seat(struct libinput_device *device);
749 * Update the LEDs on the device, if any. If the device does not have
750 * LEDs, or does not have one or more of the LEDs given in the mask, this
751 * function does nothing.
753 * @param device A previously obtained device
754 * @param leds A mask of the LEDs to set, or unset.
757 libinput_device_led_update(struct libinput_device *device,
758 enum libinput_led leds);
763 * Set the bitmask in keys to the bitmask of the keys present on the device
764 * (see linux/input.h), up to size characters.
766 * @param device A current input device
767 * @param keys An array filled with the bitmask for the keys
768 * @param size Size of the keys array
771 libinput_device_get_keys(struct libinput_device *device,
772 char *keys, size_t size);
777 * Apply the 3x3 transformation matrix to absolute device coordinates. This
778 * matrix has no effect on relative events.
780 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
788 libinput_device_calibrate(struct libinput_device *device,
789 float calibration[6]);
794 * Check if the given device has the specified capability
796 * @return 1 if the given device has the capability or 0 if not
799 libinput_device_has_capability(struct libinput_device *device,
800 enum libinput_device_capability capability);
802 #endif /* LIBINPUT_H */