libinput  0.6.0
A wrapper library for input devices
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Enumerations | Functions
Device configuration

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 }
 

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...
 

Detailed Description

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.

Enumeration Type Documentation

Status codes returned when applying configuration settings.

Enumerator
LIBINPUT_CONFIG_STATUS_SUCCESS 

Config applied successfully.

LIBINPUT_CONFIG_STATUS_UNSUPPORTED 

Configuration not available on this device.

LIBINPUT_CONFIG_STATUS_INVALID 

Invalid parameter range.

Enumerator
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.

Function Documentation

const char* libinput_config_status_to_str ( enum libinput_config_status  status)

Return a string describing the error.

Parameters
statusThe status to translate to a string
Returns
A human-readable string representing the error or NULL for an invalid status.
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:

* 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
*
Parameters
deviceThe device to configure
matrixSet to the array representing the first two rows of a 3x3 matrix as described in libinput_device_config_calibration_set_matrix().
Returns
0 if no calibration is set and the returned matrix is the identity matrix, 1 otherwise
See Also
libinput_device_config_calibration_has_matrix
libinput_device_config_calibration_set_matrix
libinput_device_config_calibration_get_default_matrix
int libinput_device_config_calibration_get_matrix ( struct libinput_device *  device,
float  matrix[6] 
)

Return the current calibration matrix for this device.

Parameters
deviceThe device to configure
matrixSet to the array representing the first two rows of a 3x3 matrix as described in libinput_device_config_calibration_set_matrix().
Returns
0 if no calibration is set and the returned matrix is the identity matrix, 1 otherwise
See Also
libinput_device_config_calibration_has_matrix
libinput_device_config_calibration_set_matrix
libinput_device_config_calibration_get_default_matrix
int libinput_device_config_calibration_has_matrix ( struct libinput_device *  device)

Check if the device can be calibrated via a calibration matrix.

Parameters
deviceThe device to check
Returns
non-zero if the device can be calibrated, zero otherwise.
See Also
libinput_device_config_calibration_set_matrix
libinput_device_config_calibration_get_matrix
libinput_device_config_calibration_get_default_matrix
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

* [ a b c ] [ x ]
* [ d e f ] * [ y ]
* [ 0 0 1 ] [ 1 ]
*

The translation component (c, f) is expected to be normalized to the device coordinate range. For example, the matrix

* [ 1 0 1 ]
* [ 0 1 -1 ]
* [ 0 0 1 ]
*

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

* [ cos(a) -sin(a) 0 ]
* [ sin(a) cos(a) 0 ]
* [ 0 0 1 ]
*

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:

* 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 ]
*
Parameters
deviceThe device to configure
matrixAn array representing the first two rows of a 3x3 matrix as described above.
Returns
A config status code.
See Also
libinput_device_config_calibration_has_matrix
libinput_device_config_calibration_get_matrix
libinput_device_config_calibration_get_default_matrix
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.

Parameters
deviceThe device to configure
Returns
LIBINPUT_CONFIG_TAP_ENABLED if tapping is enabled by default, or LIBINPUT_CONFIG_TAP_DISABLED is disabled by default
See Also
libinput_device_config_tap_get_finger_count
libinput_device_config_tap_set_enabled
libinput_device_config_tap_get_enabled
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.

Parameters
deviceThe device to configure
Returns
LIBINPUT_CONFIG_TAP_ENABLED if tapping is currently enabled, or LIBINPUT_CONFIG_TAP_DISABLED is currently disabled
See Also
libinput_device_config_tap_get_finger_count
libinput_device_config_tap_set_enabled
libinput_device_config_tap_get_default_enabled
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.

Parameters
deviceThe device to configure
Returns
The number of fingers that can generate a tap event, or 0 if the device does not support tapping.
See Also
libinput_device_config_tap_set_enabled
libinput_device_config_tap_get_enabled
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 
)

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().

Parameters
deviceThe device to configure
enableLIBINPUT_CONFIG_TAP_ENABLED to enable tapping or LIBINPUT_CONFIG_TAP_DISABLED to disable tapping
Returns
A config status code. Disabling tapping on a device that does not support tapping always succeeds.
See Also
libinput_device_config_tap_get_finger_count
libinput_device_config_tap_get_enabled
libinput_device_config_tap_get_default_enabled