#define LIBINPUT_ATTRIBUTE_PRINTF(_format, _args) \
__attribute__ ((format (printf, _format, _args)))
+#define LIBINPUT_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated))
/**
* @mainpage
*
* 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:
*
* 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
*/
/**
+ * @page udev_config Static device configuration via udev
+ *
+ * libinput supports some static configuration through udev properties.
+ * These propertiesare read when the device is initially added
+ * to libinput's device list, i.e. before the @ref
+ * LIBINPUT_EVENT_DEVICE_ADDED event is generated.
+ *
+ * The following udev properties are supported:
+ * <dl>
+ * <dt>LIBINPUT_CALIBRATION_MATRIX</dt>
+ * <dd>Sets the calibration matrix, see
+ * libinput_device_config_calibration_get_default_matrix(). If unset,
+ * defaults to the identity matrix.</dd>
+ * <dt>ID_SEAT</dt>
+ * <dd>Assigns the physical seat for this device. See
+ * libinput_seat_get_physical_name(). Defaults to "seat0".</dd>
+ * <dt>WL_SEAT</dt>
+ * <dd>Assigns the logical seat for this device. See
+ * libinput_seat_get_logical_name()
+ * context. Defaults to "default".</dd>
+ * </dl>
+ *
+ * Below is an example udev rule to assign "seat1" to a device from vendor
+ * 0x012a with the model ID of 0x034b.
+ * @code
+ * ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
+ * ENV{ID_MODEL_ID}=="034b", ENV{ID_SEAT}="seat1"
+ * @endcode
+ *
+ */
+
+/**
* Log priority for internal logging messages.
*/
enum libinput_log_priority {
* 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
};
/**
* 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,
};
/**
*
* @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);
* events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
* returns 0.
*
+ * If a device employs pointer acceleration, the delta returned by this
+ * function is the accelerated delta.
+ *
* @note It is an application bug to call this function for events other than
* LIBINPUT_EVENT_POINTER_MOTION.
*
* events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
* returns 0.
*
+ * If a device employs pointer acceleration, the delta returned by this
+ * function is the accelerated delta.
+ *
* @note It is an application bug to call this function for events other than
* LIBINPUT_EVENT_POINTER_MOTION.
*
/**
* @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.
/**
* @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.
*
* 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
/**
* @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.
/**
* @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.
*
* @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);
};
/**
* @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
* 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_priority
+ * @see libinput_log_get_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
+ * @see libinput_log_set_priority
+ * @see libinput_log_get_priority
*/
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
*/
int
libinput_device_get_keys(struct libinput_device *device,
- char *keys, size_t size);
+ char *keys, size_t size)
+ LIBINPUT_ATTRIBUTE_DEPRECATED;
/**
* @ingroup device
*
+ * @deprecated Use libinput_device_config_calibration_set_matrix() instead.
+ */
+void
+libinput_device_calibrate(struct libinput_device *device,
+ float calibration[6])
+ LIBINPUT_ATTRIBUTE_DEPRECATED;
+
+/**
+ * @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
+ */
+enum libinput_config_tap_state {
+ LIBINPUT_CONFIG_TAP_DISABLED, /**< Tapping is to be disabled, or is
+ currently disabled */
+ LIBINPUT_CONFIG_TAP_ENABLED, /**< Tapping is to be enabled, or is
+ currently enabled */
+};
+
+/**
+ * @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_get_default_enabled
+ */
+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 @ref LIBINPUT_CONFIG_TAP_ENABLED to enable tapping or @ref
+ * LIBINPUT_CONFIG_TAP_DISABLED to disable tapping
+ *
+ * @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,
+ enum libinput_config_tap_state 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 @ref LIBINPUT_CONFIG_TAP_ENABLED if tapping is currently enabled,
+ * or @ref LIBINPUT_CONFIG_TAP_DISABLED is currently disabled
+ *
+ * @see libinput_device_config_tap_get_finger_count
+ * @see libinput_device_config_tap_set_enabled
+ * @see libinput_device_config_tap_get_default_enabled
+ */
+enum libinput_config_tap_state
+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 @ref LIBINPUT_CONFIG_TAP_ENABLED if tapping is enabled by default,
+ * or @ref LIBINPUT_CONFIG_TAP_DISABLED is disabled by default
+ *
+ * @see libinput_device_config_tap_get_finger_count
+ * @see libinput_device_config_tap_set_enabled
+ * @see libinput_device_config_tap_get_enabled
+ */
+enum libinput_config_tap_state
+libinput_device_config_tap_get_default_enabled(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Check if the device can be calibrated via a calibration matrix.
+ *
+ * @param device The device to check
+ * @return non-zero if the device can be calibrated, zero otherwise.
+ *
+ * @see libinput_device_config_calibration_set_matrix
+ * @see libinput_device_config_calibration_get_matrix
+ * @see libinput_device_config_calibration_get_default_matrix
+ */
+int
+libinput_device_config_calibration_has_matrix(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
* Apply the 3x3 transformation matrix to absolute device coordinates. This
* matrix has no effect on relative events.
*
* [ d e f ] * [ y ]
* [ 0 0 1 ] [ 1 ]
* @endcode
+ *
+ * The translation component (c, f) is expected to be normalized to the
+ * device coordinate range. For example, the matrix
+ * @code
+ * [ 1 0 1 ]
+ * [ 0 1 -1 ]
+ * [ 0 0 1 ]
+ * @endcode
+ * moves all coordinates by 1 device-width to the right and 1 device-height
+ * up.
+ *
+ * The rotation matrix for rotation around the origin is defined as
+ * @code
+ * [ cos(a) -sin(a) 0 ]
+ * [ sin(a) cos(a) 0 ]
+ * [ 0 0 1 ]
+ * @endcode
+ * Note that any rotation requires an additional translation component to
+ * translate the rotated coordinates back into the original device space.
+ * The rotation matrixes for 90, 180 and 270 degrees clockwise are:
+ * @code
+ * 90 deg cw: 180 deg cw: 270 deg cw:
+ * [ 0 -1 1] [ -1 0 1] [ 0 1 0 ]
+ * [ 1 0 0] [ 0 -1 1] [ -1 0 1 ]
+ * [ 0 0 1] [ 0 0 1] [ 0 0 1 ]
+ * @endcode
+ *
+ * @param device The device to configure
+ * @param matrix An array representing the first two rows of a 3x3 matrix as
+ * described above.
+ *
+ * @return A config status code.
+ *
+ * @see libinput_device_config_calibration_has_matrix
+ * @see libinput_device_config_calibration_get_matrix
+ * @see libinput_device_config_calibration_get_default_matrix
*/
-void
-libinput_device_calibrate(struct libinput_device *device,
- float calibration[6]);
+enum libinput_config_status
+libinput_device_config_calibration_set_matrix(struct libinput_device *device,
+ const float matrix[6]);
/**
- * @ingroup device
+ * @ingroup config
*
- * Check if the given device has the specified capability
+ * Return the current calibration matrix for this device.
*
- * @return 1 if the given device has the capability or 0 if not
+ * @param device The device to configure
+ * @param matrix Set to the array representing the first two rows of a 3x3 matrix as
+ * described in libinput_device_config_calibration_set_matrix().
+ *
+ * @return 0 if no calibration is set and the returned matrix is the
+ * identity matrix, 1 otherwise
+ *
+ * @see libinput_device_config_calibration_has_matrix
+ * @see libinput_device_config_calibration_set_matrix
+ * @see libinput_device_config_calibration_get_default_matrix
*/
int
-libinput_device_has_capability(struct libinput_device *device,
- enum libinput_device_capability capability);
+libinput_device_config_calibration_get_matrix(struct libinput_device *device,
+ float matrix[6]);
+
+/**
+ * @ingroup config
+ *
+ * Return the default calibration matrix for this device. On most devices,
+ * this is the identity matrix. If the udev property
+ * <b>LIBINPUT_CALIBRATION_MATRIX</b> is set on the respective udev device,
+ * that property's value becomes the default matrix.
+ *
+ * The udev property is parsed as 6 floating point numbers separated by a
+ * single space each (scanf(3) format "%f %f %f %f %f %f").
+ * The 6 values represent the first two rows of the calibration matrix as
+ * described in libinput_device_config_calibration_set_matrix().
+ *
+ * Example values are:
+ * @code
+ * ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
+ * ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
+ * ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
+ * ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
+ * ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 1 0 0" # reflect along y axis
+ * @endcode
+ *
+ * @param device The device to configure
+ * @param matrix Set to the array representing the first two rows of a 3x3 matrix as
+ * described in libinput_device_config_calibration_set_matrix().
+ *
+ * @return 0 if no calibration is set and the returned matrix is the
+ * identity matrix, 1 otherwise
+ *
+ * @see libinput_device_config_calibration_has_matrix
+ * @see libinput_device_config_calibration_set_matrix
+ * @see libinput_device_config_calibration_get_default_matrix
+ */
+int
+libinput_device_config_calibration_get_default_matrix(struct libinput_device *device,
+ float matrix[6]);
+
+/**
+ * The send-event mode of a device defines when a device may generate events
+ * and pass those events to the caller.
+ */
+enum libinput_config_send_events_mode {
+ /**
+ * Send events from this device normally.
+ */
+ LIBINPUT_CONFIG_SEND_EVENTS_ENABLED = (1 << 0),
+ /**
+ * Do not send events through this device. Depending on the device,
+ * this may close all file descriptors on the device or it may leave
+ * the file descriptors open and route events through a different
+ * device.
+ */
+ LIBINPUT_CONFIG_SEND_EVENTS_DISABLED = (1 << 1),
+ /**
+ * If an external pointer device is plugged in, do not send events
+ * from this device. This option may be available on built-in
+ * touchpads.
+ */
+ LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE = (1 << 2),
+};
+
+/**
+ * @ingroup config
+ *
+ * Return the possible send-event modes for this device. These modes define
+ * when a device may process and send events.
+ *
+ * @param device The device to configure
+ *
+ * @return A bitmask of possible modes.
+ *
+ * @see libinput_device_config_send_events_set_mode
+ * @see libinput_device_config_send_events_get_mode
+ * @see libinput_device_config_send_events_get_default_mode
+ */
+uint32_t
+libinput_device_config_send_events_get_modes(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Set the send-event mode for this device. The mode defines when the device
+ * processes and sends events to the caller.
+ *
+ * The selected mode may not take effect immediately. Events already
+ * received and processed from this device are unaffected and will be passed
+ * to the caller on the next call to libinput_get_event().
+ *
+ * If the mode is one of @ref LIBINPUT_CONFIG_SEND_EVENTS_DISABLED or
+ * @ref LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE, the device
+ * may wait for or generate events until it is in a neutral state.
+ * For example, this may include waiting for or generating button release
+ * events.
+ *
+ * If the device is already suspended, this function does nothing and
+ * returns success. Changing the send-event mode on a device that has been
+ * removed is permitted.
+ *
+ * @param device The device to configure
+ * @param mode The send-event mode for this device.
+ *
+ * @return A config status code.
+ *
+ * @see libinput_device_config_send_events_get_modes
+ * @see libinput_device_config_send_events_get_mode
+ * @see libinput_device_config_send_events_get_default_mode
+ */
+enum libinput_config_status
+libinput_device_config_send_events_set_mode(struct libinput_device *device,
+ enum libinput_config_send_events_mode mode);
+
+/**
+ * @ingroup config
+ *
+ * Get the send-event mode for this device. The mode defines when the device
+ * processes and sends events to the caller.
+ *
+ * @param device The device to configure
+ * @return The current send-event mode for this device.
+ *
+ * @see libinput_device_config_send_events_get_modes
+ * @see libinput_device_config_send_events_set_mode
+ * @see libinput_device_config_send_events_get_default_mode
+ */
+enum libinput_config_send_events_mode
+libinput_device_config_send_events_get_mode(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Get the default send-event mode for this device. The mode defines when
+ * the device processes and sends events to the caller.
+ *
+ * @param device The device to configure
+ * @return The default send-event mode for this device.
+ *
+ * @see libinput_device_config_send_events_get_modes
+ * @see libinput_device_config_send_events_set_mode
+ * @see libinput_device_config_send_events_get_default_mode
+ */
+enum libinput_config_send_events_mode
+libinput_device_config_send_events_get_default_mode(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Check if a device uses libinput-internal pointer-acceleration.
+ *
+ * @param device The device to configure
+ *
+ * @return 0 if the device is not accelerated, nonzero if it is accelerated
+ */
+int
+libinput_device_config_accel_is_available(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Set the pointer acceleration speed of this pointer device within a range
+ * of [-1, 1], where 0 is the default acceleration for this device, -1 is
+ * the slowest acceleration and 1 is the maximum acceleration available on
+ * this device. The actual pointer acceleration mechanism is
+ * implementation-dependent, as is the number of steps available within the
+ * range. libinput picks the semantically closest acceleration step if the
+ * requested value does not match a discreet setting.
+ *
+ * @param device The device to configure
+ * @param speed The normalized speed, in a range of [-1, 1]
+ *
+ * @return A config status code
+ */
+enum libinput_config_status
+libinput_device_config_accel_set_speed(struct libinput_device *device,
+ double speed);
+
+/**
+ * @ingroup config
+ *
+ * Get the current pointer acceleration setting for this pointer device. The
+ * returned value is normalized to a range of [-1, 1].
+ * See libinput_device_config_accel_set_speed() for details.
+ *
+ * @param device The device to configure
+ *
+ * @return The current speed, range -1 to 1
+ */
+double
+libinput_device_config_accel_get_speed(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Return the default speed setting for this device, normalized to a range
+ * of [-1, 1].
+ * See libinput_device_config_accel_set_speed() for details.
+ *
+ * @param device The device to configure
+ * @return The default speed setting for this device.
+ */
+double
+libinput_device_config_accel_get_default_speed(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Return non-zero if the device supports "natural scrolling".
+ *
+ * In traditional scroll mode, the movement of fingers on a touchpad when
+ * scrolling matches the movement of the scroll bars. When the fingers move
+ * down, the scroll bar moves down, a line of text on the screen moves
+ * towards the upper end of the screen. This also matches scroll wheels on
+ * mice (wheel down, content moves up).
+ *
+ * Natural scrolling is the term coined by Apple for inverted scrolling.
+ * In this mode, the effect of scrolling movement of fingers on a touchpad
+ * resemble physical manipulation of paper. When the fingers move down, a
+ * line of text on the screen moves down (scrollbars move up). This is the
+ * opposite of scroll wheels on mice.
+ *
+ * A device supporting natural scrolling can be switched between traditional
+ * scroll mode and natural scroll mode.
+ *
+ * @param device The device to configure
+ *
+ * @return 0 if natural scrolling is not supported, non-zero if natural
+ * scrolling is supported by this device
+ *
+ * @see libinput_device_config_set_natural_scroll_enabled
+ * @see libinput_device_config_get_natural_scroll_enabled
+ * @see libinput_device_config_get_default_natural_scroll_enabled
+ */
+int
+libinput_device_config_scroll_has_natural_scroll(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Enable or disable natural scrolling on the device.
+ *
+ * @param device The device to configure
+ * @param enable non-zero to enable, zero to disable natural scrolling
+ *
+ * @return a config status code
+ *
+ * @see libinput_device_config_has_natural_scroll
+ * @see libinput_device_config_get_natural_scroll_enabled
+ * @see libinput_device_config_get_default_natural_scroll_enabled
+ */
+enum libinput_config_status
+libinput_device_config_scroll_set_natural_scroll_enabled(struct libinput_device *device,
+ int enable);
+/**
+ * @ingroup config
+ *
+ * Get the current mode for scrolling on this device
+ *
+ * @param device The device to configure
+ *
+ * @return zero if natural scrolling is disabled, non-zero if enabled
+ *
+ * @see libinput_device_config_has_natural_scroll
+ * @see libinput_device_config_set_natural_scroll_enabled
+ * @see libinput_device_config_get_default_natural_scroll_enabled
+ */
+int
+libinput_device_config_scroll_get_natural_scroll_enabled(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Get the default mode for scrolling on this device
+ *
+ * @param device The device to configure
+ *
+ * @return zero if natural scrolling is disabled by default, non-zero if enabled
+ *
+ * @see libinput_device_config_has_natural_scroll
+ * @see libinput_device_config_set_natural_scroll_enabled
+ * @see libinput_device_config_get_natural_scroll_enabled
+ */
+int
+libinput_device_config_scroll_get_default_natural_scroll_enabled(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Check if a device has a button configuration that supports left-handed
+ * usage.
+ *
+ * @param device The device to configure
+ * @return Non-zero if the device can be set to left-handed, or zero
+ * otherwise
+ *
+ * @see libinput_device_config_buttons_set_left_handed
+ * @see libinput_device_config_buttons_get_left_handed
+ * @see libinput_device_config_buttons_get_default_left_handed
+ */
+int
+libinput_device_config_buttons_has_left_handed(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Set the left-handed configuration of the device. A device in left-handed
+ * mode sends a left button event instead of the right button and vice
+ * versa.
+ *
+ * The exact button behavior is device-dependent. On a mouse and most
+ * pointing devices, left and right buttons are swapped but the middle
+ * button is unmodified. On a touchpad, physical buttons (if present) are
+ * swapped. On a clickpad, the top and bottom software-emulated buttons are
+ * swapped where present, the main area of the touchpad remains a left
+ * button. Tapping and clickfinger behavior is not affected by this setting.
+ *
+ * Changing the left-handed configuration of a device may not take effect
+ * until all buttons have been logically released.
+ *
+ * @param device The device to configure
+ * @param left_handed Zero to disable, non-zero to enable left-handed mode
+ * @return A configuration status code
+ *
+ * @see libinput_device_config_buttons_has_left_handed
+ * @see libinput_device_config_buttons_get_left_handed
+ * @see libinput_device_config_buttons_get_default_left_handed
+ */
+enum libinput_config_status
+libinput_device_config_buttons_set_left_handed(struct libinput_device *device,
+ int left_handed);
+
+/**
+ * @ingroup config
+ *
+ * Get the current left-handed configuration of the device.
+ *
+ * @param device The device to configure
+ * @return Zero if the device is in right-handed mode, non-zero if the
+ * device is in left-handed mode
+ *
+ * @see libinput_device_config_buttons_has_left_handed
+ * @see libinput_device_config_buttons_set_left_handed
+ * @see libinput_device_config_buttons_get_default_left_handed
+ */
+int
+libinput_device_config_buttons_get_left_handed(struct libinput_device *device);
+
+/**
+ * @ingroup config
+ *
+ * Get the default left-handed configuration of the device.
+ *
+ * @param device The device to configure
+ * @return Zero if the device is in right-handed mode by default, or non-zero if the
+ * device is in left-handed mode by default
+ *
+ * @see libinput_device_config_buttons_has_left_handed
+ * @see libinput_device_config_buttons_set_left_handed
+ * @see libinput_device_config_buttons_get_left_handed
+ */
+int
+libinput_device_config_buttons_get_default_left_handed(struct libinput_device *device);
#ifdef __cplusplus
}
#endif
-
#endif /* LIBINPUT_H */
projects / platform / upstream / libinput.git / blobdiff