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. Option ccel‐
52 PointsFallback" "string" Sets the points of the Fallback accel‐
53 eration function, (see the libinput documentation). The string
54 must be a space-separated list of floating point non-negative
55 numbers, e.g. "0.0 1.0 2.4 2.5". This only applies to the cus‐
56 tom profile. Option ccelStepFallback" "float" Sets the step be‐
57 tween the points of the Fallback acceleration function, (see the
58 libinput documentation). When a step of 0.0 is provided, libin‐
59 put's default Fallback acceleration function is used. This only
60 applies to the custom profile. Option ccelPointsMotion"
61 "string" Equivalent to AccelPointsFallback but applies to the
62 Motion acceleration function. Option ccelStepMotion" "float"
63 Equivalent to AccelStepFallback but applies to the Motion accel‐
64 eration function. Option ccelPointsScroll" "string" Equivalent
65 to AccelPointsFallback but applies to the Scroll acceleration
66 function. Option ccelStepScroll" "float" Equivalent to Accel‐
67 StepFallback but applies to the Scroll acceleration function.
68 Option "ButtonMapping" "string"
70 Sets the logical button mapping for this device, see XSetPoint‐
71 erMapping(3). The string must be a space-separated list of but‐
72 ton mappings in the order of the logical buttons on the device,
73 starting with button 1. The default mapping is "1 2 3 ... 32".
74 A mapping of 0 deactivates the button. Multiple buttons can have
75 the same mapping. Invalid mapping strings are discarded and the
76 default mapping is used for all buttons. Buttons not specified
77 in the user's mapping use the default mapping. See section BUT‐
78 TON MAPPING for more details.
79 Option "CalibrationMatrix" "string"
81 A string of 9 space-separated floating point numbers, in the or‐
82 der "a b c d e f g h i". Sets the calibration matrix to the 3x3
83 matrix where the first row is (abc), the second row is (def) and
84 the third row is (ghi).
85 Option "ClickMethod" "string"
87 Enables a click method. Permitted values are none, buttonareas,
88 clickfinger. Not all devices support all methods, if an option
89 is unsupported, the default click method for this device is
90 used.
91 Option "DisableWhileTyping" "bool"
93 Indicates if the touchpad should be disabled while typing on the
94 keyboard (this does not apply to modifier keys such as Ctrl or
95 Alt).
96 Option "Device" "string"
98 Specifies the device through which the device can be accessed.
99 This will generally be of the form "/dev/input/eventX", where X
100 is some integer. When using InputClass directives, this option
101 is set by the server. The mapping from device node to hardware
102 is system-dependent. Property: "Device Node" (read-only).
103 Option "DragLockButtons" "L1 B1 L2 B2 ..."
105 Sets "drag lock buttons" that simulate a button logically down
106 even when it has been physically released. To logically release
107 a locked button, a second click of the same button is required.
108 If the option is a single button number, that button acts as the
110 "meta" locking button for the next button number. See section
111 BUTTON DRAG LOCK for details.
112 If the option is a list of button number pairs, the first number
114 of each number pair is the lock button, the second number the
115 logical button number to be locked. See section BUTTON DRAG LOCK
116 for details.
117 For both meta and button pair configuration, the button numbers
119 are device button numbers, i.e. the ButtonMapping applies after
120 drag lock.
121 Option "HighResolutionWheelScrolling" "bool"
123 Disables high-resolution wheel scroll events, enabled by de‐
124 fault. When enabled, the driver forwards only high-resolution
125 wheel scroll events from libinput. When disabled, the driver
126 forwards legacy wheel scroll events instead.
127 Option "HorizontalScrolling" "bool"
129 Enables or disables horizontal scrolling. When disabled, this
130 driver will discard any horizontal scroll events from libinput.
131 This does not disable horizontal scroll events from libinput; it
132 merely discards the horizontal axis from any scroll events. De‐
133 fault is enabled.
134 Option "LeftHanded" "bool"
136 Enables left-handed button orientation, i.e. swapping left and
137 right buttons.
138 Option "MiddleEmulation" "bool"
140 Enables middle button emulation. When enabled, pressing the left
141 and right buttons simultaneously produces a middle mouse button
142 click.
143 Option "NaturalScrolling" "bool"
145 Enables or disables natural scrolling behavior.
146 Option "RotationAngle" "float"
148 Sets the rotation angle of the device to the given angle, in de‐
149 grees clockwise. The angle must be between 0.0 (inclusive) and
150 360.0 (exclusive).
151 Option "ScrollButton" "int"
153 Designates a button as scroll button. If the ScrollMethod is
154 button and the button is logically down, x/y axis movement is
155 converted into scroll events.
156 Option "ScrollButtonLock" "bool"
158 Enables or disables the scroll button lock. If enabled, the
159 ScrollButton is considered logically down after the first click
160 and remains down until the second click of that button. If dis‐
161 abled (the default), the ScrollButton button is considered logi‐
162 cally down while held down and up once physically released.
163 Option "ScrollMethod" "string"
165 Enables a scroll method. Permitted values are none, twofinger,
166 edge, button. Not all devices support all options, if an option
167 is unsupported, the default scroll option for this device is
168 used.
169 Option "ScrollPixelDistance" "int"
171 Sets the movement distance, in "pixels", required to trigger one
172 logical wheel click. This option only applies to the scroll
173 methods twofinger, edge, button. See section SCROLL PIXEL DIS‐
174 TANCE for more details.
175 Option "SendEventsMode" "(disabled|enabled|disabled-on-external-mouse)"
177 Sets the send events mode to disabled, enabled, or "disable when
178 an external mouse is connected".
179 Option "TabletToolPressureCurve" "x0/y0 x1/y1 x2/y2 x3/y3"
181 Set the pressure curve for a tablet stylus to the bezier formed
182 by the four points. The respective x/y coordinate must be in the
183 [0.0, 1.0] range. For more information see section TABLET STYLUS
184 PRESSURE CURVE.
185 Option "TabletToolAreaRatio" "w:h"
187 Sets the area ratio for a tablet tool. The area always starts at
188 the origin (0/0) and expands to the largest available area with
189 the specified aspect ratio. Events outside this area are cropped
190 to the area. The special value "default" is used for the default
191 mapping (i.e. the device-native mapping). For more information
192 see section TABLET TOOL AREA RATIO.
193 Option "Tapping" "bool"
195 Enables or disables tap-to-click behavior.
196 Option "TappingButtonMap" "(lrm|lmr)"
198 Set the button mapping for 1/2/3-finger taps to left/right/mid‐
199 dle or left/middle/right, respectively.
200 Option "TappingDrag" "bool"
202 Enables or disables drag during tapping behavior ("tap-and-
203 drag"). When enabled, a tap followed by a finger held down
204 causes a single button down only, all motions of that finger
205 thus translate into dragging motion. Tap-and-drag requires op‐
206 tion Tapping to be enabled.
207 Option "TappingDragLock" "bool"
209 Enables or disables drag lock during tapping behavior. When en‐
210 abled, a finger up during tap-and-drag will not immediately re‐
211 lease the button. If the finger is set down again within the
212 timeout, the dragging process continues.
213 For all options, the options are only parsed if the device supports
215 that configuration option. For all options, the default value is the
216 one used by libinput. On configuration failure, the default value is
217 applied.
218
221 libinput exports runtime-configurable options as properties. If a prop‐
222 erty listed below is not available, the matching configuration option
223 is not available on the device. This however does not imply that the
224 feature is not available on the device. The following properties are
225 provided by the libinput driver.
226 libinput Accel Profiles Available
228 2 boolean values (8 bit, 0 or 1), in order "adaptive", "flat".
229 Indicates which acceleration profiles are available on this de‐
230 vice.
231 libinput Accel Profile Enabled
233 2 boolean values (8 bit, 0 or 1), in order "adaptive", "flat".
234 Indicates which acceleration profile is currently enabled on
235 this device.
236 libinput Accel Speed
238 1 32-bit float value, defines the pointer speed. Value range -1,
239 1
240 libinput Button Scrolling Button
242 1 32-bit value. Sets the button number to use for button
243 scrolling. This setting is independent of the scroll method, to
244 enable button scrolling the method must be set to button-
245 scrolling and a valid button must be set.
246 libinput Button Scrolling Button Lock Enabled
248 1 boolean value. If true, the scroll button lock is enabled.
249 This setting is independent of the scroll method or the scroll
250 button, to enable button scrolling the method must be set to
251 button-scrolling and a valid button must be set.
252 libinput Calibration Matrix
254 9 32-bit float values, representing a 3x3 calibration matrix,
255 order is row 1, row 2, row 3
256 libinput Click Methods Available
258 2 boolean values (8 bit, 0 or 1), in order "buttonareas",
259 "clickfinger". Indicates which click methods are available on
260 this device.
261 libinput Click Methods Enabled
263 2 boolean values (8 bit, 0 or 1), in order "buttonareas",
264 "clickfinger". Indicates which click methods are enabled on
265 this device.
266 libinput Drag Lock Buttons
268 Either one 8-bit value specifying the meta drag lock button, or
269 a list of button pairs. See section BUTTON DRAG LOCK for de‐
270 tails.
271 libinput High Resolution Wheel Scroll Enabled
273 1 boolean value (8 bit, 0 or 1). Indicates whether high-resolu‐
274 tion wheel scroll events are enabled or not.
275 libinput Horizontal Scroll Enabled
277 1 boolean value (8 bit, 0 or 1). Indicates whether horizontal
278 scrolling events are enabled or not.
279 libinput Left Handed Enabled
281 1 boolean value (8 bit, 0 or 1). Indicates if left-handed mode
282 is enabled or disabled.
283 libinput Middle Emulation Enabled
285 1 boolean value (8 bit, 0 or 1). Indicates if middle emulation
286 is enabled or disabled.
287 libinput Natural Scrolling Enabled
289 1 boolean value (8 bit, 0 or 1). 1 enables natural scrolling
290 libinput Rotation Angle
292 1 32-bit float value [0.0 to 360.0). Sets the rotation angle of
293 the device, clockwise of its natural neutral position.
294 libinput Scroll Methods Available
296 3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge",
297 "button". Indicates which scroll methods are available on this
298 device.
299 libinput Scroll Method Enabled
301 3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge",
302 "button". Indicates which scroll method is currently enabled on
303 this device.
304 libinput Scroll Pixel Distance
306 1 32-bit value (nonzero, with additional implementation-defined
307 range checks). Changes the movement distance required to trig‐
308 ger one logical wheel click.
309 libinput Send Events Modes Available
311 2 boolean values (8 bit, 0 or 1), in order "disabled" and "dis‐
312 abled-on-external-mouse". Indicates which send-event modes are
313 available on this device.
314 libinput Send Events Mode Enabled
316 2 boolean values (8 bit, 0 or 1), in order "disabled" and "dis‐
317 abled-on-external-mouse". Indicates which send-event modes is
318 currently enabled on this device.
319 libinput Tablet Tool Pressurecurve
321 4 32-bit float values [0.0 to 1.0]. See section TABLET TOOL
322 PRESSURE CURVE
323 libinput Tablet Tool Area Ratio
325 2 32-bit values, corresponding to width and height. Special
326 value 0, 0 resets to the default ratio. See section TABLET TOOL
327 AREA RATIO for more information.
328 libinput Tapping Enabled
330 1 boolean value (8 bit, 0 or 1). 1 enables tapping
331 libinput Tapping Button Mapping Enabled
333 2 boolean value (8 bit, 0 or 1), in order "lrm" and "lmr". Indi‐
334 cates which button mapping is currently enabled on this device.
335 libinput Tapping Drag Lock Enabled
337 1 boolean value (8 bit, 0 or 1). 1 enables drag lock during tap‐
338 ping
339 libinput Disable While Typing Enabled
341 1 boolean value (8 bit, 0 or 1). Indicates if disable while typ‐
342 ing is enabled or disabled.
343 Most properties have a libinput <property name> Default equivalent that
345 indicates the default value for this setting on this device.
346
349 X clients receive events with logical button numbers, where 1, 2, 3 are
350 usually interpreted as left, middle, right and logical buttons 4, 5, 6,
351 7 are usually interpreted as scroll up, down, left, right. The fourth
352 and fifth physical buttons on a device will thus send logical buttons 8
353 and 9. The ButtonMapping option adjusts the logical button mapping, it
354 does not affect how a physical button is mapped to a logical button.
355 Traditionally, a device was set to left-handed button mode by applying
357 a button mapping of "3 2 1 ..." On systems using the libinput Xorg in‐
358 put driver it is recommended to use the LeftHanded option instead.
359 The libinput Xorg input driver does not use the button mapping after
361 setup. Use XSetPointerMapping(3) to modify the button mapping at run‐
362 time.
363
366 Button drag lock holds a button logically down even when the button it‐
367 self has been physically released since. Button drag lock comes in two
368 modes.
369 If in "meta" mode, a meta button click activates drag lock for the next
371 button press of any other button. A button click in the future will
372 keep that button held logically down until a subsequent click of that
373 same button. The meta button events themselves are discarded. A sepa‐
374 rate meta button click is required each time a drag lock should be ac‐
375 tivated for a button in the future.
376 If in "pairs" mode, each button can be assigned a target locking but‐
378 ton. On button click, the target lock button is held logically down
379 until the next click of the same button. The button events themselves
380 are discarded and only the target button events are sent.
381 This feature is provided by this driver, not by libinput.
383
386 The pressure curve affects how stylus pressure is reported. By default,
387 the hardware pressure is reported as-is. By setting a pressure curve,
388 the feel of the stylus can be adjusted to be more like e.g. a pencil or
389 a brush.
390 The pressure curve is a cubic Bezier curve, drawn within a normalized
392 range of 0.0 to 1.0 between the four points provided. This normalized
393 range is applied to the tablet's pressure input so that the highest
394 pressure maps to 1.0. The points must have increasing x coordinates, if
395 x0 is larger than 0.0 all pressure values lower than x0 are equivalent
396 to y0. If x3 is less than 1.0, all pressure values higher than x3 are
397 equivalent to y3.
398 The input for a linear curve (default) is "0.0/0.0 0.0/0.0 1.0/1.0
400 1.0/1.0"; a slightly depressed curve (firmer) might be "0.0/0.0
401 0.05/0.0 1.0/0.95 1.0/1.0"; a slightly raised curve (softer) might be
402 "0.0/0.0 0.0/0.05 0.95/1.0 1.0/1.0".
403 This feature is provided by this driver, not by libinput.
405
408 By default, a tablet tool can access the whole sensor area and the
409 tablet area is mapped to the available screen area. For external
410 tablets like the Wacom Intuos series, the height:width ratio of the
411 tablet may be different to that of the monitor, causing the skew of in‐
412 put data.
413 To avoid this skew of input data, an area ratio may be set to match the
415 ratio of the screen device. For example, a ratio of 4:3 will reduce the
416 available area of the tablet to the largest available area with a ratio
417 of 4:3. Events within this area will scale to the tablet's announced
418 axis range, the area ratio is thus transparent to the X server. Any
419 events outside this area will send events equal to the maximum value of
420 that axis. The area always starts at the device's origin in it's cur‐
421 rent rotation, i.e. it takes left-handed-ness into account.
422 This feature is provided by this driver, not by libinput.
424
427 The X server does not support per-pixel scrolling but it does support
428 smooth scrolling. All scroll events however are based around a logical
429 unit of scrolling (traditionally corresponding to a wheel click). It
430 is thus not possible to scroll by 10 pixels, but it is possible for a
431 driver to scroll by 1/10th of a logical wheel click.
432 libinput provides scroll data in pixels. The ScrollPixelDistance option
434 defines the amount of movement equivalent to one wheel click. For exam‐
435 ple, a value of 50 means the user has to move a finger by 50 pixels to
436 generate one logical click event and each pixel is 1/50th of a wheel
437 click.
438
440 This driver does not work with Option "Device" set to an event node in
441 /dev/input/by-id and /dev/input/by-path. This can be usually be worked
442 by using Section "InputClass" with an appropriate Match* statement in
443 the xorg.conf(5).
444 This driver does not know about the display pixel density and submits
446 motion events assuming an approximate display density of 96dpi. On
447 high-dpi screens this results in a slower physical motion of the cursor
448 (a one-pixel movement is a smaller physical movement on the screen).
449 This can make interaction with the desktop difficult.
450 Option "DPIScaleFactor" float
452 This is a temporary solution. The factor should be set to the
453 approximate ratio of the host display compared to the default
454 96dpi. For example, a display with 200dpi should set a factor of
455 2.0.
456 If set, x/y motion will be unconditionally multiplied by this factor,
458 resulting in faster movement of the cursor. Note that this may make
459 some pixels unadressable and should be used with caution.
460 This option is a temporary solution. It may be removed in any future
462 update of this driver.
463
466 Peter Hutterer
467
469 Xorg(1), xorg.conf(5), Xserver(1), X(7)
4701.3.0 xf86-input-libinput LIBINPUT(4)