*/
/**
+ * @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 {
* @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)(struct libinput *libinput,
*
* @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(struct libinput *libinput,
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
projects / platform / upstream / libinput.git / blobdiff