X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=src%2Flibinput.h;h=7d33f2b20bc53368acec4c5c6d90f78f8e3fd73b;hb=e82728ca2773d297d9103b14edceff1a9c12833e;hp=a29a39c91baa6a3a7366e197da8fd652394a501c;hpb=67455487f80a579faca06850e31851af11de33a0;p=platform%2Fupstream%2Flibinput.git diff --git a/src/libinput.h b/src/libinput.h index a29a39c..7d33f2b 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -23,10 +23,18 @@ #ifndef LIBINPUT_H #define LIBINPUT_H +#ifdef __cplusplus +extern "C" { +#endif + #include #include #include +#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 @@ -35,21 +43,86 @@ */ /** - * libinput 24.8 fixed point real number. + * @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. */ -typedef int32_t li_fixed_t; + +/** + * 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 - * lifteime of the device. + * 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 }; /** @@ -58,9 +131,9 @@ enum libinput_device_capability { * Logical state of a key. Note that the logical state may not represent * the physical state of the key. */ -enum libinput_keyboard_key_state { - LIBINPUT_KEYBOARD_KEY_STATE_RELEASED = 0, - LIBINPUT_KEYBOARD_KEY_STATE_PRESSED = 1, +enum libinput_key_state { + LIBINPUT_KEY_STATE_RELEASED = 0, + LIBINPUT_KEY_STATE_PRESSED = 1 }; /** @@ -71,7 +144,7 @@ enum libinput_keyboard_key_state { 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) }; /** @@ -80,9 +153,9 @@ enum libinput_led { * Logical state of a physical button. Note that the logical state may not * represent the physical state of the button. */ -enum libinput_pointer_button_state { - LIBINPUT_POINTER_BUTTON_STATE_RELEASED = 0, - LIBINPUT_POINTER_BUTTON_STATE_PRESSED = 1, +enum libinput_button_state { + LIBINPUT_BUTTON_STATE_RELEASED = 0, + LIBINPUT_BUTTON_STATE_PRESSED = 1 }; @@ -92,27 +165,8 @@ enum libinput_pointer_button_state { * Axes on a device that are not x or y coordinates. */ enum libinput_pointer_axis { - LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = 0, - LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = 1, -}; - -/** - * @ingroup device - * - * Logical touch state of a touch point. A touch point usually follows the - * sequence down, motion, up, with the number of motion events being zero or - * greater. If a touch point was used for gesture interpretation internally - * and will not generate any further events, the touchpoint is cancelled. - * - * A frame event is set after a set of touchpoints that constitute one - * logical set of points at a sampling point. - */ -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, + LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0, + LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1, }; /** @@ -121,13 +175,28 @@ enum libinput_touch_type { * Event type for events returned by libinput_get_event(). */ enum libinput_event_type { - LIBINPUT_EVENT_ADDED_SEAT = 0, - LIBINPUT_EVENT_REMOVED_SEAT, - LIBINPUT_EVENT_ADDED_DEVICE, - LIBINPUT_EVENT_REMOVED_DEVICE, - - 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, @@ -136,35 +205,40 @@ enum libinput_event_type { 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; struct libinput_device; struct libinput_seat; -union libinput_event_target { - struct libinput *libinput; - struct libinput_seat *seat; - struct libinput_device *device; -}; - struct libinput_event; -struct libinput_event_added_seat; -struct libinput_event_removed_seat; -struct libinput_event_added_device; -struct libinput_event_removed_device; -struct libinput_event_device_register_capability; -struct libinput_event_device_unregister_capability; -struct libinput_event_keyboard_key; -struct libinput_event_pointer_motion; -struct libinput_event_pointer_motion_absolute; -struct libinput_event_pointer_button; -struct libinput_event_pointer_axis; -struct libinput_event_touch_touch; +struct libinput_event_device_notify; +struct libinput_event_keyboard; +struct libinput_event_pointer; /** - * @defgroup event Acessing and destruction of events + * @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; + +/** + * @defgroup event Accessing and destruction of events */ /** @@ -177,201 +251,643 @@ struct libinput_event_touch_touch; void libinput_event_destroy(struct libinput_event *event); +/** + * @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); -union libinput_event_target -libinput_event_get_target(struct libinput_event *event); +/** + * @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); /** - * @defgroup event_added_seat Added seat event + * @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_seat * -libinput_event_added_seat_get_seat(struct libinput_event_added_seat *event); +struct libinput_device * +libinput_event_get_device(struct libinput_event *event); /** - * @defgroup event_removed_seat Removed seat 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); -struct libinput_seat * -libinput_event_removed_seat_get_seat(struct libinput_event_removed_seat *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); /** - * @defgroup event_added_device Added device 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); -struct libinput_device * -libinput_event_added_device_get_device( - struct libinput_event_added_device *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); /** - * @defgroup event_removed_device Removed device 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); -struct libinput_device * -libinput_event_removed_device_get_device( - struct libinput_event_removed_device *event); +/** + * @defgroup event_keyboard Keyboard events + * + * Key events are generated when a key changes its logical state, usually by + * being pressed or released. + */ /** - * @defgroup event_device_register_capability Register device capability event + * @ingroup event_keyboard + * + * @return The event time for this event */ +uint32_t +libinput_event_keyboard_get_time(struct libinput_event_keyboard *event); -enum libinput_device_capability -libinput_event_device_register_capability_get_capability( - struct libinput_event_device_register_capability *event); +/** + * @ingroup event_keyboard + * + * @return The keycode that triggered this key event + */ +uint32_t +libinput_event_keyboard_get_key(struct libinput_event_keyboard *event); /** - * @defgroup event_device_unregister_capability Register device capability 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); -enum libinput_device_capability -libinput_event_device_unregister_capability_get_capability( - struct libinput_event_device_unregister_capability *event); /** - * @defgroup event_keyboard_key Keyboard key 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_key_get_time( - struct libinput_event_keyboard_key *event); +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_keyboard_key_get_key( - struct libinput_event_keyboard_key *event); +libinput_event_pointer_get_time(struct libinput_event_pointer *event); -enum libinput_keyboard_key_state -libinput_event_keyboard_key_get_state( - struct libinput_event_keyboard_key *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); /** - * @defgroup event_pointer_motion Pointer motion 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); -uint32_t -libinput_event_pointer_motion_get_time( - struct libinput_event_pointer_motion *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); -li_fixed_t -libinput_event_pointer_motion_get_dx( - struct libinput_event_pointer_motion *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); -li_fixed_t -libinput_event_pointer_motion_get_dy( - struct libinput_event_pointer_motion *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); /** - * @defgroup event_pointer_motion_absolute Absolute pointer motion event + * @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); +/** + * @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_motion_absolute_get_time( - struct libinput_event_pointer_motion_absolute *event); +libinput_event_pointer_get_button(struct libinput_event_pointer *event); -li_fixed_t -libinput_event_pointer_motion_absolute_get_x( - struct libinput_event_pointer_motion_absolute *event); +/** + * @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); -li_fixed_t -libinput_event_pointer_motion_absolute_get_y( - struct libinput_event_pointer_motion_absolute *event); +/** + * @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); /** - * @defgroup event_pointer_button Pointer button 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); -uint32_t -libinput_event_pointer_button_get_time( - struct libinput_event_pointer_button *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); -uint32_t -libinput_event_pointer_button_get_button( - struct libinput_event_pointer_button *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); -enum libinput_pointer_button_state -libinput_event_pointer_button_get_state( - struct libinput_event_pointer_button *event); /** - * @defgroup event_pointer_axis Pointer axis 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_pointer_axis_get_time( - struct libinput_event_pointer_axis *event); +libinput_event_touch_get_time(struct libinput_event_touch *event); -enum libinput_pointer_axis -libinput_event_pointer_axis_get_axis( - struct libinput_event_pointer_axis *event); - -li_fixed_t -libinput_event_pointer_axis_get_value( - struct libinput_event_pointer_axis *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); /** - * @defgroup event_pointer_button Pointer button 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); -uint32_t -libinput_event_touch_touch_get_time( - struct libinput_event_touch_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); -uint32_t -libinput_event_touch_touch_get_slot( - struct libinput_event_touch_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); -li_fixed_t -libinput_event_touch_touch_get_x( - struct libinput_event_touch_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); -li_fixed_t -libinput_event_touch_touch_get_y( - struct libinput_event_touch_touch *event); +/** + * @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); -enum libinput_touch_type -libinput_event_touch_touch_get_touch_type( - struct libinput_event_touch_touch *event); +/** + * @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); - - void (*get_current_screen_dimensions)(struct libinput_device *device, - int *width, - int *height, - void *user_data); }; /** * @ingroup base * - * Create a new libinput context from udev, for input devices matching - * the given seat ID. New devices or devices removed will appear as events - * during libinput_dispatch. + * 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 - * @param seat_id A seat identifier. This string must not be NULL. * - * @return An initialize libinput context, ready to handle events or NULL on - * error. + * @return An initialized, but inactive libinput context or NULL on error */ struct libinput * -libinput_create_from_udev(const struct libinput_interface *interface, - void *user_data, - struct udev *udev, +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_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. * @@ -384,14 +900,14 @@ libinput_get_fd(struct libinput *libinput); * @ingroup base * * Main event dispatchment function. Reads events of the file descriptors - * and processes them internall. Use libinput_get_event() to retrieve the + * 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 - * @retval -EAGAIN libinput_dispatch completed successfully but no events - * are ready to read with libinput_get_event() */ int libinput_dispatch(struct libinput *libinput); @@ -413,6 +929,20 @@ 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(). @@ -449,15 +979,125 @@ libinput_suspend(struct libinput *libinput); /** * @ingroup base * - * Destroy the libinput context. + * 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_destroy(struct libinput *libinput); +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 */ /** @@ -469,8 +1109,9 @@ libinput_destroy(struct libinput *libinput); * the seat correctly to avoid dangling pointers. * * @param seat A previously obtained seat + * @return The passed seat */ -void +struct libinput_seat * libinput_seat_ref(struct libinput_seat *seat); /** @@ -482,8 +1123,9 @@ libinput_seat_ref(struct libinput_seat *seat); * the seat correctly to avoid dangling pointers. * * @param seat A previously obtained seat + * @return NULL if seat was destroyed, otherwise the passed seat */ -void +struct libinput_seat * libinput_seat_unref(struct libinput_seat *seat); /** @@ -515,11 +1157,33 @@ 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 name of this seat + * @return the physical name of this seat */ const char * -libinput_seat_get_name(struct libinput_seat *seat); +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 @@ -534,8 +1198,9 @@ libinput_seat_get_name(struct libinput_seat *seat); * the device correctly to avoid dangling pointers. * * @param device A previously obtained device + * @return The passed device */ -void +struct libinput_device * libinput_device_ref(struct libinput_device *device); /** @@ -547,8 +1212,9 @@ libinput_device_ref(struct libinput_device *device); * the device correctly to avoid dangling pointers. * * @param device A previously obtained device + * @return NULL if device was destroyed, otherwise the passed device */ -void +struct libinput_device * libinput_device_unref(struct libinput_device *device); /** @@ -580,6 +1246,58 @@ 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 @@ -596,6 +1314,11 @@ libinput_device_get_output_name(struct libinput_device *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 */ @@ -625,6 +1348,8 @@ libinput_device_led_update(struct libinput_device *device, * @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, @@ -647,4 +1372,148 @@ 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 */