*
* 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:
*
enum libinput_pointer_axis {
LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0,
LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1,
-
-
- /** @deprecated Use @ref LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL instead */
- LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL,
- /** @deprecated Use @ref LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL instead */
- LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL
};
/**
*
* 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.
*
* 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.
* @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.
*/
*
* @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);
};
*/
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().
- *
- * @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
* 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 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,
* @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);
/**
* @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
*
* 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
*
* 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,
+typedef void (*libinput_log_handler)(struct libinput *libinput,
+ enum libinput_log_priority priority,
const char *format, va_list args)
LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
*
* 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(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
* 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);
/**
* 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);
/**
*
* 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
* 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);
/**
* 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);
/**
*
* 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
double *width,
double *height);
+
+/**
+ * @defgroup config Device configuration
+ *
+ * Enable, disable, change and/or check for device-specific features. For
+ * all features, libinput assigns a default based on the hardware
+ * configuration. This default can be obtained with the respective
+ * get_default call.
+ *
+ * Some configuration option may be dependent on or mutually exclusive with
+ * with other options. The behavior in those cases is
+ * implementation-defined, the caller must ensure that the options are set
+ * in the right order.
+ */
+
+/**
+ * @ingroup config
+ *
+ * Status codes returned when applying configuration settings.
+ */
+enum libinput_config_status {
+ LIBINPUT_CONFIG_STATUS_SUCCESS = 0, /**< Config applied successfully */
+ LIBINPUT_CONFIG_STATUS_UNSUPPORTED, /**< Configuration not available on
+ this device */
+ LIBINPUT_CONFIG_STATUS_INVALID, /**< Invalid parameter range */
+};
+
+/**
+ * @ingroup config
+ *
+ * Return a string describing the error.
+ *
+ * @param status The status to translate to a string
+ * @return A human-readable string representing the error or NULL for an
+ * invalid status.
+ */
+const char *
+libinput_config_status_to_str(enum libinput_config_status status);
+
+/**
+ * @ingroup config
+ *
+ * Check if the device supports tap-to-click. See
+ * libinput_device_config_tap_set_enabled() for more information.
+ *
+ * @param device The device to configure
+ * @return The number of fingers that can generate a tap event, or 0 if the
+ * device does not support tapping.
+ *
+ * @see libinput_device_config_tap_set_enabled
+ * @see libinput_device_config_tap_get_enabled
+ * @see libinput_device_config_tap_set_enabled_get_default
+ */
+int
+libinput_device_config_tap_get_finger_count(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Enable or disable tap-to-click on this device, with a default mapping of
+ * 1, 2, 3 finger tap mapping to left, right, middle click, respectively.
+ * Tapping is limited by the number of simultaneous touches
+ * supported by the device, see
+ * libinput_device_config_tap_get_finger_count().
+ *
+ * @param device The device to configure
+ * @param enable Non-zero to enable, zero to disable
+ *
+ * @return A config status code. Disabling tapping on a device that does not
+ * support tapping always succeeds.
+ *
+ * @see libinput_device_config_tap_get_finger_count
+ * @see libinput_device_config_tap_get_enabled
+ * @see libinput_device_config_tap_get_default_enabled
+ */
+enum libinput_config_status
+libinput_device_config_tap_set_enabled(struct libinput_device *device,
+ int enable);
+
+/**
+ * @ingroup config
+ *
+ * Check if tap-to-click is enabled on this device. If the device does not
+ * support tapping, this function always returns 0.
+ *
+ * @param device The device to configure
+ *
+ * @return 1 if enabled, 0 otherwise.
+ *
+ * @see libinput_device_config_tap_get_finger_count
+ * @see libinput_device_config_tap_set_enabled
+ * @see libinput_device_config_tap_get_default_enabled
+ */
+int
+libinput_device_config_tap_get_enabled(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Return the default setting for whether tapping is enabled on this device.
+ *
+ * @param device The device to configure
+ * @return 1 if tapping is enabled by default, or 0 otherwise
+ *
+ * @see libinput_device_config_tap_get_finger_count
+ * @see libinput_device_config_tap_set_enabled
+ * @see libinput_device_config_tap_get_enabled
+ */
+int
+libinput_device_config_tap_get_default_enabled(struct libinput_device *device);
+
#ifdef __cplusplus
}
#endif
-
#endif /* LIBINPUT_H */
projects / platform / upstream / libinput.git / blobdiff