X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=src%2Flibinput.h;h=7d33f2b20bc53368acec4c5c6d90f78f8e3fd73b;hb=e82728ca2773d297d9103b14edceff1a9c12833e;hp=810a66c22b9fe30f9c87e2d1b1ac6b7f1b3cb13f;hpb=3ece2270443f4b1a905a94a409fab62bbae71eed;p=platform%2Fupstream%2Flibinput.git diff --git a/src/libinput.h b/src/libinput.h index 810a66c..7d33f2b 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -31,6 +31,10 @@ extern "C" { #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 @@ -39,11 +43,65 @@ extern "C" { */ /** - * @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. @@ -59,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, @@ -73,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 }; /** @@ -95,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 }; @@ -107,8 +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 + LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0, + LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1, }; /** @@ -180,46 +238,7 @@ struct libinput_event_pointer; 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 */ /** @@ -358,7 +377,7 @@ 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); @@ -371,6 +390,22 @@ 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 @@ -397,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); /** @@ -412,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. @@ -432,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. @@ -452,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); /** @@ -472,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); @@ -494,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); @@ -526,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. @@ -549,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 @@ -564,7 +611,7 @@ 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); /** @@ -627,11 +674,9 @@ libinput_event_touch_get_seat_slot(struct libinput_event_touch *event); /** * @ingroup event_touch * - * Return the current absolute x coordinate of the touch event. - * - * The coordinate is in a device specific coordinate space; to get the - * corresponding output screen coordinate, use - * libinput_event_touch_get_x_transformed(). + * 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. @@ -639,17 +684,15 @@ libinput_event_touch_get_seat_slot(struct libinput_event_touch *event); * @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. - * - * The coordinate is in a device specific coordinate space; to get the - * corresponding output screen coordinate, use - * libinput_event_touch_get_y_transformed(). + * 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. * @@ -659,7 +702,7 @@ libinput_event_touch_get_x(struct libinput_event_touch *event); * @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); /** @@ -675,7 +718,7 @@ libinput_event_touch_get_y(struct libinput_event_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); @@ -692,7 +735,7 @@ libinput_event_touch_get_x_transformed(struct libinput_event_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); @@ -716,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. */ @@ -726,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); }; @@ -734,31 +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(). * - * libinput_udev_create_for_seat() succeeds even if no input device is - * available in this seat, or if devices are available but fail to open in + * @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(). * - * @param interface The callback interface - * @param user_data Caller-specific data passed to the various callback - * interfaces. - * @param udev An already initialized udev context + * 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 An initialized libinput context, ready to handle events or NULL on - * error. + * @return 0 on success or -1 on failure. */ -struct libinput * -libinput_udev_create_for_seat(const struct libinput_interface *interface, - void *user_data, - struct udev *udev, - const char *seat_id); +int +libinput_udev_assign_seat(struct libinput *libinput, + const char *seat_id); /** * @ingroup base @@ -770,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. @@ -784,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 @@ -798,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, @@ -808,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, @@ -820,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); @@ -919,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 @@ -935,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 @@ -950,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 @@ -984,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. @@ -991,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 @@ -1029,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); /** @@ -1042,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); /** @@ -1077,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 @@ -1116,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); /** @@ -1129,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); /** @@ -1164,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); @@ -1173,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 @@ -1258,8 +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 */