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