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 }
 
enum  libinput_config_drag_lock_state { LIBINPUT_CONFIG_DRAG_LOCK_DISABLED, LIBINPUT_CONFIG_DRAG_LOCK_ENABLED }
 
enum  libinput_config_send_events_mode { LIBINPUT_CONFIG_SEND_EVENTS_ENABLED, LIBINPUT_CONFIG_SEND_EVENTS_DISABLED, LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE }
 The send-event mode of a device defines when a device may generate events and pass those events to the caller. More...
 
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_middle_emulation_state { LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED, LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED }
 
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...
 
enum  libinput_config_dwt_state { LIBINPUT_CONFIG_DWT_DISABLED, LIBINPUT_CONFIG_DWT_ENABLED }
 Possible states for the disable-while-typing feature. 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 and how many fingers can be used for tapping. 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 tap-to-click is enabled on this device. More...
 
enum libinput_config_status libinput_device_config_tap_set_drag_lock_enabled (struct libinput_device *device, enum libinput_config_drag_lock_state enable)
 Enable or disable drag-lock during tapping on this device. More...
 
enum libinput_config_drag_lock_state libinput_device_config_tap_get_drag_lock_enabled (struct libinput_device *device)
 Check if drag-lock during tapping is enabled on this device. More...
 
enum libinput_config_drag_lock_state libinput_device_config_tap_get_default_drag_lock_enabled (struct libinput_device *device)
 Check if drag-lock during tapping is enabled by default 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...
 
uint32_t libinput_device_config_accel_get_profiles (struct libinput_device *device)
 Returns a bitmask of the configurable acceleration modes available on this device. More...
 
enum libinput_config_status libinput_device_config_accel_set_profile (struct libinput_device *device, enum libinput_config_accel_profile mode)
 Set the pointer acceleration profile of this pointer device to the given mode. More...
 
enum libinput_config_accel_profile libinput_device_config_accel_get_profile (struct libinput_device *device)
 Get the current pointer acceleration profile for this pointer device. More...
 
enum libinput_config_accel_profile libinput_device_config_accel_get_default_profile (struct libinput_device *device)
 Return the default pointer acceleration profile for this pointer device. 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...
 
int libinput_device_config_middle_emulation_is_available (struct libinput_device *device)
 Check if middle mouse button emulation configuration is available on this device. More...
 
enum libinput_config_status libinput_device_config_middle_emulation_set_enabled (struct libinput_device *device, enum libinput_config_middle_emulation_state enable)
 Enable or disable middle button emulation on this device. More...
 
enum libinput_config_middle_emulation_state libinput_device_config_middle_emulation_get_enabled (struct libinput_device *device)
 Check if configurable middle button emulation is enabled on this device. More...
 
enum libinput_config_middle_emulation_state libinput_device_config_middle_emulation_get_default_enabled (struct libinput_device *device)
 Check if configurable middle button emulation is enabled by default on 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 the LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for this device. More...
 
int libinput_device_config_dwt_is_available (struct libinput_device *device)
 Check if this device supports configurable disable-while-typing feature. More...
 
enum libinput_config_status libinput_device_config_dwt_set_enabled (struct libinput_device *device, enum libinput_config_dwt_state enable)
 Enable or disable the disable-while-typing feature. More...
 
enum libinput_config_dwt_state libinput_device_config_dwt_get_enabled (struct libinput_device *device)
 Check if the disable-while typing feature is currently enabled on this device. More...
 
enum libinput_config_dwt_state libinput_device_config_dwt_get_default_enabled (struct libinput_device *device)
 Check if the disable-while typing feature is enabled on this device by default. 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-dependent, the caller must ensure that the options are set in the right order.

Enumeration Type Documentation

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 events generated by physical buttons.

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.

Enumerator
LIBINPUT_CONFIG_DRAG_LOCK_DISABLED 

Drag lock is to be disabled, or is currently disabled.

LIBINPUT_CONFIG_DRAG_LOCK_ENABLED 

Drag lock is to be enabled, or is currently disabled.

Possible states for the disable-while-typing feature.

See Disable-while-typing for details.

Enumerator
LIBINPUT_CONFIG_DWT_DISABLED 
LIBINPUT_CONFIG_DWT_ENABLED 
Enumerator
LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED 

Middle mouse button emulation is to be disabled, or is currently disabled.

LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED 

Middle mouse button emulation is to be enabled, or is currently enabled.

The scroll method of a device selects when to generate scroll axis events instead of pointer motion events.

Enumerator
LIBINPUT_CONFIG_SCROLL_NO_SCROLL 

Never send scroll events instead of pointer motion events.

This has no effect on events generated by scroll wheels.

LIBINPUT_CONFIG_SCROLL_2FG 

Send scroll events when two fingers are logically down on the device.

LIBINPUT_CONFIG_SCROLL_EDGE 

Send scroll events when a finger moves along the bottom or right edge of a device.

LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN 

Send scroll events when a button is down and the device moves along a scroll-capable axis.

The send-event mode of a device defines when a device may generate events and pass those events to the caller.

Enumerator
LIBINPUT_CONFIG_SEND_EVENTS_ENABLED 

Send events from this device normally.

This is a placeholder mode only, any device detected by libinput can be enabled. Do not test for this value as bitmask.

LIBINPUT_CONFIG_SEND_EVENTS_DISABLED 

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.

If this bit field is set, other disable modes may be ignored. For example, if both LIBINPUT_CONFIG_SEND_EVENTS_DISABLED and LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE are set, the device remains disabled when all external pointer devices are unplugged.

LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE 

If an external pointer device is plugged in, do not send events from this device.

This option may be available on built-in touchpads.

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.
enum libinput_config_accel_profile libinput_device_config_accel_get_default_profile ( struct libinput_device device)

Return the default pointer acceleration profile for this pointer device.

Parameters
deviceThe device to configure
Returns
The default acceleration profile for this device.
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.

Parameters
deviceThe device to configure
Returns
The default speed setting for this device.
enum libinput_config_accel_profile libinput_device_config_accel_get_profile ( struct libinput_device device)

Get the current pointer acceleration profile for this pointer device.

Parameters
deviceThe device to configure
Returns
The currently configured pointer acceleration profile.
uint32_t libinput_device_config_accel_get_profiles ( struct libinput_device device)

Returns a bitmask of the configurable acceleration modes available on this device.

Parameters
deviceThe device to configure
Returns
A bitmask of all configurable modes availble on this device.
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.

Parameters
deviceThe device to configure
Returns
The current speed, range -1 to 1
int libinput_device_config_accel_is_available ( struct libinput_device device)

Check if a device uses libinput-internal pointer-acceleration.

Parameters
deviceThe device to configure
Returns
0 if the device is not accelerated, nonzero if it is accelerated
enum libinput_config_status libinput_device_config_accel_set_profile ( struct libinput_device device,
enum libinput_config_accel_profile  mode 
)

Set the pointer acceleration profile of this pointer device to the given mode.

Parameters
deviceThe device to configure
modeThe mode to set the device to.
Returns
A config status code
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.

Parameters
deviceThe device to configure
speedThe normalized speed, in a range of [-1, 1]
Returns
A config status code
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, see Static device configuration via udev.

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

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

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

1 [ 1 0 1 ]
2 [ 0 1 -1 ]
3 [ 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

1 [ cos(a) -sin(a) 0 ]
2 [ sin(a) cos(a) 0 ]
3 [ 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:

1 90 deg cw: 180 deg cw: 270 deg cw:
2 [ 0 -1 1] [ -1 0 1] [ 0 1 0 ]
3 [ 1 0 0] [ 0 -1 1] [ -1 0 1 ]
4 [ 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_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.

Parameters
deviceThe device to configure
Returns
The default button click method for this device
See also
libinput_device_config_click_get_methods
libinput_device_config_click_set_method
libinput_device_config_click_get_method
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.

Parameters
deviceThe device to configure
Returns
The current button click method for this device
See also
libinput_device_config_click_get_methods
libinput_device_config_click_set_method
libinput_device_config_click_get_default_method
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.

Parameters
deviceThe device to configure
Returns
A bitmask of possible methods.
See also
libinput_device_config_click_get_methods
libinput_device_config_click_set_method
libinput_device_config_click_get_method
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.

Note
The selected click method may not take effect immediately. The device may require changing to a neutral state first before activating the new method.
Parameters
deviceThe device to configure
methodThe button click method
Returns
A config status code
See also
libinput_device_config_click_get_methods
libinput_device_config_click_get_method
libinput_device_config_click_get_default_method
enum libinput_config_dwt_state libinput_device_config_dwt_get_default_enabled ( struct libinput_device device)

Check if the disable-while typing feature is enabled on this device by default.

If the device does not support disable-while-typing, this function returns LIBINPUT_CONFIG_DWT_DISABLED.

Parameters
deviceThe device to configure
Returns
LIBINPUT_CONFIG_DWT_DISABLED if disabled, LIBINPUT_CONFIG_DWT_ENABLED if enabled.
See also
libinput_device_config_dwt_is_available
libinput_device_config_dwt_set_enabled
libinput_device_config_dwt_get_enabled
enum libinput_config_dwt_state libinput_device_config_dwt_get_enabled ( struct libinput_device device)

Check if the disable-while typing feature is currently enabled on this device.

If the device does not support disable-while-typing, this function returns LIBINPUT_CONFIG_DWT_DISABLED.

Parameters
deviceThe device to configure
Returns
LIBINPUT_CONFIG_DWT_DISABLED if disabled, LIBINPUT_CONFIG_DWT_ENABLED if enabled.
See also
libinput_device_config_dwt_is_available
libinput_device_config_dwt_set_enabled
libinput_device_config_dwt_get_default_enabled
int libinput_device_config_dwt_is_available ( struct libinput_device device)

Check if this device supports configurable disable-while-typing feature.

This feature is usally available on built-in touchpads and disables the touchpad while typing. See Disable-while-typing for details.

Parameters
deviceThe device to configure
Returns
0 if this device does not support disable-while-typing, or 1 otherwise.
See also
libinput_device_config_dwt_set_enabled
libinput_device_config_dwt_get_enabled
libinput_device_config_dwt_get_default_enabled
enum libinput_config_status libinput_device_config_dwt_set_enabled ( struct libinput_device device,
enum libinput_config_dwt_state  enable 
)

Enable or disable the disable-while-typing feature.

When enabled, the device will be disabled while typing and for a short period after. See Disable-while-typing for details.

Note
Enabling or disabling disable-while-typing may not take effect immediately.
Parameters
deviceThe device to configure
enableLIBINPUT_CONFIG_DWT_DISABLED to disable disable-while-typing, LIBINPUT_CONFIG_DWT_ENABLED to enable
Returns
A config status code. Disabling disable-while-typing on a device that does not support the feature always succeeds.
See also
libinput_device_config_dwt_is_available
libinput_device_config_dwt_get_enabled
libinput_device_config_dwt_get_default_enabled
int libinput_device_config_left_handed_get ( struct libinput_device device)

Get the current left-handed configuration of the device.

Parameters
deviceThe device to configure
Returns
Zero if the device is in right-handed mode, non-zero if the device is in left-handed mode
See also
libinput_device_config_left_handed_is_available
libinput_device_config_left_handed_set
libinput_device_config_left_handed_get_default
int libinput_device_config_left_handed_get_default ( struct libinput_device device)

Get the default left-handed configuration of the device.

Parameters
deviceThe device to configure
Returns
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 also
libinput_device_config_left_handed_is_available
libinput_device_config_left_handed_set
libinput_device_config_left_handed_get
int libinput_device_config_left_handed_is_available ( struct libinput_device device)

Check if a device has a configuration that supports left-handed usage.

Parameters
deviceThe device to configure
Returns
Non-zero if the device can be set to left-handed, or zero otherwise
See also
libinput_device_config_left_handed_set
libinput_device_config_left_handed_get
libinput_device_config_left_handed_get_default
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.

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.

Parameters
deviceThe device to configure
left_handedZero to disable, non-zero to enable left-handed mode
Returns
A configuration status code
See also
libinput_device_config_left_handed_is_available
libinput_device_config_left_handed_get
libinput_device_config_left_handed_get_default
enum libinput_config_middle_emulation_state libinput_device_config_middle_emulation_get_default_enabled ( struct libinput_device device)

Check if configurable middle button emulation is enabled by default on this device.

If the device does not have configurable middle button emulation, this function returns LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.

Note
Some devices provide middle mouse button emulation but do not allow enabling/disabling that emulation. These devices always return LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.
Parameters
deviceThe device to configure
Returns
LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED If disabled or not available, LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED if enabled.
See also
libinput_device_config_middle_emulation_is_available
libinput_device_config_middle_emulation_set_enabled
libinput_device_config_middle_emulation_get_enabled
enum libinput_config_middle_emulation_state libinput_device_config_middle_emulation_get_enabled ( struct libinput_device device)

Check if configurable middle button emulation is enabled on this device.

If the device does not have configurable middle button emulation, this function returns LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.

Note
Some devices provide middle mouse button emulation but do not allow enabling/disabling that emulation. These devices always return LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.
Parameters
deviceThe device to configure
Returns
LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED if disabled or not available/configurable, LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED If enabled.
See also
libinput_device_config_middle_emulation_is_available
libinput_device_config_middle_emulation_set_enabled
libinput_device_config_middle_emulation_get_default_enabled
int libinput_device_config_middle_emulation_is_available ( struct libinput_device device)

Check if middle mouse button emulation configuration is available on this device.

See libinput_device_config_middle_emulation_set_enabled() for details.

Note
Some devices provide middle mouse button emulation but do not allow enabling/disabling that emulation. These devices return zero in libinput_device_config_middle_emulation_is_available().
Parameters
deviceThe device to query
Returns
Non-zero if middle mouse button emulation is available and can be configured, zero otherwise.
See also
libinput_device_config_middle_emulation_set_enabled
libinput_device_config_middle_emulation_get_enabled
libinput_device_config_middle_emulation_get_default_enabled
enum libinput_config_status libinput_device_config_middle_emulation_set_enabled ( struct libinput_device device,
enum libinput_config_middle_emulation_state  enable 
)

Enable or disable middle button emulation on this device.

When enabled, a simultaneous press of the left and right button generates a middle mouse button event. Releasing the buttons generates a middle mouse button release, the left and right button events are discarded otherwise.

The middle button release event may be generated when either button is released, or when both buttons have been released. The exact behavior is device-dependent.

The middle button emulation behavior when combined with other device buttons, including a physical middle button is device-dependent.

Note
Some devices provide middle mouse button emulation but do not allow enabling/disabling that emulation.
Parameters
deviceThe device to configure
enableLIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED to disable, LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED To enable middle button emulation.
Returns
A config status code. Disabling middle button emulation on a device that does not support middle button emulation always succeeds.
See also
libinput_device_config_middle_emulation_is_available
libinput_device_config_middle_emulation_get_enabled
libinput_device_config_middle_emulation_get_default_enabled
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.

Note
The return value is independent of the currently selected scroll-method. For button scrolling to activate, a device must have the LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method enabled, and a non-zero button set as scroll button.
Parameters
deviceThe device to configure
Returns
The button which when pressed switches to sending scroll events
See also
libinput_device_config_scroll_get_methods
libinput_device_config_scroll_set_method
libinput_device_config_scroll_get_method
libinput_device_config_scroll_get_default_method
libinput_device_config_scroll_set_button
libinput_device_config_scroll_get_default_button
uint32_t libinput_device_config_scroll_get_default_button ( struct libinput_device device)

Get the default 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 default button is set, this function returns 0.

Parameters
deviceThe device to configure
Returns
The default button for the LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method
See also
libinput_device_config_scroll_get_methods
libinput_device_config_scroll_set_method
libinput_device_config_scroll_get_method
libinput_device_config_scroll_get_default_method
libinput_device_config_scroll_set_button
libinput_device_config_scroll_get_button
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.

Parameters
deviceThe device to configure
Returns
The default scroll method for this device.
See also
libinput_device_config_scroll_get_methods
libinput_device_config_scroll_set_method
libinput_device_config_scroll_get_method
libinput_device_config_scroll_set_button
libinput_device_config_scroll_get_button
libinput_device_config_scroll_get_default_button
int libinput_device_config_scroll_get_default_natural_scroll_enabled ( struct libinput_device device)

Get the default mode for scrolling on this device.

Parameters
deviceThe device to configure
Returns
Zero if natural scrolling is disabled by default, non-zero if enabled
See also
libinput_device_config_has_natural_scroll
libinput_device_config_set_natural_scroll_enabled
libinput_device_config_get_natural_scroll_enabled
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.

Parameters
deviceThe device to configure
Returns
The current scroll method for this device.
See also
libinput_device_config_scroll_get_methods
libinput_device_config_scroll_set_method
libinput_device_config_scroll_get_default_method
libinput_device_config_scroll_set_button
libinput_device_config_scroll_get_button
libinput_device_config_scroll_get_default_button
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.

Parameters
deviceThe device to configure
Returns
A bitmask of possible methods.
See also
libinput_device_config_scroll_set_method
libinput_device_config_scroll_get_method
libinput_device_config_scroll_get_default_method
libinput_device_config_scroll_set_button
libinput_device_config_scroll_get_button
libinput_device_config_scroll_get_default_button
int libinput_device_config_scroll_get_natural_scroll_enabled ( struct libinput_device device)

Get the current mode for scrolling on this device.

Parameters
deviceThe device to configure
Returns
Zero if natural scrolling is disabled, non-zero if enabled
See also
libinput_device_config_has_natural_scroll
libinput_device_config_set_natural_scroll_enabled
libinput_device_config_get_default_natural_scroll_enabled
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.

Parameters
deviceThe device to configure
Returns
Zero if natural scrolling is not supported, non-zero if natural scrolling is supported by this device
See also
libinput_device_config_set_natural_scroll_enabled
libinput_device_config_get_natural_scroll_enabled
libinput_device_config_get_default_natural_scroll_enabled
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.

Note
Setting the button does not change the scroll method. To change the scroll method call libinput_device_config_scroll_set_method().

If the button is 0, button scrolling is effectively disabled.

Parameters
deviceThe device to configure
buttonThe button which when pressed switches to sending scroll events
Returns
A config status code
Return values
LIBINPUT_CONFIG_STATUS_SUCCESSOn success
LIBINPUT_CONFIG_STATUS_UNSUPPORTEDIf LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN is not supported
LIBINPUT_CONFIG_STATUS_INVALIDThe given button does not exist on this device
See also
libinput_device_config_scroll_get_methods
libinput_device_config_scroll_set_method
libinput_device_config_scroll_get_method
libinput_device_config_scroll_get_default_method
libinput_device_config_scroll_get_button
libinput_device_config_scroll_get_default_button
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.

Note
Setting LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN enables the scroll method, but scrolling is only activated when the configured button is held down. If no button is set, i.e. libinput_device_config_scroll_get_button() returns 0, scrolling cannot activate.
Parameters
deviceThe device to configure
methodThe scroll method for this device.
Returns
A config status code.
See also
libinput_device_config_scroll_get_methods
libinput_device_config_scroll_get_method
libinput_device_config_scroll_get_default_method
libinput_device_config_scroll_set_button
libinput_device_config_scroll_get_button
libinput_device_config_scroll_get_default_button
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.

Parameters
deviceThe device to configure
enablenon-zero to enable, zero to disable natural scrolling
Returns
A config status code
See also
libinput_device_config_has_natural_scroll
libinput_device_config_get_natural_scroll_enabled
libinput_device_config_get_default_natural_scroll_enabled
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.

Parameters
deviceThe device to configure
Returns
The bitmask of the send-event mode for this device.
See also
libinput_device_config_send_events_get_modes
libinput_device_config_send_events_set_mode
libinput_device_config_send_events_get_mode
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().

Parameters
deviceThe device to configure
Returns
The current bitmask of the send-event mode for this device.
See also
libinput_device_config_send_events_get_modes
libinput_device_config_send_events_set_mode
libinput_device_config_send_events_get_default_mode
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.

Parameters
deviceThe device to configure
Returns
A bitmask of possible modes.
See also
libinput_device_config_send_events_set_mode
libinput_device_config_send_events_get_mode
libinput_device_config_send_events_get_default_mode
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.

Parameters
deviceThe device to configure
modeA bitmask of send-events modes
Returns
A config status code.
See also
libinput_device_config_send_events_get_modes
libinput_device_config_send_events_get_mode
libinput_device_config_send_events_get_default_mode
enum libinput_config_drag_lock_state libinput_device_config_tap_get_default_drag_lock_enabled ( struct libinput_device device)

Check if drag-lock during tapping is enabled by default on this device.

If the device does not support tapping, this function always returns LIBINPUT_CONFIG_DRAG_LOCK_DISABLED.

Drag lock may be enabled by default even when tapping is disabled by default.

Parameters
deviceThe device to configure
Return values
LIBINPUT_CONFIG_DRAG_LOCK_ENABLEDIf drag lock is enabled by default
LIBINPUT_CONFIG_DRAG_LOCK_DISABLEDIf drag lock is disabled by default
See also
libinput_device_config_tap_set_drag_lock_enabled
libinput_device_config_tap_get_drag_lock_enabled
enum libinput_config_tap_state libinput_device_config_tap_get_default_enabled ( struct libinput_device device)

Return the default setting for whether tap-to-click is enabled on this device.

Parameters
deviceThe device to configure
Return values
LIBINPUT_CONFIG_TAP_ENABLEDIf tapping is enabled by default
LIBINPUT_CONFIG_TAP_DISABLEDIf tapping 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_drag_lock_state libinput_device_config_tap_get_drag_lock_enabled ( struct libinput_device device)

Check if drag-lock during tapping is enabled on this device.

If the device does not support tapping, this function always returns LIBINPUT_CONFIG_DRAG_LOCK_DISABLED.

Drag lock may be enabled even when tapping is disabled.

Parameters
deviceThe device to configure
Return values
LIBINPUT_CONFIG_DRAG_LOCK_ENABLEDIf drag lock is currently enabled
LIBINPUT_CONFIG_DRAG_LOCK_DISABLEDIf drag lock is currently disabled
See also
libinput_device_config_tap_set_drag_lock_enabled
libinput_device_config_tap_get_default_drag_lock_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 LIBINPUT_CONFIG_TAP_DISABLED.

Parameters
deviceThe device to configure
Return values
LIBINPUT_CONFIG_TAP_ENABLEDIf tapping is currently enabled
LIBINPUT_CONFIG_TAP_DISABLEDIf tapping 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 and how many fingers can be used for tapping.

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_drag_lock_enabled ( struct libinput_device device,
enum libinput_config_drag_lock_state  enable 
)

Enable or disable drag-lock during tapping on this device.

When enabled, a finger may be lifted and put back on the touchpad within a timeout and the drag process continues. When disabled, lifting the finger during a tap-and-drag will immediately stop the drag. See Tap-and-drag for details.

Enabling drag lock on a device that has tapping disabled is permitted, but has no effect until tapping is enabled.

Parameters
deviceThe device to configure
enableLIBINPUT_CONFIG_DRAG_LOCK_ENABLED to enable drag lock or LIBINPUT_CONFIG_DRAG_LOCK_DISABLED to disable drag lock
Returns
A config status code. Disabling drag lock on a device that does not support tapping always succeeds.
See also
libinput_device_config_tap_get_drag_lock_enabled
libinput_device_config_tap_get_default_drag_lock_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