| 1 |
.. _config_options: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Configuration options |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
Below is a list of configurable options exposed to the users. |
| 8 |
|
| 9 |
.. contents:: |
| 10 |
:depth: 1 |
| 11 |
:local: |
| 12 |
|
| 13 |
|
| 14 |
.. hint:: Not all configuration options are available on all devices. Use |
| 15 |
:ref:`libinput list-devices <libinput-list-devices>` to show the |
| 16 |
configuration options for local devices. |
| 17 |
|
| 18 |
libinput's configuration interface is available to the caller only, not |
| 19 |
directly to the user. Thus it is the responsibility of the caller to expose |
| 20 |
the various options and how these options are exposed. For example, the |
| 21 |
`xf86-input-libinput driver <https://gitlab.freedesktop.org/xorg/driver/xf86-input-libinput/>`_ |
| 22 |
exposes the options through X Input device properties and `xorg.conf.d |
| 23 |
<https://linux.die.net/man/5/xorg.conf.d>`_ options. See the `libinput(4) |
| 24 |
<https://www.mankier.com/4/libinput>`_ man page for more details. |
| 25 |
|
| 26 |
|
| 27 |
------------------------------------------------------------------------------ |
| 28 |
Tap-to-click |
| 29 |
------------------------------------------------------------------------------ |
| 30 |
|
| 31 |
See :ref:`tapping` for details on how this feature works. Configuration |
| 32 |
options exposed by libinput are: |
| 33 |
|
| 34 |
- how many tapping fingers are supported by this device |
| 35 |
- a toggle to enable/disable tapping |
| 36 |
- a toggle to enable/disable tap-and-drag, see :ref:`tapndrag`. |
| 37 |
- a toggle to enable/disable tap-and-drag drag lock, see :ref:`tapndrag` |
| 38 |
- The default order is 1, 2, 3 finger tap mapping to left, right, middle |
| 39 |
click, respectively. This order can be changed to left, middle, right click, |
| 40 |
respectively. |
| 41 |
|
| 42 |
Tapping is usually available on touchpads and the touchpad part of external |
| 43 |
graphics tablets. Tapping is usually **not** available on touch screens, |
| 44 |
for those devices it is expected to be implemented by the toolkit. |
| 45 |
|
| 46 |
------------------------------------------------------------------------------ |
| 47 |
Three-finger drag |
| 48 |
------------------------------------------------------------------------------ |
| 49 |
|
| 50 |
Three-finger drag allows emulates the mouse button down while three fingers |
| 51 |
are down on a touchpad without the need to press a physical button or use |
| 52 |
:ref:`tapndrag`. See :ref:`drag_3fg` for details on how this feature works. |
| 53 |
|
| 54 |
Three-finger drag is usually available on touchpads and the touchpad part of |
| 55 |
external graphics tablets. Three-finger drag is usually **not** available on |
| 56 |
touch screens, for those devices it is expected to be implemented by the |
| 57 |
toolkit. |
| 58 |
|
| 59 |
------------------------------------------------------------------------------ |
| 60 |
Send Events Mode |
| 61 |
------------------------------------------------------------------------------ |
| 62 |
|
| 63 |
The Send Events Mode is libinput's terminology for disabling a device. It is |
| 64 |
more precise in that the device only stops sending events but may not get |
| 65 |
fully disabled. For example, disabling the touchpad on a |
| 66 |
:ref:`Lenovo T440 and similar <t440_support>` leaves the top software |
| 67 |
buttons enabled for the trackpoint. Available options are |
| 68 |
**enabled** (send events normally), **disabled** ( do not send events), |
| 69 |
**disabled on external mouse** (disable the device while an external mouse |
| 70 |
is plugged in). |
| 71 |
|
| 72 |
|
| 73 |
.. _config_pointer_acceleration: |
| 74 |
|
| 75 |
------------------------------------------------------------------------------ |
| 76 |
Pointer acceleration |
| 77 |
------------------------------------------------------------------------------ |
| 78 |
|
| 79 |
Pointer acceleration is a function to convert input deltas to output deltas, |
| 80 |
usually based on the movement speed of the device, see |
| 81 |
:ref:`pointer-acceleration` for details. |
| 82 |
|
| 83 |
Pointer acceleration is normalized into a [-1, 1] range, where -1 is |
| 84 |
"slowest" and 1 is "fastest". Most devices use a default speed of 0. |
| 85 |
|
| 86 |
The pointer acceleration profile defines **how** the input deltas are |
| 87 |
converted, see :ref:`ptraccel-profiles`. Most devices have their default |
| 88 |
profile (usually called "adaptive") and a "flat" profile. The flat profile |
| 89 |
does not apply any acceleration. |
| 90 |
|
| 91 |
------------------------------------------------------------------------------ |
| 92 |
Scrolling |
| 93 |
------------------------------------------------------------------------------ |
| 94 |
|
| 95 |
"Natural scrolling" is the terminology for moving the content in the |
| 96 |
direction of scrolling, i.e. moving the wheel or fingers down moves the page |
| 97 |
down. Traditional scrolling moves the content in the opposite direction. |
| 98 |
Natural scrolling can be turned on or off, it is usually off by default. |
| 99 |
|
| 100 |
The scroll method defines how to trigger scroll events. On touchpads |
| 101 |
libinput provides two-finger scrolling and edge scrolling. Two-finger |
| 102 |
scrolling converts a movement with two fingers to a series of scroll events. |
| 103 |
Edge scrolling converts a movement with one finger along the right or bottom |
| 104 |
edge of the touchpad into a series of scroll events. |
| 105 |
|
| 106 |
On other libinput provides button-scrolling - movement of the device while |
| 107 |
the designated scroll button is down is converted to scroll events. The |
| 108 |
button used for scrolling is configurable. |
| 109 |
|
| 110 |
The scroll method can be chosen or disabled altogether but most devices only |
| 111 |
support a subset of available scroll methods. libinput's default is |
| 112 |
two-finger scrolling for multi-touch touchpads, edge scrolling for |
| 113 |
single-touch touchpads. On tracksticks, button scrolling is enabled by |
| 114 |
default. |
| 115 |
|
| 116 |
See :ref:`scrolling` for more details on how the scroll methods work. |
| 117 |
|
| 118 |
------------------------------------------------------------------------------ |
| 119 |
Left-handed Mode |
| 120 |
------------------------------------------------------------------------------ |
| 121 |
|
| 122 |
Left-handed mode switches the device's functionality to be more |
| 123 |
accommodating for left-handed users. On mice this usually means swapping the |
| 124 |
left and right mouse button, on tablets this allows the tablet to be used |
| 125 |
upside-down to present the pad buttons for the non-dominant right hand. Not |
| 126 |
all devices have left-handed mode. |
| 127 |
|
| 128 |
Left-handed mode can be enabled or disabled and is disabled by default. |
| 129 |
|
| 130 |
------------------------------------------------------------------------------ |
| 131 |
Middle Button Emulation |
| 132 |
------------------------------------------------------------------------------ |
| 133 |
|
| 134 |
Middle button emulation converts a simultaneous left and right button click |
| 135 |
into a middle button. The emulation can be enabled or disabled. Middle |
| 136 |
button emulation is usually enabled when the device does not provide a |
| 137 |
middle button. |
| 138 |
|
| 139 |
------------------------------------------------------------------------------ |
| 140 |
Click method |
| 141 |
------------------------------------------------------------------------------ |
| 142 |
|
| 143 |
The click method defines how button events are triggered on a :ref:`clickpad |
| 144 |
<clickpad_softbuttons>`. When set to button areas, the bottom area of the |
| 145 |
touchpad is divided into a left, middle and right button area. When set to |
| 146 |
clickfinger, the number of fingers on the touchpad decide the button type. |
| 147 |
Clicking with 1, 2, 3 fingers triggers a left, right, or middle click, |
| 148 |
respectively. The default click method is software button areas. Click |
| 149 |
methods are usually only available on :ref:`clickpads |
| 150 |
<clickpad_softbuttons>`. |
| 151 |
|
| 152 |
------------------------------------------------------------------------------ |
| 153 |
Disable while typing |
| 154 |
------------------------------------------------------------------------------ |
| 155 |
|
| 156 |
DWT is the most generic form of palm detection on touchpad. While the user |
| 157 |
is typing on an internal keyboard the touchpad is disabled, the touchpad |
| 158 |
is enabled again after a timeout. See :ref:`disable-while-typing` for more |
| 159 |
info. |
| 160 |
|
| 161 |
Disable-while-typing can be enabled or disabled, it is enabled by default on |
| 162 |
most touchpads. |
| 163 |
|
| 164 |
------------------------------------------------------------------------------ |
| 165 |
Disable while trackpointing |
| 166 |
------------------------------------------------------------------------------ |
| 167 |
|
| 168 |
DWTP is a form of palm detecion for devices that have a trackpoint (like |
| 169 |
Thinkpads). While the user is using the trackpoint, the touchpad is disabled, |
| 170 |
being enabled again after a timeout. See :ref:`disable-while-trackpointing` for |
| 171 |
more info. |
| 172 |
|
| 173 |
Disable-while-trackpointing can be enabled or disabled, it is enabled by |
| 174 |
default. |
| 175 |
|
| 176 |
------------------------------------------------------------------------------ |
| 177 |
Calibration |
| 178 |
------------------------------------------------------------------------------ |
| 179 |
|
| 180 |
Calibration is available for some direct-input devices (touch screens, |
| 181 |
graphics tablets, etc.). The purpose of calibration is to ensure the input |
| 182 |
lines up with the output and the configuration data is a transformation |
| 183 |
matrix. It is thus not expected that the user sets this option. The desktop |
| 184 |
environment should provide an interface for this. |
| 185 |
|
| 186 |
------------------------------------------------------------------------------ |
| 187 |
Rotation |
| 188 |
------------------------------------------------------------------------------ |
| 189 |
|
| 190 |
The device rotation applies a corrective angle to relative input events, |
| 191 |
allowing the device to be used e.g. sideways or upside-down. For example, a |
| 192 |
trackball may be used in a 90° rotated position for accessibility reasons - |
| 193 |
such a rotated position allows triggering the buttons with the thumb or |
| 194 |
the non-dominant hand. |
| 195 |
|
| 196 |
Note that where a device rotation is higher than 160 but less than 200 degrees, |
| 197 |
the direction of wheels is also inverted. For all other angles, the wheel |
| 198 |
direction is left as-is. |
| 199 |
|
| 200 |
.. _config-tablet-pressure-range: |
| 201 |
|
| 202 |
------------------------------------------------------------------------------ |
| 203 |
Tablet tool pressure range |
| 204 |
------------------------------------------------------------------------------ |
| 205 |
|
| 206 |
The pressure range on a :ref:`Tablet tool <tablet-tools>` can be reduced |
| 207 |
from the full available hardware range to a subset of that range. The effect |
| 208 |
of this is that the tablet will not register pressure below the given |
| 209 |
the given threshold is met, and will reach the maximum logical pressure |
| 210 |
before the maximum hardware-supported pressure is reached. |
| 211 |
|
| 212 |
See :ref:`tablet-pressure-range` for more info. |
| 213 |
|
| 214 |
.. _config-tablet-eraser-buttons: |
| 215 |
|
| 216 |
------------------------------------------------------------------------------ |
| 217 |
Tablet tool eraser buttons |
| 218 |
------------------------------------------------------------------------------ |
| 219 |
|
| 220 |
On many contemporary :ref:`Tablet tools <tablet-tools>` one button is hardcoded |
| 221 |
in firmware to emulate an eraser. This button can be remapped to provide |
| 222 |
a normal stylus button instead. |
| 223 |
|
| 224 |
See :ref:`tablet-eraser-button` for more info. |
| 225 |
|
| 226 |
------------------------------------------------------------------------------ |
| 227 |
Area configuration |
| 228 |
------------------------------------------------------------------------------ |
| 229 |
|
| 230 |
Area configuration is available for some indirect input devices such as |
| 231 |
graphics tablets. This configuration allows reducing the active area of |
| 232 |
such a device to a subset of the physically possible area. |
| 233 |
|
| 234 |
An example use-case for this is to match the aspect ratio of the device to that |
| 235 |
of the screen. |
| 236 |
|
| 237 |
See :ref:`tablet-area` for more info. |