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_tap_button_map { LIBINPUT_CONFIG_TAP_MAP_LRM , LIBINPUT_CONFIG_TAP_MAP_LMR }
 
enum  libinput_config_drag_state { LIBINPUT_CONFIG_DRAG_DISABLED , LIBINPUT_CONFIG_DRAG_ENABLED }
 A config status to distinguish or set dragging on a device. More...
 
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_accel_profile { LIBINPUT_CONFIG_ACCEL_PROFILE_NONE , LIBINPUT_CONFIG_ACCEL_PROFILE_FLAT , LIBINPUT_CONFIG_ACCEL_PROFILE_ADAPTIVE , LIBINPUT_CONFIG_ACCEL_PROFILE_CUSTOM }
 
enum  libinput_config_accel_type { LIBINPUT_ACCEL_TYPE_FALLBACK , LIBINPUT_ACCEL_TYPE_MOTION , LIBINPUT_ACCEL_TYPE_SCROLL }
 Acceleration types are categories of movement by a device that may have specific acceleration functions applied. 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...
 
enum  libinput_config_dwtp_state { LIBINPUT_CONFIG_DWTP_DISABLED , LIBINPUT_CONFIG_DWTP_ENABLED }
 Possible states for the disable-while-trackpointing 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_button_map (struct libinput_device *device, enum libinput_config_tap_button_map map)
 Set the finger number to button number mapping for tap-to-click. More...
 
enum libinput_config_tap_button_map libinput_device_config_tap_get_button_map (struct libinput_device *device)
 Get the finger number to button number mapping for tap-to-click. More...
 
enum libinput_config_tap_button_map libinput_device_config_tap_get_default_button_map (struct libinput_device *device)
 Get the default finger number to button number mapping for tap-to-click. More...
 
enum libinput_config_status libinput_device_config_tap_set_drag_enabled (struct libinput_device *device, enum libinput_config_drag_state enable)
 Enable or disable tap-and-drag on this device. More...
 
enum libinput_config_drag_state libinput_device_config_tap_get_drag_enabled (struct libinput_device *device)
 Return whether tap-and-drag is enabled or disabled on this device. More...
 
enum libinput_config_drag_state libinput_device_config_tap_get_default_drag_enabled (struct libinput_device *device)
 Return whether tap-and-drag is enabled or disabled by default 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...
 
struct libinput_config_accel * libinput_config_accel_create (enum libinput_config_accel_profile profile)
 Create an acceleration configuration of a given profile. More...
 
void libinput_config_accel_destroy (struct libinput_config_accel *accel_config)
 Destroy an acceleration configuration. More...
 
enum libinput_config_status libinput_device_config_accel_apply (struct libinput_device *device, struct libinput_config_accel *accel_config)
 Apply this pointer acceleration configuration to the device. More...
 
enum libinput_config_status libinput_config_accel_set_points (struct libinput_config_accel *accel_config, enum libinput_config_accel_type accel_type, double step, size_t npoints, double *points)
 Defines the acceleration function for a given movement type in an acceleration configuration with the profile LIBINPUT_CONFIG_ACCEL_PROFILE_CUSTOM. 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 profile)
 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...
 
enum libinput_config_status libinput_device_config_scroll_set_button_lock (struct libinput_device *device, enum libinput_config_scroll_button_lock_state state)
 Set the scroll button lock. More...
 
enum libinput_config_scroll_button_lock_state libinput_device_config_scroll_get_button_lock (struct libinput_device *device)
 Get the current scroll button lock state. More...
 
enum libinput_config_scroll_button_lock_state libinput_device_config_scroll_get_default_button_lock (struct libinput_device *device)
 Get the default scroll button lock state. 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...
 
int libinput_device_config_dwtp_is_available (struct libinput_device *device)
 Check if this device supports configurable disable-while-trackpointing feature. More...
 
enum libinput_config_status libinput_device_config_dwtp_set_enabled (struct libinput_device *device, enum libinput_config_dwtp_state enable)
 Enable or disable the disable-while-trackpointing feature. More...
 
enum libinput_config_dwtp_state libinput_device_config_dwtp_get_enabled (struct libinput_device *device)
 Check if the disable-while trackpointing feature is currently enabled on this device. More...
 
enum libinput_config_dwtp_state libinput_device_config_dwtp_get_default_enabled (struct libinput_device *device)
 Check if the disable-while trackpointing feature is enabled on this device by default. More...
 
int libinput_device_config_rotation_is_available (struct libinput_device *device)
 Check whether a device can have a custom rotation applied. More...
 
enum libinput_config_status libinput_device_config_rotation_set_angle (struct libinput_device *device, unsigned int degrees_cw)
 Set the rotation of a device in degrees clockwise off the logical neutral position. More...
 
unsigned int libinput_device_config_rotation_get_angle (struct libinput_device *device)
 Get the current rotation of a device in degrees clockwise off the logical neutral position. More...
 
unsigned int libinput_device_config_rotation_get_default_angle (struct libinput_device *device)
 Get the default rotation of a device in degrees clockwise off the logical neutral position. 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.

Configuration options are device dependent and not all options are supported on all devices. For all configuration options, libinput provides a call to check if a configuration option is available on a device (e.g. libinput_device_config_calibration_has_matrix())

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.

Below is a general grouping of configuration options according to device type. Note that this is a guide only and not indicative of any specific device.

Enumeration Type Documentation

◆ libinput_config_accel_profile

Since
1.1
Enumerator
LIBINPUT_CONFIG_ACCEL_PROFILE_NONE 

Placeholder for devices that don't have a configurable pointer acceleration profile.

LIBINPUT_CONFIG_ACCEL_PROFILE_FLAT 

A flat acceleration profile.

Pointer motion is accelerated by a constant (device-specific) factor, depending on the current speed.

See also
libinput_device_config_accel_set_speed
LIBINPUT_CONFIG_ACCEL_PROFILE_ADAPTIVE 

An adaptive acceleration profile.

Pointer acceleration depends on the input speed. This is the default profile for most devices.

LIBINPUT_CONFIG_ACCEL_PROFILE_CUSTOM 

A custom acceleration profile.

Device movement acceleration depends on user defined custom acceleration functions for each movement type.

See also
libinput_device_config_accel_set_points

◆ libinput_config_accel_type

Acceleration types are categories of movement by a device that may have specific acceleration functions applied.

A device always supports the LIBINPUT_ACCEL_TYPE_MOTION type (for regular pointer motion). Other types (e.g. scrolling) may be added in the future.

The special type LIBINPUT_ACCEL_TYPE_FALLBACK specifies the acceleration function to be moved for any movement produced by the device that does not have a specific acceleration type defined.

Use to specify the acceleration function type in libinput_config_accel_set_points

Each device implements a subset of those types, see a list of supported devices for each movement type definition.

See also
LIBINPUT_ACCEL_ARG_TYPE
Since
1.23
Enumerator
LIBINPUT_ACCEL_TYPE_FALLBACK 

The default acceleration type used as a fallback when other acceleration types are not provided.

LIBINPUT_ACCEL_TYPE_MOTION 

Acceleration type for regular pointer movement.

This type is always supported.

LIBINPUT_ACCEL_TYPE_SCROLL 

Acceleration type for scroll movement.

This type is supported by mouse and touchpad.

◆ libinput_config_click_method

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 to generate button events.

LIBINPUT_CONFIG_CLICK_METHOD_CLICKFINGER 

The number of fingers decides which button press to generate.

◆ libinput_config_drag_lock_state

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.

◆ libinput_config_drag_state

A config status to distinguish or set dragging on a device.

Currently implemented for tap-and-drag only, see libinput_device_config_tap_set_drag_enabled()

Since
1.2
Enumerator
LIBINPUT_CONFIG_DRAG_DISABLED 

Drag is to be disabled, or is currently disabled.

LIBINPUT_CONFIG_DRAG_ENABLED 

Drag is to be enabled, or is currently enabled.

◆ libinput_config_dwt_state

Possible states for the disable-while-typing feature.

Enumerator
LIBINPUT_CONFIG_DWT_DISABLED 
LIBINPUT_CONFIG_DWT_ENABLED 

◆ libinput_config_dwtp_state

Possible states for the disable-while-trackpointing feature.

Since
1.21
Enumerator
LIBINPUT_CONFIG_DWTP_DISABLED 
LIBINPUT_CONFIG_DWTP_ENABLED 

◆ libinput_config_middle_emulation_state

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.

◆ libinput_config_scroll_method

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.

◆ libinput_config_send_events_mode

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.

◆ libinput_config_status

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.

◆ libinput_config_tap_button_map

Since
1.5
Enumerator
LIBINPUT_CONFIG_TAP_MAP_LRM 

1/2/3 finger tap maps to left/right/middle

LIBINPUT_CONFIG_TAP_MAP_LMR 

1/2/3 finger tap maps to left/middle/right

◆ libinput_config_tap_state

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

◆ libinput_config_accel_create()

struct libinput_config_accel * libinput_config_accel_create ( enum libinput_config_accel_profile  profile)

Create an acceleration configuration of a given profile.

Note that in this version of libinput, only the LIBINPUT_CONFIG_ACCEL_PROFILE_CUSTOM profile provides configuration options. All other acceleration profiles, when applied, will merely switch the profile and reset any profile-specific options to the default values.

Parameters
profileThe profile of the newly created acceleration configuration.
Returns
The newly created acceleration configuration or NULL on error.
Warning
Unlike other structs pointer acceleration configuration is considered transient and not refcounted. Calling libinput_config_accel_destroy() will destroy the configuration.
See also
libinput_config_accel
Since
1.23

◆ libinput_config_accel_destroy()

void libinput_config_accel_destroy ( struct libinput_config_accel *  accel_config)

Destroy an acceleration configuration.

Warning
Unlike other structs pointer acceleration configuration is considered transient and not refcounted. Calling libinput_config_accel_destroy() will destroy the configuration.
Parameters
accel_configThe acceleration configuration to destroy.
See also
libinput_config_accel
Since
1.23

◆ libinput_config_accel_set_points()

enum libinput_config_status libinput_config_accel_set_points ( struct libinput_config_accel *  accel_config,
enum libinput_config_accel_type  accel_type,
double  step,
size_t  npoints,
double *  points 
)

Defines the acceleration function for a given movement type in an acceleration configuration with the profile LIBINPUT_CONFIG_ACCEL_PROFILE_CUSTOM.

Movement types are specific to each device,

See also
libinput_config_accel_type.

Each custom acceleration function is defined by n points spaced uniformly along the x-axis starting from 0 and continuing in a constant step size. There by the function is defined by the following points: (0 * step, f[0]), (1 * step, f[1]), ..., ((n - 1) * step, f[n - 1]). The x-axis represents the device-speed in device units per millisecond. The y-axis represents the pointer-speed.

It is up to the user to define those values in accordance with device DPI and screen DPI.

Parameters
accel_configThe acceleration configuration to modify.
accel_typeThe movement type to configure a custom function for.
stepThe distance between each point along the x-axis.
npointsThe number of points of the custom acceleration function.
pointsThe points' y-values of the custom acceleration function.
Returns
A config status code.
See also
libinput_config_accel
Since
1.23

◆ libinput_config_status_to_str()

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.

◆ libinput_device_config_accel_apply()

enum libinput_config_status libinput_device_config_accel_apply ( struct libinput_device device,
struct libinput_config_accel *  accel_config 
)

Apply this pointer acceleration configuration to the device.

This changes the device's pointer acceleration method to the method given in libinput_config_accel_create() and applies all other configuration settings.

Once applied, call libinput_config_accel_destroy() to destroy the configuration struct.

Parameters
deviceThe device to configure.
accel_configThe acceleration configuration.
Returns
A config status code.
See also
libinput_config_accel
Since
1.23

◆ libinput_device_config_accel_get_default_profile()

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

◆ libinput_device_config_accel_get_default_speed()

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.
See also
libinput_device_config_accel_is_available
libinput_device_config_accel_set_speed
libinput_device_config_accel_get_speed

◆ libinput_device_config_accel_get_profile()

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

◆ libinput_device_config_accel_get_profiles()

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 available on this device.
Since
1.1

◆ libinput_device_config_accel_get_speed()

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.

If the current acceleration profile is LIBINPUT_CONFIG_ACCEL_PROFILE_CUSTOM, the behavior of the device will not change but future calls to libinput_device_config_accel_get_speed() will reflect the updated speed setting.

Parameters
deviceThe device to configure
Returns
The current speed, range -1 to 1
See also
libinput_device_config_accel_is_available
libinput_device_config_accel_set_speed
libinput_device_config_accel_get_default_speed

◆ libinput_device_config_accel_is_available()

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
See also
libinput_device_config_accel_set_speed
libinput_device_config_accel_get_speed
libinput_device_config_accel_get_default_speed

◆ libinput_device_config_accel_set_profile()

enum libinput_config_status libinput_device_config_accel_set_profile ( struct libinput_device device,
enum libinput_config_accel_profile  profile 
)

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

Parameters
deviceThe device to configure
profileThe profile to set the device to.
Returns
A config status code
Since
1.1

◆ libinput_device_config_accel_set_speed()

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
See also
libinput_device_config_accel_is_available
libinput_device_config_accel_get_speed
libinput_device_config_accel_get_default_speed

◆ libinput_device_config_calibration_get_default_matrix()

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 the libinput documentation for more details.

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_matrix

◆ libinput_device_config_calibration_get_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

◆ libinput_device_config_calibration_has_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

◆ libinput_device_config_calibration_set_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

◆ libinput_device_config_click_get_default_method()

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

◆ 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

◆ libinput_device_config_click_get_methods()

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

◆ libinput_device_config_click_set_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

◆ libinput_device_config_dwt_get_default_enabled()

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

◆ 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

◆ libinput_device_config_dwt_is_available()

int libinput_device_config_dwt_is_available ( struct libinput_device device)

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

This feature is usually available on built-in touchpads and disables the touchpad while typing. See the libinput documentation 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

◆ libinput_device_config_dwt_set_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 the libinput documentation 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

◆ libinput_device_config_dwtp_get_default_enabled()

enum libinput_config_dwtp_state libinput_device_config_dwtp_get_default_enabled ( struct libinput_device device)

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

If the device does not support disable-while-trackpointing, this function returns LIBINPUT_CONFIG_DWTP_DISABLED.

Parameters
deviceThe device to configure
Returns
LIBINPUT_CONFIG_DWTP_DISABLED if disabled, LIBINPUT_CONFIG_DWTP_ENABLED if enabled.
See also
libinput_device_config_dwtp_is_available
libinput_device_config_dwtp_set_enabled
libinput_device_config_dwtp_get_enabled
Since
1.21

◆ libinput_device_config_dwtp_get_enabled()

enum libinput_config_dwtp_state libinput_device_config_dwtp_get_enabled ( struct libinput_device device)

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

If the device does not support disable-while-trackpointing, this function returns LIBINPUT_CONFIG_DWTP_DISABLED.

Parameters
deviceThe device to configure
Returns
LIBINPUT_CONFIG_DWTP_DISABLED if disabled, LIBINPUT_CONFIG_DWTP_ENABLED if enabled.
See also
libinput_device_config_dwtp_is_available
libinput_device_config_dwtp_set_enabled
libinput_device_config_dwtp_get_default_enabled
Since
1.21

◆ libinput_device_config_dwtp_is_available()

int libinput_device_config_dwtp_is_available ( struct libinput_device device)

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

This feature is usually available on Thinkpads and disables the touchpad while using the trackpoint. See the libinput documentation for details.

Parameters
deviceThe device to configure
Returns
0 if this device does not support disable-while-trackpointing, or 1 otherwise.
See also
libinput_device_config_dwtp_set_enabled
libinput_device_config_dwtp_get_enabled
libinput_device_config_dwtp_get_default_enabled
Since
1.21

◆ libinput_device_config_dwtp_set_enabled()

enum libinput_config_status libinput_device_config_dwtp_set_enabled ( struct libinput_device device,
enum libinput_config_dwtp_state  enable 
)

Enable or disable the disable-while-trackpointing feature.

When enabled, the device will be disabled while using the trackpoint and for a short period after. See the libinput documentation for details.

Note
Enabling or disabling disable-while-trackpointing may not take effect immediately.
Parameters
deviceThe device to configure
enableLIBINPUT_CONFIG_DWTP_DISABLED to disable disable-while-trackpointing, LIBINPUT_CONFIG_DWTP_ENABLED to enable
Returns
A config status code. Disabling disable-while-trackpointing on a device that does not support the feature always succeeds.
See also
libinput_device_config_dwtp_is_available
libinput_device_config_dwtp_get_enabled
libinput_device_config_dwtp_get_default_enabled
Since
1.21

◆ libinput_device_config_left_handed_get()

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

◆ 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

◆ libinput_device_config_left_handed_is_available()

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

◆ libinput_device_config_left_handed_set()

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

◆ libinput_device_config_middle_emulation_get_default_enabled()

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.

See libinput_device_config_middle_emulation_set_enabled() for more details.

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

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

See libinput_device_config_middle_emulation_set_enabled() for more details.

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

◆ libinput_device_config_middle_emulation_is_available()

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

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

See the libinput documentation for more details.

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

◆ libinput_device_config_rotation_get_angle()

unsigned int libinput_device_config_rotation_get_angle ( struct libinput_device device)

Get the current rotation of a device in degrees clockwise off the logical neutral position.

If this device does not support rotation, the return value is always 0.

Parameters
deviceThe device to configure
Returns
The angle in degrees clockwise
See also
libinput_device_config_rotation_is_available
libinput_device_config_rotation_set_angle
libinput_device_config_rotation_get_default_angle
Since
1.4

◆ libinput_device_config_rotation_get_default_angle()

unsigned int libinput_device_config_rotation_get_default_angle ( struct libinput_device device)

Get the default rotation of a device in degrees clockwise off the logical neutral position.

If this device does not support rotation, the return value is always 0.

Parameters
deviceThe device to configure
Returns
The default angle in degrees clockwise
See also
libinput_device_config_rotation_is_available
libinput_device_config_rotation_set_angle
libinput_device_config_rotation_get_angle
Since
1.4

◆ libinput_device_config_rotation_is_available()

int libinput_device_config_rotation_is_available ( struct libinput_device device)

Check whether a device can have a custom rotation applied.

Parameters
deviceThe device to configure
Returns
Non-zero if a device can be rotated, zero otherwise.
See also
libinput_device_config_rotation_set_angle
libinput_device_config_rotation_get_angle
libinput_device_config_rotation_get_default_angle
Since
1.4

◆ libinput_device_config_rotation_set_angle()

enum libinput_config_status libinput_device_config_rotation_set_angle ( struct libinput_device device,
unsigned int  degrees_cw 
)

Set the rotation of a device in degrees clockwise off the logical neutral position.

Any subsequent motion events are adjusted according to the given angle.

The angle has to be in the range of [0, 360[ degrees, otherwise this function returns LIBINPUT_CONFIG_STATUS_INVALID. If the angle is a multiple of 360 or negative, the caller must ensure the correct ranging before calling this function.

The rotation angle is applied to all motion events emitted by the device. Thus, rotating the device also changes the angle required or presented by scrolling, gestures, etc.

Parameters
deviceThe device to configure
degrees_cwThe angle in degrees clockwise
Returns
A config status code. Setting a rotation of 0 degrees on a device that does not support rotation always succeeds.
See also
libinput_device_config_rotation_is_available
libinput_device_config_rotation_get_angle
libinput_device_config_rotation_get_default_angle
Since
1.4

◆ libinput_device_config_scroll_get_button()

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

◆ libinput_device_config_scroll_get_button_lock()

enum libinput_config_scroll_button_lock_state libinput_device_config_scroll_get_button_lock ( struct libinput_device device)

Get the current scroll button lock state.

If LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not supported, or no button is set, this function returns LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED.

Note
The return value is independent of the currently selected scroll-method. For the scroll button lock 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 scroll button lock state
See also
libinput_device_config_scroll_set_button
libinput_device_config_scroll_set_button_lock
libinput_device_config_scroll_get_button_lock
libinput_device_config_scroll_get_default_button_lock

◆ 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

◆ libinput_device_config_scroll_get_default_button_lock()

enum libinput_config_scroll_button_lock_state libinput_device_config_scroll_get_default_button_lock ( struct libinput_device device)

Get the default scroll button lock state.

If LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not supported, or no button is set, this function returns LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED.

Parameters
deviceThe device to configure
Returns
The default scroll button lock state
See also
libinput_device_config_scroll_set_button
libinput_device_config_scroll_set_button_lock
libinput_device_config_scroll_get_button_lock
libinput_device_config_scroll_get_default_button_lock

◆ libinput_device_config_scroll_get_default_method()

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

◆ libinput_device_config_scroll_get_default_natural_scroll_enabled()

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_scroll_has_natural_scroll
libinput_device_config_scroll_set_natural_scroll_enabled
libinput_device_config_scroll_get_natural_scroll_enabled

◆ libinput_device_config_scroll_get_method()

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

◆ libinput_device_config_scroll_get_methods()

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

◆ libinput_device_config_scroll_get_natural_scroll_enabled()

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_scroll_has_natural_scroll
libinput_device_config_scroll_set_natural_scroll_enabled
libinput_device_config_scroll_get_default_natural_scroll_enabled

◆ libinput_device_config_scroll_has_natural_scroll()

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_scroll_set_natural_scroll_enabled
libinput_device_config_scroll_get_natural_scroll_enabled
libinput_device_config_scroll_get_default_natural_scroll_enabled

◆ libinput_device_config_scroll_set_button()

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

◆ libinput_device_config_scroll_set_button_lock()

enum libinput_config_status libinput_device_config_scroll_set_button_lock ( struct libinput_device device,
enum libinput_config_scroll_button_lock_state  state 
)

Set the scroll button lock.

If the state is LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED, the button must physically be held down for button scrolling to work. If the state is LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_ENABLED, the button is considered logically down after the first press and release sequence, and logically up after the second press and release sequence.

Parameters
deviceThe device to configure
stateThe state to set the scroll button lock to
Returns
A config status code. Disabling the scroll button lock on device that does not support button scrolling always succeeds.
See also
libinput_device_config_scroll_set_button
libinput_device_config_scroll_get_button
libinput_device_config_scroll_get_default_button

◆ libinput_device_config_scroll_set_method()

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

◆ libinput_device_config_scroll_set_natural_scroll_enabled()

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_scroll_has_natural_scroll
libinput_device_config_scroll_get_natural_scroll_enabled
libinput_device_config_scroll_get_default_natural_scroll_enabled

◆ libinput_device_config_send_events_get_default_mode()

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

◆ 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

◆ libinput_device_config_send_events_get_modes()

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

◆ libinput_device_config_send_events_set_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

◆ libinput_device_config_tap_get_button_map()

enum libinput_config_tap_button_map libinput_device_config_tap_get_button_map ( struct libinput_device device)

Get the finger number to button number mapping for tap-to-click.

The return value for a device that does not support tapping is always LIBINPUT_CONFIG_TAP_MAP_LRM.

Note
It is an application bug to call this function for devices where libinput_device_config_tap_get_finger_count() returns 0.
Parameters
deviceThe device to configure
Returns
The current finger-to-button number mapping
See also
libinput_device_config_tap_set_button_map
libinput_device_config_tap_get_default_button_map
Since
1.5

◆ libinput_device_config_tap_get_default_button_map()

enum libinput_config_tap_button_map libinput_device_config_tap_get_default_button_map ( struct libinput_device device)

Get the default finger number to button number mapping for tap-to-click.

The return value for a device that does not support tapping is always LIBINPUT_CONFIG_TAP_MAP_LRM.

Note
It is an application bug to call this function for devices where libinput_device_config_tap_get_finger_count() returns 0.
Parameters
deviceThe device to configure
Returns
The current finger-to-button number mapping
See also
libinput_device_config_tap_set_button_map
libinput_device_config_tap_get_default_button_map
Since
1.5

◆ libinput_device_config_tap_get_default_drag_enabled()

enum libinput_config_drag_state libinput_device_config_tap_get_default_drag_enabled ( struct libinput_device device)

Return whether tap-and-drag is enabled or disabled by default on this device.

Parameters
deviceThe device to check
Return values
LIBINPUT_CONFIG_DRAG_ENABLEDif tap-and-drag is enabled by default
LIBINPUT_CONFIG_DRAG_DISABLEDif tap-and-drag is disabled by default
See also
libinput_device_config_tap_drag_set_enabled
libinput_device_config_tap_drag_get_enabled
Since
1.2

◆ libinput_device_config_tap_get_default_drag_lock_enabled()

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

◆ libinput_device_config_tap_get_default_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

◆ libinput_device_config_tap_get_drag_enabled()

enum libinput_config_drag_state libinput_device_config_tap_get_drag_enabled ( struct libinput_device device)

Return whether tap-and-drag is enabled or disabled on this device.

Parameters
deviceThe device to check
Return values
LIBINPUT_CONFIG_DRAG_ENABLEDif tap-and-drag is enabled
LIBINPUT_CONFIG_DRAG_DISABLEDif tap-and-drag is disabled
See also
libinput_device_config_tap_drag_set_enabled
libinput_device_config_tap_drag_get_default_enabled
Since
1.2

◆ libinput_device_config_tap_get_drag_lock_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

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

◆ libinput_device_config_tap_get_finger_count()

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

◆ libinput_device_config_tap_set_button_map()

enum libinput_config_status libinput_device_config_tap_set_button_map ( struct libinput_device device,
enum libinput_config_tap_button_map  map 
)

Set the finger number to button number mapping for tap-to-click.

The default mapping on most devices is to have a 1, 2 and 3 finger tap to map to the left, right and middle button, respectively. A device may permit changing the button mapping but disallow specific maps. In this case LIBINPUT_CONFIG_STATUS_UNSUPPORTED is returned, the caller is expected to handle this case correctly.

Changing the button mapping may not take effect immediately, the device may wait until it is in a neutral state before applying any changes.

The mapping may be changed when tap-to-click is disabled. The new mapping takes effect when tap-to-click is enabled in the future.

Note
It is an application bug to call this function for devices where libinput_device_config_tap_get_finger_count() returns 0.
Parameters
deviceThe device to configure
mapThe new finger-to-button number mapping
Returns
A config status code. Changing the order on a device that does not support tapping always fails with LIBINPUT_CONFIG_STATUS_UNSUPPORTED.
See also
libinput_device_config_tap_get_button_map
libinput_device_config_tap_get_default_button_map
Since
1.5

◆ libinput_device_config_tap_set_drag_enabled()

enum libinput_config_status libinput_device_config_tap_set_drag_enabled ( struct libinput_device device,
enum libinput_config_drag_state  enable 
)

Enable or disable tap-and-drag on this device.

When enabled, a tap immediately followed by a finger down results in a button down event, subsequent finger motion thus triggers a drag. The button is released on finger up. See the libinput documentation for more details.

Parameters
deviceThe device to configure
enableLIBINPUT_CONFIG_DRAG_ENABLED to enable, LIBINPUT_CONFIG_DRAG_DISABLED to disable tap-and-drag
See also
libinput_device_config_tap_drag_get_enabled
libinput_device_config_tap_drag_get_default_enabled
Since
1.2

◆ libinput_device_config_tap_set_drag_lock_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 the libinput documentation for more 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

◆ libinput_device_config_tap_set_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