Debian Codegraph @

doc/user/configuration.rst

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