X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=src%2Flibinput.h;h=7d33f2b20bc53368acec4c5c6d90f78f8e3fd73b;hb=e82728ca2773d297d9103b14edceff1a9c12833e;hp=993472c522b6d974753ab82807a8c3f17cd3a74c;hpb=e80cff7b0e18da0ac57662afb99e5ec396ab3786;p=platform%2Fupstream%2Flibinput.git diff --git a/src/libinput.h b/src/libinput.h index 993472c..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,11 +43,65 @@ */ /** - * @ingroup fixed_point + * @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 * - * libinput 24.8 fixed point real number. + * 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. @@ -55,7 +117,7 @@ enum libinput_log_priority { * * 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, @@ -69,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 }; /** @@ -91,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 }; @@ -103,23 +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. - */ -enum libinput_touch_type { - LIBINPUT_TOUCH_TYPE_DOWN = 0, - LIBINPUT_TOUCH_TYPE_UP = 1, - LIBINPUT_TOUCH_TYPE_MOTION = 2, - LIBINPUT_TOUCH_TYPE_CANCEL = 4 + LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0, + LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1, }; /** @@ -158,7 +205,10 @@ 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. @@ -181,51 +231,14 @@ struct libinput_event_pointer; * * 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_TOUCH and @ref LIBINPUT_EVENT_TOUCH_FRAME. + * 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 fixed_point Fixed point utilities - */ - -/** - * @ingroup fixed_point - * - * Convert li_fixed_t to a double - * - * @param f fixed point number - * @return Converted double - */ -static inline double -li_fixed_to_double (li_fixed_t f) -{ - union { - double d; - int64_t i; - } u; - - u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f; - - return u.d - (3LL << 43); -} - -/** - * @ingroup fixed_point - * - * Convert li_fixed_t to a int. The fraction part is discarded. - * - * @param f fixed point number - * @return Converted int - */ -static inline int -li_fixed_to_int(li_fixed_t f) -{ - return f / 256; -} - -/** - * @defgroup event Acessing and destruction of events + * @defgroup event Accessing and destruction of events */ /** @@ -281,6 +294,8 @@ libinput_event_get_device(struct libinput_event *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 * @@ -292,6 +307,8 @@ libinput_event_get_pointer_event(struct libinput_event *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 * @@ -303,6 +320,8 @@ libinput_event_get_keyboard_event(struct libinput_event *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 * @@ -314,12 +333,23 @@ libinput_event_get_touch_event(struct libinput_event *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 @@ -347,9 +377,34 @@ libinput_event_keyboard_get_key(struct libinput_event_keyboard *event); * * @return The state change of the key */ -enum libinput_keyboard_key_state +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 * @@ -377,7 +432,7 @@ libinput_event_pointer_get_time(struct libinput_event_pointer *event); * * @return the relative x movement since the last event */ -li_fixed_t +double libinput_event_pointer_get_dx(struct libinput_event_pointer *event); /** @@ -392,17 +447,15 @@ libinput_event_pointer_get_dx(struct libinput_event_pointer *event); * * @return the relative y movement since the last event */ -li_fixed_t +double libinput_event_pointer_get_dy(struct libinput_event_pointer *event); /** * @ingroup event_pointer * - * Return the current absolute x coordinate of the pointer event. - * - * The coordinate is in a device specific coordinate space; to get the - * corresponding output screen coordinate, use - * libinput_event_pointer_get_x_transformed(). + * 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. @@ -412,17 +465,15 @@ libinput_event_pointer_get_dy(struct libinput_event_pointer *event); * * @return the current absolute x coordinate */ -li_fixed_t +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. - * - * The coordinate is in a device specific coordinate space; to get the - * corresponding output screen coordinate, use - * libinput_event_pointer_get_y_transformed(). + * 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. @@ -432,7 +483,7 @@ libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event); * * @return the current absolute y coordinate */ -li_fixed_t +double libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event); /** @@ -452,7 +503,7 @@ libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event); * @param width The current output screen width * @return the current absolute x coordinate transformed to a screen coordinate */ -li_fixed_t +double libinput_event_pointer_get_absolute_x_transformed( struct libinput_event_pointer *event, uint32_t width); @@ -474,7 +525,7 @@ libinput_event_pointer_get_absolute_x_transformed( * @param height The current output screen height * @return the current absolute y coordinate transformed to a screen coordinate */ -li_fixed_t +double libinput_event_pointer_get_absolute_y_transformed( struct libinput_event_pointer *event, uint32_t height); @@ -506,12 +557,28 @@ libinput_event_pointer_get_button(struct libinput_event_pointer *event); * * @return the button state triggering this event */ -enum libinput_pointer_button_state +enum libinput_button_state libinput_event_pointer_get_button_state(struct libinput_event_pointer *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); + +/** + * @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. @@ -529,8 +596,8 @@ libinput_event_pointer_get_axis(struct libinput_event_pointer *event); * * 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_VERTICAL_SCROLL and - * LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL, the value of the event is in + * 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 @@ -544,10 +611,19 @@ libinput_event_pointer_get_axis(struct libinput_event_pointer *event); * * @return the axis value of this event */ -li_fixed_t +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. @@ -570,7 +646,8 @@ libinput_event_touch_get_time(struct libinput_event_touch *event); * 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_FRAME. + * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or + * LIBINPUT_EVENT_TOUCH_FRAME. * * @return The slot of this touch event */ @@ -586,7 +663,8 @@ libinput_event_touch_get_slot(struct libinput_event_touch *event); * 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_FRAME. + * @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 */ @@ -596,35 +674,35 @@ libinput_event_touch_get_seat_slot(struct libinput_event_touch *event); /** * @ingroup event_touch * - * Return the current absolute x coordinate of the touch event. + * 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(). * - * The coordinate is in a device specific coordinate space; to get the - * corresponding output screen coordinate, use - * libinput_event_touch_get_x_transformed(). - * - * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME. + * @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 */ -li_fixed_t +double libinput_event_touch_get_x(struct libinput_event_touch *event); /** * @ingroup event_touch * - * Return the current absolute y coordinate of the touch event. + * 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(). * - * The coordinate is in a device specific coordinate space; 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 not be called for LIBINPUT_EVENT_TOUCH_FRAME. + * @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 */ -li_fixed_t +double libinput_event_touch_get_y(struct libinput_event_touch *event); /** @@ -633,13 +711,14 @@ libinput_event_touch_get_y(struct libinput_event_touch *event); * Return the current absolute x coordinate of the touch event, transformed to * screen coordinates. * - * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME. + * @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 */ -li_fixed_t +double libinput_event_touch_get_x_transformed(struct libinput_event_touch *event, uint32_t width); @@ -649,25 +728,24 @@ libinput_event_touch_get_x_transformed(struct libinput_event_touch *event, * Return the current absolute y coordinate of the touch event, transformed to * screen coordinates. * - * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME. + * @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 */ -li_fixed_t +double libinput_event_touch_get_y_transformed(struct libinput_event_touch *event, uint32_t height); /** * @ingroup event_touch * - * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME. - * - * @return the type of touch that occured on the device + * @return The generic libinput_event of this event */ -enum libinput_touch_type -libinput_event_touch_get_touch_type(struct libinput_event_touch *event); +struct libinput_event * +libinput_event_touch_get_base_event(struct libinput_event_touch *event); /** * @defgroup base Initialization and manipulation of libinput contexts @@ -681,7 +759,7 @@ struct libinput_interface { * @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_for_seat() + * libinput_udev_create_context() * * @return the file descriptor, or a negative errno on failure. */ @@ -691,7 +769,7 @@ struct libinput_interface { * * @param fd The file descriptor to close * @param user_data The user_data provided in - * libinput_udev_create_for_seat() + * libinput_udev_create_context() */ void (*close_restricted)(int fd, void *user_data); }; @@ -699,24 +777,45 @@ struct libinput_interface { /** * @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 initialized libinput context, ready to handle events or NULL on - * error. + * @return An initialized, but inactive libinput context or NULL on error */ struct libinput * -libinput_udev_create_for_seat(const struct libinput_interface *interface, - void *user_data, - struct udev *udev, - const char *seat_id); +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 @@ -728,6 +827,9 @@ libinput_udev_create_for_seat(const struct libinput_interface *interface, * 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. @@ -742,13 +844,13 @@ libinput_path_create_context(const struct libinput_interface *interface, * @ingroup base * * Add a device to a libinput context initialized with - * libinput_path_create_from_device(). If successful, the device will be + * 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 linput_dispatch(), use libinput_device_ref() to keep a permanent + * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent * reference. * * @param libinput A previously initialized libinput context @@ -756,7 +858,7 @@ libinput_path_create_context(const struct libinput_interface *interface, * @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 initialize with libinput_udev_create_for_seat(). + * context initialized with libinput_udev_create_context(). */ struct libinput_device * libinput_path_add_device(struct libinput *libinput, @@ -766,7 +868,7 @@ libinput_path_add_device(struct libinput *libinput, * @ingroup base * * Remove a device from a libinput context initialized with - * libinput_path_create_from_device() or added to such a context 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, @@ -778,7 +880,7 @@ libinput_path_add_device(struct libinput *libinput, * @param device A libinput device * * @note It is an application bug to call this function on a libinput - * context initialize with libinput_udev_create_for_seat(). + * context initialized with libinput_udev_create_context(). */ void libinput_path_remove_device(struct libinput_device *device); @@ -877,13 +979,27 @@ libinput_suspend(struct libinput *libinput); /** * @ingroup base * - * Destroy the libinput context. After this, object references associated with - * the destroyed context are invalid and may not be interacted with. + * 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 */ -void -libinput_destroy(struct libinput *libinput); +struct libinput * +libinput_unref(struct libinput *libinput); /** * @ingroup base @@ -893,12 +1009,15 @@ libinput_destroy(struct libinput *libinput); * * 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_log_set_priority(enum libinput_log_priority priority); +libinput_log_set_priority(struct libinput *libinput, + enum libinput_log_priority priority); /** * @ingroup base @@ -908,30 +1027,32 @@ libinput_log_set_priority(enum libinput_log_priority priority); * * 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(void); +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 user_data Caller-specific data pointer as previously passed into - * libinput_log_set_handler() * @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)(enum libinput_log_priority priority, - void *user_data, - const char *format, va_list args); +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 @@ -942,6 +1063,7 @@ typedef void (*libinput_log_handler)(enum libinput_log_priority priority, * * 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. @@ -949,8 +1071,8 @@ typedef void (*libinput_log_handler)(enum libinput_log_priority priority, * @see libinput_log_set_handler */ void -libinput_log_set_handler(libinput_log_handler log_handler, - void *user_data); +libinput_log_set_handler(struct libinput *libinput, + libinput_log_handler log_handler); /** * @defgroup seat Initialization and manipulation of seats @@ -987,8 +1109,9 @@ libinput_log_set_handler(libinput_log_handler log_handler, * 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); /** @@ -1000,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); /** @@ -1035,7 +1159,7 @@ libinput_seat_get_user_data(struct libinput_seat *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_create_for_seat() and all seats from that context will have + * 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 @@ -1074,8 +1198,9 @@ libinput_seat_get_logical_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); /** @@ -1087,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); /** @@ -1122,8 +1248,11 @@ libinput_device_get_user_data(struct libinput_device *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); @@ -1131,6 +1260,44 @@ 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 @@ -1181,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, @@ -1214,4 +1383,137 @@ 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 */