X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=src%2Flibinput.h;h=7d33f2b20bc53368acec4c5c6d90f78f8e3fd73b;hb=e82728ca2773d297d9103b14edceff1a9c12833e;hp=d765ced2325f23fb2f131f8d34e8fd4d6bd8f504;hpb=ac5fc23e49ffdb0a6f4ab45ef26048f3c414373d;p=platform%2Fupstream%2Flibinput.git diff --git a/src/libinput.h b/src/libinput.h index d765ced..7d33f2b 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -50,7 +50,7 @@ extern "C" { * * Software button areas * ===================== - * On most touchpads, the bottom area of the touchpad is split into a a left + * 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: * @@ -455,7 +455,7 @@ libinput_event_pointer_get_dy(struct libinput_event_pointer *event); * * 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_x_transformed(). + * 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. @@ -473,7 +473,7 @@ libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event); * * 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_x_transformed(). + * 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. @@ -759,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. */ @@ -769,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); }; @@ -815,44 +815,7 @@ libinput_udev_create_context(const struct libinput_interface *interface, */ int libinput_udev_assign_seat(struct libinput *libinput, - const char *seat_id); - -/** - * @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. - * - * 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 - * @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(). - * - * 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. - * @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. - * - * @deprecated This function was deprecated in 0.4.0 and will be removed - * soon. Use libinput_udev_create_context() and libinput_udev_assign_seat() - * instead. - */ -struct libinput * -libinput_udev_create_for_seat(const struct libinput_interface *interface, - void *user_data, - struct udev *udev, - const char *seat_id) - LIBINPUT_ATTRIBUTE_DEPRECATED; + const char *seat_id); /** * @ingroup base @@ -895,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 initialized with libinput_udev_create_for_seat(). + * context initialized with libinput_udev_create_context(). */ struct libinput_device * libinput_path_add_device(struct libinput *libinput, @@ -917,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 initialized with libinput_udev_create_for_seat(). + * context initialized with libinput_udev_create_context(). */ void libinput_path_remove_device(struct libinput_device *device); @@ -1196,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 @@ -1285,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); @@ -1294,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 @@ -1398,8 +1402,118 @@ 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 */