#ifndef LIBINPUT_H
#define LIBINPUT_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
#include <stdlib.h>
#include <stdint.h>
+#include <libudev.h>
+
+#define LIBINPUT_ATTRIBUTE_PRINTF(_format, _args) \
+ __attribute__ ((format (printf, _format, _args)))
+#define LIBINPUT_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated))
+
+/**
+ * @mainpage
+ * libinput is a generic input device handling library. It abstracts
+ * commonly-used concepts such as keyboard, pointer and touchpad handling
+ * behind an API.
+ */
-typedef int32_t li_fixed_t;
+/**
+ * @page tpbuttons Touchpad button behavior
+ *
+ * For touchpad devices without physical buttons, libinput enables an
+ * emulated right button area through either of two methods.
+ *
+ * Software button areas
+ * =====================
+ * On most touchpads, the bottom area of the touchpad is split into a left
+ * and a right-button area. Pressing the touchpad down with a finger in
+ * those areas will generate clicks as shown in the diagram below:
+ *
+ * @code
+ +------------------------+
+ | |
+ | |
+ | LEFT |
+ | |
+ | |
+ +------------------------+
+ | LEFT | RIGHT |
+ +------------------------+
+ * @endcode
+ *
+ * Generally, the touchpad will emulate a right-button click if the finger
+ * was set down in the right button area and did not leave the
+ * right button area before clicking, even if another finger was already
+ * down on the touchpad in another area.
+ * A middle click is generated by clicking the touchpad when one finger is
+ * in the bottom left button area, and one finger is in the botton right
+ * button area.
+ * The exact behavior of the touchpad is implementation-dependent.
+ *
+ * Top software button area
+ * ========================
+ * On selected touchpads, the top area of the touchpad is a separate set of
+ * software buttons split into a left, middle and right button area.
+ * Pressing the touchpad down with a finger in those areas will generate
+ * clicks as shown in the diagram below:
+ *
+ * @code
+ +------------------------+
+ | LEFT | MIDDLE | RIGHT |
+ +------------------------+
+ | |
+ | LEFT |
+ | |
+ +------------------------+
+ | LEFT | RIGHT |
+ +------------------------+
+ * @endcode
+ * This behavior is enabled on the Lenovo *40 series (T440, T540, T240...)
+ * and the Lenovo Helix, Yoga S1 and Carbon X1 2nd.
+ *
+ * Clickfinger
+ * ===========
+ * On Apple touchpads, no button areas are provided. Instead, use a
+ * two-finger click for a right button click, and a three-finger click for a
+ * middle button click.
+ */
+
+/**
+ * Log priority for internal logging messages.
+ */
+enum libinput_log_priority {
+ LIBINPUT_LOG_PRIORITY_DEBUG = 10,
+ LIBINPUT_LOG_PRIORITY_INFO = 20,
+ LIBINPUT_LOG_PRIORITY_ERROR = 30,
+};
+/**
+ * @ingroup device
+ *
+ * Capabilities on a device. A device may have one or more capabilities
+ * at a time, and capabilities may appear or disappear during the
+ * lifetime of the device.
+ */
enum libinput_device_capability {
LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
LIBINPUT_DEVICE_CAP_POINTER = 1,
- LIBINPUT_DEVICE_CAP_TOUCH = 2,
+ LIBINPUT_DEVICE_CAP_TOUCH = 2
};
-enum libinput_keyboard_key_state {
- LIBINPUT_KEYBOARD_KEY_STATE_RELEASED = 0,
- LIBINPUT_KEYBOARD_KEY_STATE_PRESSED = 1,
+/**
+ * @ingroup device
+ *
+ * Logical state of a key. Note that the logical state may not represent
+ * the physical state of the key.
+ */
+enum libinput_key_state {
+ LIBINPUT_KEY_STATE_RELEASED = 0,
+ LIBINPUT_KEY_STATE_PRESSED = 1
};
+/**
+ * @ingroup device
+ *
+ * Mask reflecting LEDs on a device.
+ */
enum libinput_led {
LIBINPUT_LED_NUM_LOCK = (1 << 0),
LIBINPUT_LED_CAPS_LOCK = (1 << 1),
- LIBINPUT_LED_SCROLL_LOCK = (1 << 2),
+ LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
};
-enum libinput_pointer_button_state {
- LIBINPUT_POINTER_BUTTON_STATE_RELEASED = 0,
- LIBINPUT_POINTER_BUTTON_STATE_PRESSED = 1,
+/**
+ * @ingroup device
+ *
+ * Logical state of a physical button. Note that the logical state may not
+ * represent the physical state of the button.
+ */
+enum libinput_button_state {
+ LIBINPUT_BUTTON_STATE_RELEASED = 0,
+ LIBINPUT_BUTTON_STATE_PRESSED = 1
};
-enum libinput_pointer_axis {
- LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = 0,
- LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = 1,
-};
-enum libinput_touch_type {
- LIBINPUT_TOUCH_TYPE_DOWN = 0,
- LIBINPUT_TOUCH_TYPE_UP = 1,
- LIBINPUT_TOUCH_TYPE_MOTION = 2,
- LIBINPUT_TOUCH_TYPE_FRAME = 3,
- LIBINPUT_TOUCH_TYPE_CANCEL = 4,
+/**
+ * @ingroup device
+ *
+ * Axes on a device that are not x or y coordinates.
+ */
+enum libinput_pointer_axis {
+ LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0,
+ LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1,
};
+/**
+ * @ingroup base
+ *
+ * Event type for events returned by libinput_get_event().
+ */
enum libinput_event_type {
- LIBINPUT_EVENT_DEVICE_REGISTER_CAPABILITY = 200,
- LIBINPUT_EVENT_DEVICE_UNREGISTER_CAPABILITY,
+ /**
+ * This is not a real event type, and is only used to tell the user that
+ * no new event is available in the queue. See
+ * libinput_next_event_type().
+ */
+ LIBINPUT_EVENT_NONE = 0,
+
+ /**
+ * Signals that a device has been added to the context. The device will
+ * not be read until the next time the user calls libinput_dispatch()
+ * and data is available.
+ *
+ * This allows setting up initial device configuration before any events
+ * are created.
+ */
+ LIBINPUT_EVENT_DEVICE_ADDED,
+
+ /**
+ * Signals that a device has been removed. No more events from the
+ * associated device will be in the queue or be queued after this event.
+ */
+ LIBINPUT_EVENT_DEVICE_REMOVED,
LIBINPUT_EVENT_KEYBOARD_KEY = 300,
LIBINPUT_EVENT_POINTER_BUTTON,
LIBINPUT_EVENT_POINTER_AXIS,
- LIBINPUT_EVENT_TOUCH_TOUCH = 500,
+ LIBINPUT_EVENT_TOUCH_DOWN = 500,
+ LIBINPUT_EVENT_TOUCH_UP,
+ LIBINPUT_EVENT_TOUCH_MOTION,
+ LIBINPUT_EVENT_TOUCH_CANCEL,
+ /**
+ * Signals the end of a set of touchpoints at one device sample
+ * time. This event has no coordinate information attached.
+ */
+ LIBINPUT_EVENT_TOUCH_FRAME
};
-struct libinput_event {
- enum libinput_event_type type;
- struct libinput_device *device;
-};
+struct libinput;
+struct libinput_device;
+struct libinput_seat;
-struct libinput_event_device_register_capability {
- struct libinput_event base;
- enum libinput_device_capability capability;
-};
+struct libinput_event;
+struct libinput_event_device_notify;
+struct libinput_event_keyboard;
+struct libinput_event_pointer;
-struct libinput_event_device_unregister_capability {
- struct libinput_event base;
- enum libinput_device_capability capability;
-};
+/**
+ * @ingroup event_touch
+ * @struct libinput_event_touch
+ *
+ * Touch event representing a touch down, move or up, as well as a touch
+ * cancel and touch frame events. Valid event types for this event are @ref
+ * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
+ * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
+ * LIBINPUT_EVENT_TOUCH_FRAME.
+ */
+struct libinput_event_touch;
-struct libinput_event_keyboard_key {
- struct libinput_event base;
- uint32_t time;
- uint32_t key;
- enum libinput_keyboard_key_state state;
-};
+/**
+ * @defgroup event Accessing and destruction of events
+ */
-struct libinput_event_pointer_motion {
- struct libinput_event base;
- uint32_t time;
- li_fixed_t dx;
- li_fixed_t dy;
-};
+/**
+ * @ingroup event
+ *
+ * Destroy the event.
+ *
+ * @param event An event retrieved by libinput_get_event().
+ */
+void
+libinput_event_destroy(struct libinput_event *event);
-struct libinput_event_pointer_motion_absolute {
- struct libinput_event base;
- uint32_t time;
- li_fixed_t x;
- li_fixed_t y;
-};
+/**
+ * @ingroup event
+ *
+ * Get the type of the event.
+ *
+ * @param event An event retrieved by libinput_get_event().
+ */
+enum libinput_event_type
+libinput_event_get_type(struct libinput_event *event);
-struct libinput_event_pointer_button {
- struct libinput_event base;
- uint32_t time;
- int32_t button;
- enum libinput_pointer_button_state state;
-};
+/**
+ * @ingroup event
+ *
+ * Get the libinput context from the event.
+ *
+ * @param event The libinput event
+ * @return The libinput context for this event.
+ */
+struct libinput *
+libinput_event_get_context(struct libinput_event *event);
-struct libinput_event_pointer_axis {
- struct libinput_event base;
- uint32_t time;
- enum libinput_pointer_axis axis;
- li_fixed_t value;
-};
+/**
+ * @ingroup event
+ *
+ * Return the device associated with this event, if applicable. For device
+ * added/removed events this is the device added or removed. For all other
+ * device events, this is the device that generated the event.
+ *
+ * This device is not refcounted and its lifetime is that of the event. Use
+ * libinput_device_ref() before using the device outside of this scope.
+ *
+ * @return The device associated with this event
+ */
-struct libinput_event_touch_touch {
- struct libinput_event base;
- uint32_t time;
- int32_t slot;
- li_fixed_t x;
- li_fixed_t y;
- enum libinput_touch_type touch_type;
-};
+struct libinput_device *
+libinput_event_get_device(struct libinput_event *event);
+
+/**
+ * @ingroup event
+ *
+ * Return the pointer event that is this input event. If the event type does
+ * not match the pointer event types, this function returns NULL.
+ *
+ * The inverse of this function is libinput_event_pointer_get_base_event().
+ *
+ * @return A pointer event, or NULL for other events
+ */
+struct libinput_event_pointer *
+libinput_event_get_pointer_event(struct libinput_event *event);
+
+/**
+ * @ingroup event
+ *
+ * Return the keyboard event that is this input event. If the event type does
+ * not match the keyboard event types, this function returns NULL.
+ *
+ * The inverse of this function is libinput_event_keyboard_get_base_event().
+ *
+ * @return A keyboard event, or NULL for other events
+ */
+struct libinput_event_keyboard *
+libinput_event_get_keyboard_event(struct libinput_event *event);
+
+/**
+ * @ingroup event
+ *
+ * Return the touch event that is this input event. If the event type does
+ * not match the touch event types, this function returns NULL.
+ *
+ * The inverse of this function is libinput_event_touch_get_base_event().
+ *
+ * @return A touch event, or NULL for other events
+ */
+struct libinput_event_touch *
+libinput_event_get_touch_event(struct libinput_event *event);
+
+/**
+ * @ingroup event
+ *
+ * Return the device event that is this input event. If the event type does
+ * not match the device event types, this function returns NULL.
+ *
+ * The inverse of this function is
+ * libinput_event_device_notify_get_base_event().
+ *
+ * @return A device event, or NULL for other events
+ */
+struct libinput_event_device_notify *
+libinput_event_get_device_notify_event(struct libinput_event *event);
+
+/**
+ * @ingroup event
+ *
+ * @return The generic libinput_event of this event
+ */
+struct libinput_event *
+libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
+
+/**
+ * @defgroup event_keyboard Keyboard events
+ *
+ * Key events are generated when a key changes its logical state, usually by
+ * being pressed or released.
+ */
+
+/**
+ * @ingroup event_keyboard
+ *
+ * @return The event time for this event
+ */
+uint32_t
+libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
+
+/**
+ * @ingroup event_keyboard
+ *
+ * @return The keycode that triggered this key event
+ */
+uint32_t
+libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
+
+/**
+ * @ingroup event_keyboard
+ *
+ * @return The state change of the key
+ */
+enum libinput_key_state
+libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
+
+
+/**
+ * @ingroup event_keyboard
+ *
+ * @return The generic libinput_event of this event
+ */
+struct libinput_event *
+libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
+
+/**
+ * @ingroup event_keyboard
+ *
+ * For the key of a LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
+ * of keys pressed on all devices on the associated seat after the event was
+ * triggered.
+ *
+ " @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
+ *
+ * @return the seat wide pressed key count for the key of this event
+ */
+uint32_t
+libinput_event_keyboard_get_seat_key_count(
+ struct libinput_event_keyboard *event);
+
+/**
+ * @defgroup event_pointer Pointer events
+ *
+ * Pointer events reflect motion, button and scroll events, as well as
+ * events from other axes.
+ */
+
+/**
+ * @ingroup event_pointer
+ *
+ * @return The event time for this event
+ */
+uint32_t
+libinput_event_pointer_get_time(struct libinput_event_pointer *event);
+
+/**
+ * @ingroup event_pointer
+ *
+ * Return the delta between the last event and the current event. For pointer
+ * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
+ * returns 0.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_MOTION.
+ *
+ * @return the relative x movement since the last event
+ */
+double
+libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
+
+/**
+ * @ingroup event_pointer
+ *
+ * Return the delta between the last event and the current event. For pointer
+ * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
+ * returns 0.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_MOTION.
+ *
+ * @return the relative y movement since the last event
+ */
+double
+libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
+
+/**
+ * @ingroup event_pointer
+ *
+ * Return the current absolute x coordinate of the pointer event, in mm from
+ * the top left corner of the device. To get the corresponding output screen
+ * coordinate, use libinput_event_pointer_get_absolute_x_transformed().
+ *
+ * For pointer events that are not of type
+ * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
+ *
+ * @return the current absolute x coordinate
+ */
+double
+libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
+
+/**
+ * @ingroup event_pointer
+ *
+ * Return the current absolute y coordinate of the pointer event, in mm from
+ * the top left corner of the device. To get the corresponding output screen
+ * coordinate, use libinput_event_pointer_get_absolute_y_transformed().
+ *
+ * For pointer events that are not of type
+ * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
+ *
+ * @return the current absolute y coordinate
+ */
+double
+libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
+
+/**
+ * @ingroup event_pointer
+ *
+ * Return the current absolute x coordinate of the pointer event, transformed to
+ * screen coordinates.
+ *
+ * For pointer events that are not of type
+ * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
+ * undefined.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
+ *
+ * @param event The libinput pointer event
+ * @param width The current output screen width
+ * @return the current absolute x coordinate transformed to a screen coordinate
+ */
+double
+libinput_event_pointer_get_absolute_x_transformed(
+ struct libinput_event_pointer *event,
+ uint32_t width);
+
+/**
+ * @ingroup event_pointer
+ *
+ * Return the current absolute y coordinate of the pointer event, transformed to
+ * screen coordinates.
+ *
+ * For pointer events that are not of type
+ * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
+ * undefined.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
+ *
+ * @param event The libinput pointer event
+ * @param height The current output screen height
+ * @return the current absolute y coordinate transformed to a screen coordinate
+ */
+double
+libinput_event_pointer_get_absolute_y_transformed(
+ struct libinput_event_pointer *event,
+ uint32_t height);
-struct libinput_fd_handle;
+/**
+ * @ingroup event_pointer
+ *
+ * Return the button that triggered this event.
+ * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
+ * this function returns 0.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_BUTTON.
+ *
+ * @return the button triggering this event
+ */
+uint32_t
+libinput_event_pointer_get_button(struct libinput_event_pointer *event);
-typedef void (*libinput_fd_callback)(int fd, void *data);
+/**
+ * @ingroup event_pointer
+ *
+ * Return the button state that triggered this event.
+ * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
+ * this function returns 0.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_BUTTON.
+ *
+ * @return the button state triggering this event
+ */
+enum libinput_button_state
+libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
-struct libinput_device_interface {
- void (*get_current_screen_dimensions)(int *width,
- int *height,
- void *data);
+/**
+ * @ingroup event_pointer
+ *
+ * For the button of a LIBINPUT_EVENT_POINTER_BUTTON event, return the total
+ * number of buttons pressed on all devices on the associated seat after the
+ * the event was triggered.
+ *
+ " @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function returns 0.
+ *
+ * @return the seat wide pressed button count for the key of this event
+ */
+uint32_t
+libinput_event_pointer_get_seat_button_count(
+ struct libinput_event_pointer *event);
+
+/**
+ * @ingroup event_pointer
+ *
+ * Return the axis that triggered this event.
+ * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
+ * this function returns 0.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_AXIS.
+ *
+ * @return the axis triggering this event
+ */
+enum libinput_pointer_axis
+libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
+
+/**
+ * @ingroup event_pointer
+ *
+ * Return the axis value of the given axis. The interpretation of the value
+ * is dependent on the axis. For the two scrolling axes
+ * LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
+ * LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in
+ * relative scroll units, with the positive direction being down or right,
+ * respectively. The dimension of a scroll unit is equal to one unit of
+ * motion in the respective axis, where applicable (e.g. touchpad two-finger
+ * scrolling).
+ *
+ * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
+ * this function returns 0.
+ *
+ * @note It is an application bug to call this function for events other than
+ * LIBINPUT_EVENT_POINTER_AXIS.
+ *
+ * @return the axis value of this event
+ */
+double
+libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
+
+/**
+ * @ingroup event_pointer
+ *
+ * @return The generic libinput_event of this event
+ */
+struct libinput_event *
+libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
+
+
+/**
+ * @defgroup event_touch Touch events
+ *
+ * Events from absolute touch devices.
+ */
+
+/**
+ * @ingroup event_touch
+ *
+ * @return The event time for this event
+ */
+uint32_t
+libinput_event_touch_get_time(struct libinput_event_touch *event);
+
+/**
+ * @ingroup event_touch
+ *
+ * Get the slot of this touch event. See the kernel's multitouch
+ * protocol B documentation for more information.
+ *
+ * If the touch event has no assigned slot, for example if it is from a
+ * single touch device, this function returns -1.
+ *
+ * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
+ * LIBINPUT_EVENT_TOUCH_FRAME.
+ *
+ * @return The slot of this touch event
+ */
+int32_t
+libinput_event_touch_get_slot(struct libinput_event_touch *event);
+
+/**
+ * @ingroup event_touch
+ *
+ * Get the seat slot of the touch event. A seat slot is a non-negative seat
+ * wide unique identifier of an active touch point.
+ *
+ * Events from single touch devices will be represented as one individual
+ * touch point per device.
+ *
+ * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
+ * LIBINPUT_EVENT_TOUCH_FRAME.
+ *
+ * @return The seat slot of the touch event
+ */
+int32_t
+libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
+
+/**
+ * @ingroup event_touch
+ *
+ * Return the current absolute x coordinate of the touch event, in mm from
+ * the top left corner of the device. To get the corresponding output screen
+ * coordinate, use libinput_event_touch_get_x_transformed().
+ *
+ * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
+ * LIBINPUT_EVENT_TOUCH_MOTION.
+ *
+ * @param event The libinput touch event
+ * @return the current absolute x coordinate
+ */
+double
+libinput_event_touch_get_x(struct libinput_event_touch *event);
+
+/**
+ * @ingroup event_touch
+ *
+ * Return the current absolute y coordinate of the touch event, in mm from
+ * the top left corner of the device. To get the corresponding output screen
+ * coordinate, use libinput_event_touch_get_y_transformed().
+ *
+ * For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
+ *
+ * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
+ * LIBINPUT_EVENT_TOUCH_MOTION.
+ *
+ * @param event The libinput touch event
+ * @return the current absolute y coordinate
+ */
+double
+libinput_event_touch_get_y(struct libinput_event_touch *event);
+
+/**
+ * @ingroup event_touch
+ *
+ * Return the current absolute x coordinate of the touch event, transformed to
+ * screen coordinates.
+ *
+ * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
+ * LIBINPUT_EVENT_TOUCH_MOTION.
+ *
+ * @param event The libinput touch event
+ * @param width The current output screen width
+ * @return the current absolute x coordinate transformed to a screen coordinate
+ */
+double
+libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
+ uint32_t width);
+
+/**
+ * @ingroup event_touch
+ *
+ * Return the current absolute y coordinate of the touch event, transformed to
+ * screen coordinates.
+ *
+ * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
+ * LIBINPUT_EVENT_TOUCH_MOTION.
+ *
+ * @param event The libinput touch event
+ * @param height The current output screen height
+ * @return the current absolute y coordinate transformed to a screen coordinate
+ */
+double
+libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
+ uint32_t height);
+
+/**
+ * @ingroup event_touch
+ *
+ * @return The generic libinput_event of this event
+ */
+struct libinput_event *
+libinput_event_touch_get_base_event(struct libinput_event_touch *event);
+
+/**
+ * @defgroup base Initialization and manipulation of libinput contexts
+ */
+
+struct libinput_interface {
+ /**
+ * Open the device at the given path with the flags provided and
+ * return the fd.
+ *
+ * @param path The device path to open
+ * @param flags Flags as defined by open(2)
+ * @param user_data The user_data provided in
+ * libinput_udev_create_context()
+ *
+ * @return the file descriptor, or a negative errno on failure.
+ */
+ int (*open_restricted)(const char *path, int flags, void *user_data);
+ /**
+ * Close the file descriptor.
+ *
+ * @param fd The file descriptor to close
+ * @param user_data The user_data provided in
+ * libinput_udev_create_context()
+ */
+ void (*close_restricted)(int fd, void *user_data);
};
-struct libinput;
-struct libinput_device;
+/**
+ * @ingroup base
+ *
+ * Create a new libinput context from udev. This context is inactive until
+ * assigned a seat ID with libinput_udev_assign_seat().
+ *
+ * @param interface The callback interface
+ * @param user_data Caller-specific data passed to the various callback
+ * interfaces.
+ * @param udev An already initialized udev context
+ *
+ * @return An initialized, but inactive libinput context or NULL on error
+ */
+struct libinput *
+libinput_udev_create_context(const struct libinput_interface *interface,
+ void *user_data,
+ struct udev *udev);
+/**
+ * @ingroup base
+ *
+ * Assign a seat to this libinput context. New devices or the removal of
+ * existing devices will appear as events during libinput_dispatch().
+ *
+ * libinput_udev_assign_seat() succeeds even if no input devices are currently
+ * available on this seat, or if devices are available but fail to open in
+ * @ref libinput_interface::open_restricted. Devices that do not have the
+ * minimum capabilities to be recognized as pointer, keyboard or touch
+ * device are ignored. Such devices and those that failed to open
+ * ignored until the next call to libinput_resume().
+ *
+ * This function may only be called once per context.
+ *
+ * @param libinput A libinput context initialized with
+ * libinput_udev_create_context()
+ * @param seat_id A seat identifier. This string must not be NULL.
+ *
+ * @return 0 on success or -1 on failure.
+ */
+int
+libinput_udev_assign_seat(struct libinput *libinput,
+ const char *seat_id);
+
+/**
+ * @ingroup base
+ *
+ * Create a new libinput context that requires the caller to manually add or
+ * remove devices with libinput_path_add_device() and
+ * libinput_path_remove_device().
+ *
+ * The context is fully initialized but will not generate events until at
+ * least one device has been added.
+ *
+ * The reference count of the context is initialized to 1. See @ref
+ * libinput_unref.
+ *
+ * @param interface The callback interface
+ * @param user_data Caller-specific data passed to the various callback
+ * interfaces.
+ *
+ * @return An initialized, empty libinput context.
+ */
struct libinput *
-libinput_create(void);
+libinput_path_create_context(const struct libinput_interface *interface,
+ void *user_data);
+
+/**
+ * @ingroup base
+ *
+ * Add a device to a libinput context initialized with
+ * libinput_path_create_context(). If successful, the device will be
+ * added to the internal list and re-opened on libinput_resume(). The device
+ * can be removed with libinput_path_remove_device().
+ *
+ * If the device was successfully initialized, it is returned in the device
+ * argument. The lifetime of the returned device pointer is limited until
+ * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent
+ * reference.
+ *
+ * @param libinput A previously initialized libinput context
+ * @param path Path to an input device
+ * @return The newly initiated device on success, or NULL on failure.
+ *
+ * @note It is an application bug to call this function on a libinput
+ * context initialized with libinput_udev_create_context().
+ */
+struct libinput_device *
+libinput_path_add_device(struct libinput *libinput,
+ const char *path);
+
+/**
+ * @ingroup base
+ *
+ * Remove a device from a libinput context initialized with
+ * libinput_path_create_context() or added to such a context with
+ * libinput_path_add_device().
+ *
+ * Events already processed from this input device are kept in the queue,
+ * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
+ * device.
+ *
+ * If no matching device exists, this function does nothing.
+ *
+ * @param device A libinput device
+ *
+ * @note It is an application bug to call this function on a libinput
+ * context initialized with libinput_udev_create_context().
+ */
+void
+libinput_path_remove_device(struct libinput_device *device);
+/**
+ * @ingroup base
+ *
+ * libinput keeps a single file descriptor for all events. Call into
+ * libinput_dispatch() if any events become available on this fd.
+ *
+ * @return the file descriptor used to notify of pending events.
+ */
int
libinput_get_fd(struct libinput *libinput);
+/**
+ * @ingroup base
+ *
+ * Main event dispatchment function. Reads events of the file descriptors
+ * and processes them internally. Use libinput_get_event() to retrieve the
+ * events.
+ *
+ * Dispatching does not necessarily queue libinput events.
+ *
+ * @param libinput A previously initialized libinput context
+ *
+ * @return 0 on success, or a negative errno on failure
+ */
int
libinput_dispatch(struct libinput *libinput);
+/**
+ * @ingroup base
+ *
+ * Retrieve the next event from libinput's internal event queue.
+ *
+ * After handling the retrieved event, the caller must destroy it using
+ * libinput_event_destroy().
+ *
+ * @param libinput A previously initialized libinput context
+ * @return The next available event, or NULL if no event is available.
+ */
struct libinput_event *
libinput_get_event(struct libinput *libinput);
+/**
+ * @ingroup base
+ *
+ * Return the type of the next event in the internal queue. This function
+ * does not pop the event off the queue and the next call to
+ * libinput_get_event() returns that event.
+ *
+ * @param libinput A previously initialized libinput context
+ * @return The event type of the next available event or LIBINPUT_EVENT_NONE
+ * if no event is availble.
+ */
+enum libinput_event_type
+libinput_next_event_type(struct libinput *libinput);
+
+/**
+ * @ingroup base
+ *
+ * @param libinput A previously initialized libinput context
+ * @return the caller-specific data previously assigned in
+ * libinput_create_udev().
+ */
+void *
+libinput_get_user_data(struct libinput *libinput);
+
+/**
+ * @ingroup base
+ *
+ * Resume a suspended libinput context. This re-enables device
+ * monitoring and adds existing devices.
+ *
+ * @param libinput A previously initialized libinput context
+ * @see libinput_suspend
+ *
+ * @return 0 on success or -1 on failure
+ */
+int
+libinput_resume(struct libinput *libinput);
+
+/**
+ * @ingroup base
+ *
+ * Suspend monitoring for new devices and close existing devices.
+ * This all but terminates libinput but does keep the context
+ * valid to be resumed with libinput_resume().
+ *
+ * @param libinput A previously initialized libinput context
+ */
void
-libinput_destroy(struct libinput *libinput);
+libinput_suspend(struct libinput *libinput);
-struct libinput_device *
-libinput_device_create_evdev(struct libinput *libinput,
- const char *devnode,
- int fd,
- const struct libinput_device_interface *interface,
- void *user_data);
+/**
+ * @ingroup base
+ *
+ * Add a reference to the context. A context is destroyed whenever the
+ * reference count reaches 0. See @ref libinput_unref.
+ *
+ * @param libinput A previously initialized valid libinput context
+ * @return The passed libinput context
+ */
+struct libinput *
+libinput_ref(struct libinput *libinput);
+/**
+ * @ingroup base
+ *
+ * Dereference the libinput context. After this, the context may have been
+ * destroyed, if the last reference was dereferenced. If so, the context is
+ * invalid and may not be interacted with.
+ *
+ * @param libinput A previously initialized libinput context
+ * @return NULL if context was destroyed otherwise the passed context
+ */
+struct libinput *
+libinput_unref(struct libinput *libinput);
+
+/**
+ * @ingroup base
+ *
+ * Set the global log priority. Messages with priorities equal to or
+ * higher than the argument will be printed to the current log handler.
+ *
+ * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
+ *
+ * @param libinput A previously initialized libinput context
+ * @param priority The minimum priority of log messages to print.
+ *
+ * @see libinput_log_set_handler
+ * @see libinput_log_get_priority
+ */
void
-libinput_device_terminate(struct libinput_device *device);
+libinput_log_set_priority(struct libinput *libinput,
+ enum libinput_log_priority priority);
+
+/**
+ * @ingroup base
+ *
+ * Get the global log priority. Messages with priorities equal to or
+ * higher than the argument will be printed to the current log handler.
+ *
+ * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
+ *
+ * @param libinput A previously initialized libinput context
+ * @return The minimum priority of log messages to print.
+ *
+ * @see libinput_log_set_handler
+ * @see libinput_log_set_priority
+ */
+enum libinput_log_priority
+libinput_log_get_priority(const struct libinput *libinput);
+/**
+ * @ingroup base
+ *
+ * Log handler type for custom logging.
+ *
+ * @param libinput The libinput context
+ * @param priority The priority of the current message
+ * @param format Message format in printf-style
+ * @param args Message arguments
+ *
+ * @see libinput_set_log_priority
+ * @see libinput_log_set_handler
+ */
+typedef void (*libinput_log_handler)(struct libinput *libinput,
+ enum libinput_log_priority priority,
+ const char *format, va_list args)
+ LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
+
+/**
+ * @ingroup base
+ *
+ * Set the global log handler. Messages with priorities equal to or higher
+ * than the current log priority will be passed to the given
+ * log handler.
+ *
+ * The default log handler prints to stderr.
+ *
+ * @param libinput A previously initialized libinput context
+ * @param log_handler The log handler for library messages.
+ * @param user_data Caller-specific data pointer, passed into the log
+ * handler.
+ *
+ * @see libinput_log_set_handler
+ */
+void
+libinput_log_set_handler(struct libinput *libinput,
+ libinput_log_handler log_handler);
+
+/**
+ * @defgroup seat Initialization and manipulation of seats
+ *
+ * A seat has two identifiers, the physical name and the logical name. The
+ * physical name is summarized as the list of devices a process on the same
+ * physical seat has access to.
+ *
+ * The logical seat name is the seat name for a logical group of devices. A
+ * compositor may use that to create additonal seats as independent device
+ * sets. Alternatively, a compositor may limit itself to a single logical
+ * seat, leaving a second compositor to manage devices on the other logical
+ * seats.
+ *
+ * @code
+ * +---+--------+------------+------------------------+------------+
+ * | | event0 | | | log seat A |
+ * | K +--------+ | +------------+
+ * | e | event1 | phys seat0 | libinput context 1 | |
+ * | r +--------+ | | log seat B |
+ * | n | event2 | | | |
+ * | e +--------+------------+------------------------+------------+
+ * | l | event3 | phys seat1 | libinput context 2 | log seat C |
+ * +---+--------+------------+------------------------+------------+
+ * @endcode
+ */
+
+/**
+ * @ingroup seat
+ *
+ * Increase the refcount of the seat. A seat will be freed whenever the
+ * refcount reaches 0. This may happen during dispatch if the
+ * seat was removed from the system. A caller must ensure to reference
+ * the seat correctly to avoid dangling pointers.
+ *
+ * @param seat A previously obtained seat
+ * @return The passed seat
+ */
+struct libinput_seat *
+libinput_seat_ref(struct libinput_seat *seat);
+
+/**
+ * @ingroup seat
+ *
+ * Decrease the refcount of the seat. A seat will be freed whenever the
+ * refcount reaches 0. This may happen during dispatch if the
+ * seat was removed from the system. A caller must ensure to reference
+ * the seat correctly to avoid dangling pointers.
+ *
+ * @param seat A previously obtained seat
+ * @return NULL if seat was destroyed, otherwise the passed seat
+ */
+struct libinput_seat *
+libinput_seat_unref(struct libinput_seat *seat);
+
+/**
+ * @ingroup seat
+ *
+ * Set caller-specific data associated with this seat. libinput does
+ * not manage, look at, or modify this data. The caller must ensure the
+ * data is valid.
+ *
+ * @param seat A previously obtained seat
+ * @param user_data Caller-specific data pointer
+ * @see libinput_seat_get_user_data
+ */
void
-libinput_device_destroy(struct libinput_device *device);
+libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
+/**
+ * @ingroup seat
+ *
+ * Get the caller-specific data associated with this seat, if any.
+ *
+ * @param seat A previously obtained seat
+ * @return Caller-specific data pointer or NULL if none was set
+ * @see libinput_seat_set_user_data
+ */
+void *
+libinput_seat_get_user_data(struct libinput_seat *seat);
+
+/**
+ * @ingroup seat
+ *
+ * Return the physical name of the seat. For libinput contexts created from
+ * udev, this is always the same value as passed into
+ * libinput_udev_assign_seat() and all seats from that context will have
+ * the same physical name.
+ *
+ * The physical name of the seat is one that is usually set by the system or
+ * lower levels of the stack. In most cases, this is the base filter for
+ * devices - devices assigned to seats outside the current seat will not
+ * be available to the caller.
+ *
+ * @param seat A previously obtained seat
+ * @return the physical name of this seat
+ */
+const char *
+libinput_seat_get_physical_name(struct libinput_seat *seat);
+
+/**
+ * @ingroup seat
+ *
+ * Return the logical name of the seat. This is an identifier to group sets
+ * of devices within the compositor.
+ *
+ * @param seat A previously obtained seat
+ * @return the logical name of this seat
+ */
+const char *
+libinput_seat_get_logical_name(struct libinput_seat *seat);
+
+/**
+ * @defgroup device Initialization and manipulation of input devices
+ */
+
+/**
+ * @ingroup device
+ *
+ * Increase the refcount of the input device. An input device will be freed
+ * whenever the refcount reaches 0. This may happen during dispatch if the
+ * device was removed from the system. A caller must ensure to reference
+ * the device correctly to avoid dangling pointers.
+ *
+ * @param device A previously obtained device
+ * @return The passed device
+ */
+struct libinput_device *
+libinput_device_ref(struct libinput_device *device);
+
+/**
+ * @ingroup device
+ *
+ * Decrease the refcount of the input device. An input device will be freed
+ * whenever the refcount reaches 0. This may happen during dispatch if the
+ * device was removed from the system. A caller must ensure to reference
+ * the device correctly to avoid dangling pointers.
+ *
+ * @param device A previously obtained device
+ * @return NULL if device was destroyed, otherwise the passed device
+ */
+struct libinput_device *
+libinput_device_unref(struct libinput_device *device);
+
+/**
+ * @ingroup device
+ *
+ * Set caller-specific data associated with this input device. libinput does
+ * not manage, look at, or modify this data. The caller must ensure the
+ * data is valid.
+ *
+ * @param device A previously obtained device
+ * @param user_data Caller-specific data pointer
+ * @see libinput_device_get_user_data
+ */
+void
+libinput_device_set_user_data(struct libinput_device *device, void *user_data);
+
+/**
+ * @ingroup device
+ *
+ * Get the caller-specific data associated with this input device, if any.
+ *
+ * @param device A previously obtained device
+ * @return Caller-specific data pointer or NULL if none was set
+ * @see libinput_device_set_user_data
+ */
void *
libinput_device_get_user_data(struct libinput_device *device);
+/**
+ * @ingroup device
+ *
+ * Get the system name of the device.
+ *
+ * To get the descriptive device name, use libinput_device_get_name().
+ *
+ * @param device A previously obtained device
+ * @return System name of the device
+ *
+ */
+const char *
+libinput_device_get_sysname(struct libinput_device *device);
+
+/**
+ * @ingroup device
+ *
+ * The descriptive device name as advertised by the kernel and/or the
+ * hardware itself. To get the sysname for this device, use
+ * libinput_device_get_sysname().
+ *
+ * The lifetime of the returned string is tied to the struct
+ * libinput_device. The string may be the empty string but is never NULL.
+ *
+ * @param device A previously obtained device
+ * @return The device name
+ */
+const char *
+libinput_device_get_name(struct libinput_device *device);
+
+/**
+ * @ingroup device
+ *
+ * Get the product ID for this device.
+ *
+ * @param device A previously obtained device
+ * @return The product ID of this device
+ */
+unsigned int
+libinput_device_get_id_product(struct libinput_device *device);
+
+/**
+ * @ingroup device
+ *
+ * Get the vendor ID for this device.
+ *
+ * @param device A previously obtained device
+ * @return The vendor ID of this device
+ */
+unsigned int
+libinput_device_get_id_vendor(struct libinput_device *device);
+
+/**
+ * @ingroup device
+ *
+ * A device may be mapped to a single output, or all available outputs. If a
+ * device is mapped to a single output only, a relative device may not move
+ * beyond the boundaries of this output. An absolute device has its input
+ * coordinates mapped to the extents of this output.
+ *
+ * @return the name of the output this device is mapped to, or NULL if no
+ * output is set
+ */
+const char *
+libinput_device_get_output_name(struct libinput_device *device);
+
+/**
+ * @ingroup device
+ *
+ * Get the seat associated with this input device.
+ *
+ * A seat can be uniquely identified by the physical and logical seat name.
+ * There will ever be only one seat instance with a given physical and logical
+ * seat name pair at any given time, but if no external reference is kept, it
+ * may be destroyed if no device belonging to it is left.
+ *
+ * @param device A previously obtained device
+ * @return The seat this input device belongs to
+ */
+struct libinput_seat *
+libinput_device_get_seat(struct libinput_device *device);
+
+/**
+ * @ingroup device
+ *
+ * Update the LEDs on the device, if any. If the device does not have
+ * LEDs, or does not have one or more of the LEDs given in the mask, this
+ * function does nothing.
+ *
+ * @param device A previously obtained device
+ * @param leds A mask of the LEDs to set, or unset.
+ */
void
libinput_device_led_update(struct libinput_device *device,
enum libinput_led leds);
+/**
+ * @ingroup device
+ *
+ * Set the bitmask in keys to the bitmask of the keys present on the device
+ * (see linux/input.h), up to size characters.
+ *
+ * @param device A current input device
+ * @param keys An array filled with the bitmask for the keys
+ * @param size Size of the keys array
+ *
+ * @return The number of valid bytes in keys, or a negative errno on failure
+ */
int
libinput_device_get_keys(struct libinput_device *device,
char *keys, size_t size);
+/**
+ * @ingroup device
+ *
+ * Apply the 3x3 transformation matrix to absolute device coordinates. This
+ * matrix has no effect on relative events.
+ *
+ * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
+ * @code
+ * [ a b c ] [ x ]
+ * [ d e f ] * [ y ]
+ * [ 0 0 1 ] [ 1 ]
+ * @endcode
+ */
void
libinput_device_calibrate(struct libinput_device *device,
float calibration[6]);
+/**
+ * @ingroup device
+ *
+ * Check if the given device has the specified capability
+ *
+ * @return 1 if the given device has the capability or 0 if not
+ */
+int
+libinput_device_has_capability(struct libinput_device *device,
+ enum libinput_device_capability capability);
+
+/**
+ * @ingroup device
+ *
+ * Get the physical size of a device in mm, where meaningful. This function
+ * only succeeds on devices with the required data, i.e. tablets, touchpads
+ * and touchscreens.
+ *
+ * If this function returns nonzero, width and height are unmodified.
+ *
+ * @param device The device
+ * @param width Set to the width of the device
+ * @param height Set to the height of the device
+ * @return 0 on success, or nonzero otherwise
+ */
+int
+libinput_device_get_size(struct libinput_device *device,
+ double *width,
+ double *height);
+
+
+/**
+ * @defgroup config Device configuration
+ *
+ * Enable, disable, change and/or check for device-specific features. For
+ * all features, libinput assigns a default based on the hardware
+ * configuration. This default can be obtained with the respective
+ * get_default call.
+ *
+ * Some configuration option may be dependent on or mutually exclusive with
+ * with other options. The behavior in those cases is
+ * implementation-defined, the caller must ensure that the options are set
+ * in the right order.
+ */
+
+/**
+ * @ingroup config
+ *
+ * Status codes returned when applying configuration settings.
+ */
+enum libinput_config_status {
+ LIBINPUT_CONFIG_STATUS_SUCCESS = 0, /**< Config applied successfully */
+ LIBINPUT_CONFIG_STATUS_UNSUPPORTED, /**< Configuration not available on
+ this device */
+ LIBINPUT_CONFIG_STATUS_INVALID, /**< Invalid parameter range */
+};
+
+/**
+ * @ingroup config
+ *
+ * Return a string describing the error.
+ *
+ * @param status The status to translate to a string
+ * @return A human-readable string representing the error or NULL for an
+ * invalid status.
+ */
+const char *
+libinput_config_status_to_str(enum libinput_config_status status);
+
+/**
+ * @ingroup config
+ *
+ * Check if the device supports tap-to-click. See
+ * libinput_device_config_tap_set_enabled() for more information.
+ *
+ * @param device The device to configure
+ * @return The number of fingers that can generate a tap event, or 0 if the
+ * device does not support tapping.
+ *
+ * @see libinput_device_config_tap_set_enabled
+ * @see libinput_device_config_tap_get_enabled
+ * @see libinput_device_config_tap_set_enabled_get_default
+ */
+int
+libinput_device_config_tap_get_finger_count(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Enable or disable tap-to-click on this device, with a default mapping of
+ * 1, 2, 3 finger tap mapping to left, right, middle click, respectively.
+ * Tapping is limited by the number of simultaneous touches
+ * supported by the device, see
+ * libinput_device_config_tap_get_finger_count().
+ *
+ * @param device The device to configure
+ * @param enable Non-zero to enable, zero to disable
+ *
+ * @return A config status code. Disabling tapping on a device that does not
+ * support tapping always succeeds.
+ *
+ * @see libinput_device_config_tap_get_finger_count
+ * @see libinput_device_config_tap_get_enabled
+ * @see libinput_device_config_tap_get_default_enabled
+ */
+enum libinput_config_status
+libinput_device_config_tap_set_enabled(struct libinput_device *device,
+ int enable);
+
+/**
+ * @ingroup config
+ *
+ * Check if tap-to-click is enabled on this device. If the device does not
+ * support tapping, this function always returns 0.
+ *
+ * @param device The device to configure
+ *
+ * @return 1 if enabled, 0 otherwise.
+ *
+ * @see libinput_device_config_tap_get_finger_count
+ * @see libinput_device_config_tap_set_enabled
+ * @see libinput_device_config_tap_get_default_enabled
+ */
+int
+libinput_device_config_tap_get_enabled(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Return the default setting for whether tapping is enabled on this device.
+ *
+ * @param device The device to configure
+ * @return 1 if tapping is enabled by default, or 0 otherwise
+ *
+ * @see libinput_device_config_tap_get_finger_count
+ * @see libinput_device_config_tap_set_enabled
+ * @see libinput_device_config_tap_get_enabled
+ */
+int
+libinput_device_config_tap_get_default_enabled(struct libinput_device *device);
+
+#ifdef __cplusplus
+}
+#endif
#endif /* LIBINPUT_H */
projects / platform / upstream / libinput.git / blobdiff