1LIBINPUT(4) Kernel Interfaces Manual LIBINPUT(4)
2
6 libinput - libinput-based X.Org input driver
7
9 Section "InputDevice"
10 Identifier "devname"
11 Driver "libinput"
12 Option "Device" "devpath"
13 ...
14 EndSection
15
18 This is the man page for the X input driver. If you are looking for the
19 library documentation, go to http://wayland.freedesktop.org/libin‐
20 put/doc/
21
24 libinput is an Xorg input driver based on libinput. It therefore sup‐
25 ports all input devices that libinput can handle, including most mice,
26 keyboards, tablets and touchscreens.
27 It is recommended that libinput devices are configured through the In‐
29 putClass directive (refer to xorg.conf(5)) instead of manual per-device
30 configuration. Devices configured in the xorg.conf(5) are not hot-plug
31 capable.
32
35 Please refer to xorg.conf(5) for general configuration details and for
36 options that can be used with all input drivers. This section only
37 covers configuration details specific to this driver.
38 The following driver Options are supported:
40 Option "AccelProfile" "string"
42 Sets the pointer acceleration profile to the given profile. Per‐
43 mitted values are adaptive, flat, custom. Not all devices sup‐
44 port this option or all profiles. If a profile is unsupported,
45 the default profile for this device is used. For a description
46 on the profiles and their behavior, see the libinput documenta‐
47 tion.
48 Option "AccelSpeed" "float"
50 Sets the pointer acceleration speed within the range [-1, 1].
51 This only applies to the flat or adaptive profile.
52 Option "AccelPointsFallback" "string"
54 Option "AccelPointsMotion" "string"
55 Option "AccelPointsScroll" "string"
56 Sets the points of the Fallback/Motion/Scroll acceleration func‐
57 tions. The string must be a space-separated list of floating
58 point non-negative numbers, e.g. "0.0 1.0 2.4 2.5". This only
59 applies to the custom profile. See section CUSTOM ACCELERATION
60 PROFILE
61 Option "AccelStepFallback" "float"
63 Option "AccelStepMotion" "float"
64 Option "AccelStepScroll" "float"
65 Sets the step between the points of the Fallback/Motion/Scroll
66 acceleration functions. When a step of 0.0 is provided, libin‐
67 put's Fallback acceleration function is used. This only applies
68 to the custom profile. See section CUSTOM ACCELERATION PROFILE
69 Option "ButtonMapping" "string"
71 Sets the logical button mapping for this device, see XSetPoint‐
72 erMapping(3). The string must be a space-separated list of but‐
73 ton mappings in the order of the logical buttons on the device,
74 starting with button 1. The default mapping is "1 2 3 ... 32".
75 A mapping of 0 deactivates the button. Multiple buttons can have
76 the same mapping. Invalid mapping strings are discarded and the
77 default mapping is used for all buttons. Buttons not specified
78 in the user's mapping use the default mapping. See section BUT‐
79 TON MAPPING for more details.
80 Option "CalibrationMatrix" "string"
82 A string of 9 space-separated floating point numbers, in the or‐
83 der "a b c d e f g h i". Sets the calibration matrix to the 3x3
84 matrix where the first row is (abc), the second row is (def) and
85 the third row is (ghi).
86 Option "ClickMethod" "string"
88 Enables a click method. Permitted values are none, buttonareas,
89 clickfinger. Not all devices support all methods, if an option
90 is unsupported, the default click method for this device is
91 used.
92 Option "DisableWhileTyping" "bool"
94 Indicates if the touchpad should be disabled while typing on the
95 keyboard (this does not apply to modifier keys such as Ctrl or
96 Alt).
97 Option "Device" "string"
99 Specifies the device through which the device can be accessed.
100 This will generally be of the form "/dev/input/eventX", where X
101 is some integer. When using InputClass directives, this option
102 is set by the server. The mapping from device node to hardware
103 is system-dependent. Property: "Device Node" (read-only).
104 Option "DragLockButtons" "L1 B1 L2 B2 ..."
106 Sets "drag lock buttons" that simulate a button logically down
107 even when it has been physically released. To logically release
108 a locked button, a second click of the same button is required.
109 If the option is a single button number, that button acts as the
111 "meta" locking button for the next button number. See section
112 BUTTON DRAG LOCK for details.
113 If the option is a list of button number pairs, the first number
115 of each number pair is the lock button, the second number the
116 logical button number to be locked. See section BUTTON DRAG LOCK
117 for details.
118 For both meta and button pair configuration, the button numbers
120 are device button numbers, i.e. the ButtonMapping applies after
121 drag lock.
122 Option "HighResolutionWheelScrolling" "bool"
124 Disables high-resolution wheel scroll events, enabled by de‐
125 fault. When enabled, the driver forwards only high-resolution
126 wheel scroll events from libinput. When disabled, the driver
127 forwards legacy wheel scroll events instead.
128 Option "HorizontalScrolling" "bool"
130 Enables or disables horizontal scrolling. When disabled, this
131 driver will discard any horizontal scroll events from libinput.
132 This does not disable horizontal scroll events from libinput; it
133 merely discards the horizontal axis from any scroll events. De‐
134 fault is enabled.
135 Option "LeftHanded" "bool"
137 Enables left-handed button orientation, i.e. swapping left and
138 right buttons.
139 Option "MiddleEmulation" "bool"
141 Enables middle button emulation. When enabled, pressing the left
142 and right buttons simultaneously produces a middle mouse button
143 click.
144 Option "NaturalScrolling" "bool"
146 Enables or disables natural scrolling behavior.
147 Option "RotationAngle" "float"
149 Sets the rotation angle of the device to the given angle, in de‐
150 grees clockwise. The angle must be between 0.0 (inclusive) and
151 360.0 (exclusive).
152 Option "ScrollButton" "int"
154 Designates a button as scroll button. If the ScrollMethod is
155 button and the button is logically down, x/y axis movement is
156 converted into scroll events.
157 Option "ScrollButtonLock" "bool"
159 Enables or disables the scroll button lock. If enabled, the
160 ScrollButton is considered logically down after the first click
161 and remains down until the second click of that button. If dis‐
162 abled (the default), the ScrollButton button is considered logi‐
163 cally down while held down and up once physically released.
164 Option "ScrollMethod" "string"
166 Enables a scroll method. Permitted values are none, twofinger,
167 edge, button. Not all devices support all options, if an option
168 is unsupported, the default scroll option for this device is
169 used.
170 Option "ScrollPixelDistance" "int"
172 Sets the movement distance, in "pixels", required to trigger one
173 logical wheel click. This option only applies to the scroll
174 methods twofinger, edge, button. See section SCROLL PIXEL DIS‐
175 TANCE for more details.
176 Option "SendEventsMode" "(disabled|enabled|disabled-on-external-mouse)"
178 Sets the send events mode to disabled, enabled, or "disable when
179 an external mouse is connected".
180 Option "TabletToolPressureCurve" "x0/y0 x1/y1 x2/y2 x3/y3"
182 Set the pressure curve for a tablet stylus to the bezier formed
183 by the four points. The respective x/y coordinate must be in the
184 [0.0, 1.0] range. For more information see section TABLET STYLUS
185 PRESSURE CURVE.
186 Option "TabletToolAreaRatio" "w:h"
188 Sets the area ratio for a tablet tool. The area always starts at
189 the origin (0/0) and expands to the largest available area with
190 the specified aspect ratio. Events outside this area are cropped
191 to the area. The special value "default" is used for the default
192 mapping (i.e. the device-native mapping). For more information
193 see section TABLET TOOL AREA RATIO.
194 Option "Tapping" "bool"
196 Enables or disables tap-to-click behavior.
197 Option "TappingButtonMap" "(lrm|lmr)"
199 Set the button mapping for 1/2/3-finger taps to left/right/mid‐
200 dle or left/middle/right, respectively.
201 Option "TappingDrag" "bool"
203 Enables or disables drag during tapping behavior ("tap-and-
204 drag"). When enabled, a tap followed by a finger held down
205 causes a single button down only, all motions of that finger
206 thus translate into dragging motion. Tap-and-drag requires op‐
207 tion Tapping to be enabled.
208 Option "TappingDragLock" "bool"
210 Enables or disables drag lock during tapping behavior. When en‐
211 abled, a finger up during tap-and-drag will not immediately re‐
212 lease the button. If the finger is set down again within the
213 timeout, the dragging process continues.
214 For all options, the options are only parsed if the device supports
216 that configuration option. For all options, the default value is the
217 one used by libinput. On configuration failure, the default value is
218 applied.
219
222 libinput exports runtime-configurable options as properties. If a prop‐
223 erty listed below is not available, the matching configuration option
224 is not available on the device. This however does not imply that the
225 feature is not available on the device. The following properties are
226 provided by the libinput driver.
227 libinput Accel Profiles Available
229 3 boolean values (8 bit, 0 or 1), in order "adaptive", "flat",
230 "custom". Indicates which acceleration profiles are available
231 on this device.
232 libinput Accel Profile Enabled
234 3 boolean values (8 bit, 0 or 1), in order "adaptive", "flat",
235 "custom". Indicates which acceleration profile is currently en‐
236 abled on this device.
237 libinput Accel Speed
239 1 32-bit float value, defines the pointer speed. Value range -1,
240 1. This only applies to the flat or adaptive profile.
241 libinput Accel Custom Fallback Points
243 libinput Accel Custom Motion Points
244 libinput Accel Custom Scroll Points
245 A space-separated list of 32-bit floating point non-negative
246 numbers, e.g. "0.0 1.0 2.4 2.5". Sets the points of the Fall‐
247 back/Motion/Scroll acceleration functions. This only applies to
248 the custom profile. See section CUSTOM ACCELERATION PROFILE
249 libinput Accel Custom Fallback Step
251 libinput Accel Custom Motion Step
252 libinput Accel Custom Scroll Step
253 1 32-bit float value, sets the step between the points of the
254 Fallback/Motion/Scroll acceleration functions. When a step of
255 0.0 is provided, libinput's Fallback acceleration function is
256 used. This only applies to the custom profile. See section
257 CUSTOM ACCELERATION PROFILE
258 libinput Button Scrolling Button
260 1 32-bit value. Sets the button number to use for button
261 scrolling. This setting is independent of the scroll method, to
262 enable button scrolling the method must be set to button-
263 scrolling and a valid button must be set.
264 libinput Button Scrolling Button Lock Enabled
266 1 boolean value. If true, the scroll button lock is enabled.
267 This setting is independent of the scroll method or the scroll
268 button, to enable button scrolling the method must be set to
269 button-scrolling and a valid button must be set.
270 libinput Calibration Matrix
272 9 32-bit float values, representing a 3x3 calibration matrix,
273 order is row 1, row 2, row 3
274 libinput Click Methods Available
276 2 boolean values (8 bit, 0 or 1), in order "buttonareas",
277 "clickfinger". Indicates which click methods are available on
278 this device.
279 libinput Click Methods Enabled
281 2 boolean values (8 bit, 0 or 1), in order "buttonareas",
282 "clickfinger". Indicates which click methods are enabled on
283 this device.
284 libinput Drag Lock Buttons
286 Either one 8-bit value specifying the meta drag lock button, or
287 a list of button pairs. See section BUTTON DRAG LOCK for de‐
288 tails.
289 libinput High Resolution Wheel Scroll Enabled
291 1 boolean value (8 bit, 0 or 1). Indicates whether high-resolu‐
292 tion wheel scroll events are enabled or not.
293 libinput Horizontal Scroll Enabled
295 1 boolean value (8 bit, 0 or 1). Indicates whether horizontal
296 scrolling events are enabled or not.
297 libinput Left Handed Enabled
299 1 boolean value (8 bit, 0 or 1). Indicates if left-handed mode
300 is enabled or disabled.
301 libinput Middle Emulation Enabled
303 1 boolean value (8 bit, 0 or 1). Indicates if middle emulation
304 is enabled or disabled.
305 libinput Natural Scrolling Enabled
307 1 boolean value (8 bit, 0 or 1). 1 enables natural scrolling
308 libinput Rotation Angle
310 1 32-bit float value [0.0 to 360.0). Sets the rotation angle of
311 the device, clockwise of its natural neutral position.
312 libinput Scroll Methods Available
314 3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge",
315 "button". Indicates which scroll methods are available on this
316 device.
317 libinput Scroll Method Enabled
319 3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge",
320 "button". Indicates which scroll method is currently enabled on
321 this device.
322 libinput Scroll Pixel Distance
324 1 32-bit value (nonzero, with additional implementation-defined
325 range checks). Changes the movement distance required to trig‐
326 ger one logical wheel click.
327 libinput Send Events Modes Available
329 2 boolean values (8 bit, 0 or 1), in order "disabled" and "dis‐
330 abled-on-external-mouse". Indicates which send-event modes are
331 available on this device.
332 libinput Send Events Mode Enabled
334 2 boolean values (8 bit, 0 or 1), in order "disabled" and "dis‐
335 abled-on-external-mouse". Indicates which send-event modes is
336 currently enabled on this device.
337 libinput Tablet Tool Pressurecurve
339 4 32-bit float values [0.0 to 1.0]. See section TABLET TOOL
340 PRESSURE CURVE
341 libinput Tablet Tool Area Ratio
343 2 32-bit values, corresponding to width and height. Special
344 value 0, 0 resets to the default ratio. See section TABLET TOOL
345 AREA RATIO for more information.
346 libinput Tapping Enabled
348 1 boolean value (8 bit, 0 or 1). 1 enables tapping
349 libinput Tapping Button Mapping Enabled
351 2 boolean value (8 bit, 0 or 1), in order "lrm" and "lmr". Indi‐
352 cates which button mapping is currently enabled on this device.
353 libinput Tapping Drag Lock Enabled
355 1 boolean value (8 bit, 0 or 1). 1 enables drag lock during tap‐
356 ping
357 libinput Disable While Typing Enabled
359 1 boolean value (8 bit, 0 or 1). Indicates if disable while typ‐
360 ing is enabled or disabled.
361 Most properties have a libinput <property name> Default equivalent that
363 indicates the default value for this setting on this device.
364
367 X clients receive events with logical button numbers, where 1, 2, 3 are
368 usually interpreted as left, middle, right and logical buttons 4, 5, 6,
369 7 are usually interpreted as scroll up, down, left, right. The fourth
370 and fifth physical buttons on a device will thus send logical buttons 8
371 and 9. The ButtonMapping option adjusts the logical button mapping, it
372 does not affect how a physical button is mapped to a logical button.
373 Traditionally, a device was set to left-handed button mode by applying
375 a button mapping of "3 2 1 ..." On systems using the libinput Xorg in‐
376 put driver it is recommended to use the LeftHanded option instead.
377 The libinput Xorg input driver does not use the button mapping after
379 setup. Use XSetPointerMapping(3) to modify the button mapping at run‐
380 time.
381
384 Button drag lock holds a button logically down even when the button it‐
385 self has been physically released since. Button drag lock comes in two
386 modes.
387 If in "meta" mode, a meta button click activates drag lock for the next
389 button press of any other button. A button click in the future will
390 keep that button held logically down until a subsequent click of that
391 same button. The meta button events themselves are discarded. A sepa‐
392 rate meta button click is required each time a drag lock should be ac‐
393 tivated for a button in the future.
394 If in "pairs" mode, each button can be assigned a target locking but‐
396 ton. On button click, the target lock button is held logically down
397 until the next click of the same button. The button events themselves
398 are discarded and only the target button events are sent.
399 This feature is provided by this driver, not by libinput.
401
404 The pressure curve affects how stylus pressure is reported. By default,
405 the hardware pressure is reported as-is. By setting a pressure curve,
406 the feel of the stylus can be adjusted to be more like e.g. a pencil or
407 a brush.
408 The pressure curve is a cubic Bezier curve, drawn within a normalized
410 range of 0.0 to 1.0 between the four points provided. This normalized
411 range is applied to the tablet's pressure input so that the highest
412 pressure maps to 1.0. The points must have increasing x coordinates, if
413 x0 is larger than 0.0 all pressure values lower than x0 are equivalent
414 to y0. If x3 is less than 1.0, all pressure values higher than x3 are
415 equivalent to y3.
416 The input for a linear curve (default) is "0.0/0.0 0.0/0.0 1.0/1.0
418 1.0/1.0"; a slightly depressed curve (firmer) might be "0.0/0.0
419 0.05/0.0 1.0/0.95 1.0/1.0"; a slightly raised curve (softer) might be
420 "0.0/0.0 0.0/0.05 0.95/1.0 1.0/1.0".
421 This feature is provided by this driver, not by libinput.
423
426 By default, a tablet tool can access the whole sensor area and the
427 tablet area is mapped to the available screen area. For external
428 tablets like the Wacom Intuos series, the height:width ratio of the
429 tablet may be different to that of the monitor, causing the skew of in‐
430 put data.
431 To avoid this skew of input data, an area ratio may be set to match the
433 ratio of the screen device. For example, a ratio of 4:3 will reduce the
434 available area of the tablet to the largest available area with a ratio
435 of 4:3. Events within this area will scale to the tablet's announced
436 axis range, the area ratio is thus transparent to the X server. Any
437 events outside this area will send events equal to the maximum value of
438 that axis. The area always starts at the device's origin in it's cur‐
439 rent rotation, i.e. it takes left-handed-ness into account.
440 This feature is provided by this driver, not by libinput.
442
445 The X server does not support per-pixel scrolling but it does support
446 smooth scrolling. All scroll events however are based around a logical
447 unit of scrolling (traditionally corresponding to a wheel click). It
448 is thus not possible to scroll by 10 pixels, but it is possible for a
449 driver to scroll by 1/10th of a logical wheel click.
450 libinput provides scroll data in pixels. The ScrollPixelDistance option
452 defines the amount of movement equivalent to one wheel click. For exam‐
453 ple, a value of 50 means the user has to move a finger by 50 pixels to
454 generate one logical click event and each pixel is 1/50th of a wheel
455 click.
456
459 The custom pointer acceleration profile gives users full control over
460 the acceleration behavior at different speeds. libinput exposes an ac‐
461 celeration function f(x) where the x-axis is the device speed in device
462 units per millisecond and the y-axis is the pointer speed.
463 The custom acceleration function is defined using n points which are
465 spaced uniformly along the x-axis, starting from 0 and continuing in
466 constant steps. Thus the points defining the custom function are:
467 (0 * step, f[0]), (1 * step, f[1]), ..., ((n-1) * step, f[n-1])
468 When a velocity value does not lie exactly on those points, a linear
469 interpolation/extrapolation of the two closest points will be calcu‐
470 lated.
471 There are 3 custom acceleration function, which are used for different
473 movement types:
474 ┌──────────────┬──────────────────────────────────┬──────────────────┐
476 │Movement type │ Uses │ supported by │
477 ├──────────────┼──────────────────────────────────┼──────────────────┤
478 │Fallback │ Catch-all default movement type │ All devices │
479 ├──────────────┼──────────────────────────────────┼──────────────────┤
480 │Motion │ Used for pointer motion │ All devices │
481 ├──────────────┼──────────────────────────────────┼──────────────────┤
482 │Scroll │ Used for scroll movement │ Mouse, Touchpad │
483 └──────────────┴──────────────────────────────────┴──────────────────┘
484 See libinput library documentation of more details: https://way‐
485 land.freedesktop.org/libinput/doc/latest/pointer-acceleration.html#the-
486 custom-acceleration-profile
487
490 This driver does not work with Option "Device" set to an event node in
491 /dev/input/by-id and /dev/input/by-path. This can be usually be worked
492 by using Section "InputClass" with an appropriate Match* statement in
493 the xorg.conf(5).
494 This driver does not know about the display pixel density and submits
496 motion events assuming an approximate display density of 96dpi. On
497 high-dpi screens this results in a slower physical motion of the cursor
498 (a one-pixel movement is a smaller physical movement on the screen).
499 This can make interaction with the desktop difficult.
500 Option "DPIScaleFactor" float
502 This is a temporary solution. The factor should be set to the
503 approximate ratio of the host display compared to the default
504 96dpi. For example, a display with 200dpi should set a factor of
505 2.0.
506 If set, x/y motion will be unconditionally multiplied by this factor,
508 resulting in faster movement of the cursor. Note that this may make
509 some pixels unadressable and should be used with caution.
510 This option is a temporary solution. It may be removed in any future
512 update of this driver.
513
516 Peter Hutterer
517
519 Xorg(1), xorg.conf(5), Xserver(1), X(7)
5201.4.0 xf86-input-libinput LIBINPUT(4)