libinput
0.9.0
A wrapper library for input devices
|
Enable, disable, change and/or check for device-specific features. More...
Enumerations | |
enum | libinput_config_status { LIBINPUT_CONFIG_STATUS_SUCCESS, LIBINPUT_CONFIG_STATUS_UNSUPPORTED, LIBINPUT_CONFIG_STATUS_INVALID } |
Status codes returned when applying configuration settings. More... | |
enum | libinput_config_tap_state { LIBINPUT_CONFIG_TAP_DISABLED, LIBINPUT_CONFIG_TAP_ENABLED } |
enum | libinput_config_click_method { LIBINPUT_CONFIG_CLICK_METHOD_NONE, LIBINPUT_CONFIG_CLICK_METHOD_BUTTON_AREAS, LIBINPUT_CONFIG_CLICK_METHOD_CLICKFINGER } |
The click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available. More... | |
enum | libinput_config_scroll_method { LIBINPUT_CONFIG_SCROLL_NO_SCROLL, LIBINPUT_CONFIG_SCROLL_2FG, LIBINPUT_CONFIG_SCROLL_EDGE, LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN } |
The scroll method of a device selects when to generate scroll axis events instead of pointer motion events. More... | |
Functions | |
const char * | libinput_config_status_to_str (enum libinput_config_status status) |
Return a string describing the error. More... | |
int | libinput_device_config_tap_get_finger_count (struct libinput_device *device) |
Check if the device supports tap-to-click. More... | |
enum libinput_config_status | libinput_device_config_tap_set_enabled (struct libinput_device *device, enum libinput_config_tap_state enable) |
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. More... | |
enum libinput_config_tap_state | libinput_device_config_tap_get_enabled (struct libinput_device *device) |
Check if tap-to-click is enabled on this device. More... | |
enum libinput_config_tap_state | libinput_device_config_tap_get_default_enabled (struct libinput_device *device) |
Return the default setting for whether tapping is enabled on this device. More... | |
int | libinput_device_config_calibration_has_matrix (struct libinput_device *device) |
Check if the device can be calibrated via a calibration matrix. More... | |
enum libinput_config_status | libinput_device_config_calibration_set_matrix (struct libinput_device *device, const float matrix[6]) |
Apply the 3x3 transformation matrix to absolute device coordinates. More... | |
int | libinput_device_config_calibration_get_matrix (struct libinput_device *device, float matrix[6]) |
Return the current calibration matrix for this device. More... | |
int | libinput_device_config_calibration_get_default_matrix (struct libinput_device *device, float matrix[6]) |
Return the default calibration matrix for this device. More... | |
uint32_t | libinput_device_config_send_events_get_modes (struct libinput_device *device) |
Return the possible send-event modes for this device. More... | |
enum libinput_config_status | libinput_device_config_send_events_set_mode (struct libinput_device *device, uint32_t mode) |
Set the send-event mode for this device. More... | |
uint32_t | libinput_device_config_send_events_get_mode (struct libinput_device *device) |
Get the send-event mode for this device. More... | |
uint32_t | libinput_device_config_send_events_get_default_mode (struct libinput_device *device) |
Get the default send-event mode for this device. More... | |
int | libinput_device_config_accel_is_available (struct libinput_device *device) |
Check if a device uses libinput-internal pointer-acceleration. More... | |
enum libinput_config_status | libinput_device_config_accel_set_speed (struct libinput_device *device, double speed) |
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. More... | |
double | libinput_device_config_accel_get_speed (struct libinput_device *device) |
Get the current pointer acceleration setting for this pointer device. More... | |
double | libinput_device_config_accel_get_default_speed (struct libinput_device *device) |
Return the default speed setting for this device, normalized to a range of [-1, 1]. More... | |
int | libinput_device_config_scroll_has_natural_scroll (struct libinput_device *device) |
Return non-zero if the device supports "natural scrolling". More... | |
enum libinput_config_status | libinput_device_config_scroll_set_natural_scroll_enabled (struct libinput_device *device, int enable) |
Enable or disable natural scrolling on the device. More... | |
int | libinput_device_config_scroll_get_natural_scroll_enabled (struct libinput_device *device) |
Get the current mode for scrolling on this device. More... | |
int | libinput_device_config_scroll_get_default_natural_scroll_enabled (struct libinput_device *device) |
Get the default mode for scrolling on this device. More... | |
int | libinput_device_config_left_handed_is_available (struct libinput_device *device) |
Check if a device has a configuration that supports left-handed usage. More... | |
enum libinput_config_status | libinput_device_config_left_handed_set (struct libinput_device *device, int left_handed) |
Set the left-handed configuration of the device. More... | |
int | libinput_device_config_left_handed_get (struct libinput_device *device) |
Get the current left-handed configuration of the device. More... | |
int | libinput_device_config_left_handed_get_default (struct libinput_device *device) |
Get the default left-handed configuration of the device. More... | |
uint32_t | libinput_device_config_click_get_methods (struct libinput_device *device) |
Check which button click methods a device supports. More... | |
enum libinput_config_status | libinput_device_config_click_set_method (struct libinput_device *device, enum libinput_config_click_method method) |
Set the button click method for this device. More... | |
enum libinput_config_click_method | libinput_device_config_click_get_method (struct libinput_device *device) |
Get the button click method for this device. More... | |
enum libinput_config_click_method | libinput_device_config_click_get_default_method (struct libinput_device *device) |
Get the default button click method for this device. More... | |
uint32_t | libinput_device_config_scroll_get_methods (struct libinput_device *device) |
Check which scroll methods a device supports. More... | |
enum libinput_config_status | libinput_device_config_scroll_set_method (struct libinput_device *device, enum libinput_config_scroll_method method) |
Set the scroll method for this device. More... | |
enum libinput_config_scroll_method | libinput_device_config_scroll_get_method (struct libinput_device *device) |
Get the scroll method for this device. More... | |
enum libinput_config_scroll_method | libinput_device_config_scroll_get_default_method (struct libinput_device *device) |
Get the default scroll method for this device. More... | |
enum libinput_config_status | libinput_device_config_scroll_set_button (struct libinput_device *device, uint32_t button) |
Set the button for the LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for this device. More... | |
uint32_t | libinput_device_config_scroll_get_button (struct libinput_device *device) |
Get the button for the LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for this device. More... | |
uint32_t | libinput_device_config_scroll_get_default_button (struct libinput_device *device) |
Get the default button for LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for this device. More... | |
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.
The click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
Enumerator | |
---|---|
LIBINPUT_CONFIG_CLICK_METHOD_NONE |
Do not send software-emulated button events. This has no effect on physical button generations. |
LIBINPUT_CONFIG_CLICK_METHOD_BUTTON_AREAS |
Use software-button areas (see Clickfinger behavior) to generate button events. |
LIBINPUT_CONFIG_CLICK_METHOD_CLICKFINGER |
The number of fingers decides which button press to generate. |
The scroll method of a device selects when to generate scroll axis events instead of pointer motion events.
const char* libinput_config_status_to_str | ( | enum libinput_config_status | status | ) |
Return a string describing the error.
status | The status to translate to a string |
double libinput_device_config_accel_get_default_speed | ( | struct libinput_device * | device | ) |
Return the default speed setting for this device, normalized to a range of [-1, 1].
See libinput_device_config_accel_set_speed() for details.
device | The device to configure |
double libinput_device_config_accel_get_speed | ( | struct libinput_device * | device | ) |
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.
device | The device to configure |
int libinput_device_config_accel_is_available | ( | struct libinput_device * | device | ) |
Check if a device uses libinput-internal pointer-acceleration.
device | The device to configure |
enum libinput_config_status libinput_device_config_accel_set_speed | ( | struct libinput_device * | device, |
double | speed | ||
) |
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 discrete setting.
device | The device to configure |
speed | The normalized speed, in a range of [-1, 1] |
int libinput_device_config_calibration_get_default_matrix | ( | struct libinput_device * | device, |
float | matrix[6] | ||
) |
Return the default calibration matrix for this device.
On most devices, this is the identity matrix. If the udev property LIBINPUT_CALIBRATION_MATRIX 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:
device | The device to configure |
matrix | Set to the array representing the first two rows of a 3x3 matrix as described in libinput_device_config_calibration_set_matrix(). |
int libinput_device_config_calibration_get_matrix | ( | struct libinput_device * | device, |
float | matrix[6] | ||
) |
Return the current calibration matrix for this device.
device | The device to configure |
matrix | Set to the array representing the first two rows of a 3x3 matrix as described in libinput_device_config_calibration_set_matrix(). |
int libinput_device_config_calibration_has_matrix | ( | struct libinput_device * | device | ) |
Check if the device can be calibrated via a calibration matrix.
device | The device to check |
enum libinput_config_status libinput_device_config_calibration_set_matrix | ( | struct libinput_device * | device, |
const float | matrix[6] | ||
) |
Apply the 3x3 transformation matrix to absolute device coordinates.
This matrix has no effect on relative events.
Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
The translation component (c, f) is expected to be normalized to the device coordinate range. For example, the matrix
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
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:
device | The device to configure |
matrix | An array representing the first two rows of a 3x3 matrix as described above. |
enum libinput_config_click_method libinput_device_config_click_get_default_method | ( | struct libinput_device * | device | ) |
Get the default button click method for this device.
The button click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
device | The device to configure |
enum libinput_config_click_method libinput_device_config_click_get_method | ( | struct libinput_device * | device | ) |
Get the button click method for this device.
The button click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
device | The device to configure |
uint32_t libinput_device_config_click_get_methods | ( | struct libinput_device * | device | ) |
Check which button click methods a device supports.
The button click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
device | The device to configure |
enum libinput_config_status libinput_device_config_click_set_method | ( | struct libinput_device * | device, |
enum libinput_config_click_method | method | ||
) |
Set the button click method for this device.
The button click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
device | The device to configure |
method | The button click method |
int libinput_device_config_left_handed_get | ( | struct libinput_device * | device | ) |
Get the current left-handed configuration of the device.
device | The device to configure |
int libinput_device_config_left_handed_get_default | ( | struct libinput_device * | device | ) |
Get the default left-handed configuration of the device.
device | The device to configure |
int libinput_device_config_left_handed_is_available | ( | struct libinput_device * | device | ) |
Check if a device has a configuration that supports left-handed usage.
device | The device to configure |
enum libinput_config_status libinput_device_config_left_handed_set | ( | struct libinput_device * | device, |
int | left_handed | ||
) |
Set the left-handed configuration of the device.
For example, a pointing device may reverse it's buttons and send a right button click when the left button is pressed, and vice versa.
The exact 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.
device | The device to configure |
left_handed | Zero to disable, non-zero to enable left-handed mode |
uint32_t libinput_device_config_scroll_get_button | ( | struct libinput_device * | device | ) |
Get the button for the LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for this device.
If LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not supported, or no button is set, this function returns 0.
device | The device to configure |
uint32_t libinput_device_config_scroll_get_default_button | ( | struct libinput_device * | device | ) |
Get the default button for LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for this device.
If LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not supported, or no default button is set, this function returns 0.
device | The device to configure |
enum libinput_config_scroll_method libinput_device_config_scroll_get_default_method | ( | struct libinput_device * | device | ) |
Get the default scroll method for this device.
The method defines when to generate scroll axis events instead of pointer motion events.
device | The device to configure |
int libinput_device_config_scroll_get_default_natural_scroll_enabled | ( | struct libinput_device * | device | ) |
Get the default mode for scrolling on this device.
device | The device to configure |
enum libinput_config_scroll_method libinput_device_config_scroll_get_method | ( | struct libinput_device * | device | ) |
Get the scroll method for this device.
The method defines when to generate scroll axis events instead of pointer motion events.
device | The device to configure |
uint32_t libinput_device_config_scroll_get_methods | ( | struct libinput_device * | device | ) |
Check which scroll methods a device supports.
The method defines when to generate scroll axis events instead of pointer motion events.
device | The device to configure |
int libinput_device_config_scroll_get_natural_scroll_enabled | ( | struct libinput_device * | device | ) |
Get the current mode for scrolling on this device.
device | The device to configure |
int libinput_device_config_scroll_has_natural_scroll | ( | struct libinput_device * | device | ) |
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.
device | The device to configure |
enum libinput_config_status libinput_device_config_scroll_set_button | ( | struct libinput_device * | device, |
uint32_t | button | ||
) |
Set the button for the LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for this device.
When the current scroll method is set to LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN, no button press/release events will be send for the configured button.
When the configured button is pressed, any motion events along a scroll-capable axis are turned into scroll axis events.
If the button is 0, button scrolling is effectively disabled.
device | The device to configure |
button | The button which when pressed switches to sending scroll events |
LIBINPUT_CONFIG_STATUS_SUCCESS | on success |
LIBINPUT_CONFIG_STATUS_UNSUPPORTED | if LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN is not supported |
LIBINPUT_CONFIG_STATUS_INVALID | the given button does not exist on this device |
enum libinput_config_status libinput_device_config_scroll_set_method | ( | struct libinput_device * | device, |
enum libinput_config_scroll_method | method | ||
) |
Set the scroll method for this device.
The method defines when to generate scroll axis events instead of pointer motion events.
device | The device to configure |
method | The scroll method for this device. |
enum libinput_config_status libinput_device_config_scroll_set_natural_scroll_enabled | ( | struct libinput_device * | device, |
int | enable | ||
) |
Enable or disable natural scrolling on the device.
device | The device to configure |
enable | non-zero to enable, zero to disable natural scrolling |
uint32_t libinput_device_config_send_events_get_default_mode | ( | struct libinput_device * | device | ) |
Get the default send-event mode for this device.
The mode defines when the device processes and sends events to the caller.
device | The device to configure |
uint32_t libinput_device_config_send_events_get_mode | ( | struct libinput_device * | device | ) |
Get the send-event mode for this device.
The mode defines when the device processes and sends events to the caller.
If a caller enables the bits for multiple modes, some of which are subsets of another mode libinput may drop the bits that are subsets. In other words, don't expect libinput_device_config_send_events_get_mode() to always return exactly the same bitmask as passed into libinput_device_config_send_events_set_mode().
device | The device to configure |
uint32_t libinput_device_config_send_events_get_modes | ( | struct libinput_device * | device | ) |
Return the possible send-event modes for this device.
These modes define when a device may process and send events.
device | The device to configure |
enum libinput_config_status libinput_device_config_send_events_set_mode | ( | struct libinput_device * | device, |
uint32_t | mode | ||
) |
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 a bitmask of libinput_config_send_events_mode, 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.
device | The device to configure |
mode | A bitmask of send-events modes |
enum libinput_config_tap_state libinput_device_config_tap_get_default_enabled | ( | struct libinput_device * | device | ) |
Return the default setting for whether tapping is enabled on this device.
device | The device to configure |
enum libinput_config_tap_state libinput_device_config_tap_get_enabled | ( | struct libinput_device * | device | ) |
Check if tap-to-click is enabled on this device.
If the device does not support tapping, this function always returns 0.
device | The device to configure |
int libinput_device_config_tap_get_finger_count | ( | struct libinput_device * | device | ) |
Check if the device supports tap-to-click.
See libinput_device_config_tap_set_enabled() for more information.
device | The device to configure |
enum libinput_config_status libinput_device_config_tap_set_enabled | ( | struct libinput_device * | device, |
enum libinput_config_tap_state | enable | ||
) |
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().
device | The device to configure |
enable | LIBINPUT_CONFIG_TAP_ENABLED to enable tapping or LIBINPUT_CONFIG_TAP_DISABLED to disable tapping |