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
29 InputClass directive (refer to xorg.conf(5)) instead of manual per-
30 device configuration. Devices configured in the xorg.conf(5) are not
31 hot-plug 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
64 order "a b c d e f g h i". Sets the calibration matrix to the
65 3x3 matrix where the first row is (abc), the second row is (def)
66 and 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 "HorizontalScrolling" "bool"
105 Disables horizontal scrolling. When disabled, this driver will
106 discard any horizontal scroll events from libinput. Note that
107 this does not disable horizontal scrolling, it merely discards
108 the horizontal axis from any scroll events.
109 Option "LeftHanded" "bool"
111 Enables left-handed button orientation, i.e. swapping left and
112 right buttons.
113 Option "MiddleEmulation" "bool"
115 Enables middle button emulation. When enabled, pressing the left
116 and right buttons simultaneously produces a middle mouse button
117 click.
118 Option "NaturalScrolling" "bool"
120 Enables or disables natural scrolling behavior.
121 Option "RotationAngle" "float"
123 Sets the rotation angle of the device to the given angle, in
124 degrees clockwise. The angle must be between 0.0 (inclusive) and
125 360.0 (exclusive).
126 Option "ScrollButton" "int"
128 Designates a button as scroll button. If the ScrollMethod is
129 button and the button is logically held down, x/y axis movement
130 is converted into scroll events.
131 Option "ScrollMethod" "string"
133 Enables a scroll method. Permitted values are none, twofinger,
134 edge, button. Not all devices support all options, if an option
135 is unsupported, the default scroll option for this device is
136 used.
137 Option "SendEventsMode" "(disabled|enabled|disabled-on-external-mouse)"
139 Sets the send events mode to disabled, enabled, or "disable when
140 an external mouse is connected".
141 Option "TabletToolPressureCurve" "x0/y0 x1/y1 x2/y2 x3/y3"
143 Set the pressure curve for a tablet stylus to the bezier formed
144 by the four points. The respective x/y coordinate must be in the
145 [0.0, 1.0] range. For more information see section TABLET STYLUS
146 PRESSURE CURVE.
147 Option "TabletToolAreaRatio" "w:h"
149 Sets the area ratio for a tablet tool. The area always starts at
150 the origin (0/0) and expands to the largest available area with
151 the specified aspect ratio. Events outside this area are cropped
152 to the area. The special value "default" is used for the default
153 mapping (i.e. the device-native mapping). For more information
154 see section TABLET TOOL AREA RATIO.
155 Option "Tapping" "bool"
157 Enables or disables tap-to-click behavior.
158 Option "TappingButtonMap" "(lrm|lmr)"
160 Set the button mapping for 1/2/3-finger taps to left/right/mid‐
161 dle or left/middle/right, respectively.
162 Option "TappingDrag" "bool"
164 Enables or disables drag during tapping behavior ("tap-and-
165 drag"). When enabled, a tap followed by a finger held down
166 causes a single button down only, all motions of that finger
167 thus translate into dragging motion. Tap-and-drag requires
168 option Tapping to be enabled.
169 Option "TappingDragLock" "bool"
171 Enables or disables drag lock during tapping behavior. When
172 enabled, a finger up during tap-and-drag will not immediately
173 release the button. If the finger is set down again within the
174 timeout, the dragging process continues.
175 For all options, the options are only parsed if the device supports
177 that configuration option. For all options, the default value is the
178 one used by libinput. On configuration failure, the default value is
179 applied.
180
183 libinput exports runtime-configurable options as properties. If a prop‐
184 erty listed below is not available, the matching configuration option
185 is not available on the device. This however does not imply that the
186 feature is not available on the device. The following properties are
187 provided by the libinput driver.
188 libinput Accel Profiles Available
190 2 boolean values (8 bit, 0 or 1), in order "adaptive", "flat".
191 Indicates which acceleration profiles are available on this
192 device.
193 libinput Accel Profile Enabled
195 2 boolean values (8 bit, 0 or 1), in order "adaptive", "flat".
196 Indicates which acceleration profile is currently enabled on
197 this device.
198 libinput Accel Speed
200 1 32-bit float value, defines the pointer speed. Value range -1,
201 1
202 libinput Button Scrolling Button
204 1 32-bit value. Sets the button number to use for button
205 scrolling. This setting is independent of the scroll method, to
206 enable button scrolling the method must be set to button-
207 scrolling and a valid button must be set.
208 libinput Calibration Matrix
210 9 32-bit float values, representing a 3x3 calibration matrix,
211 order is row 1, row 2, row 3
212 libinput Click Methods Available
214 2 boolean values (8 bit, 0 or 1), in order "buttonareas",
215 "clickfinger". Indicates which click methods are available on
216 this device.
217 libinput Click Methods Enabled
219 2 boolean values (8 bit, 0 or 1), in order "buttonareas",
220 "clickfinger". Indicates which click methods are enabled on
221 this device.
222 libinput Drag Lock Buttons
224 Either one 8-bit value specifying the meta drag lock button, or
225 a list of button pairs. See section BUTTON DRAG LOCK for
226 details.
227 libinput Horizontal Scrolling Enabled
229 1 boolean value (8 bit, 0 or 1). Indicates whether horizontal
230 scrolling events are enabled or not.
231 libinput Left Handed Enabled
233 1 boolean value (8 bit, 0 or 1). Indicates if left-handed mode
234 is enabled or disabled.
235 libinput Middle Emulation Enabled
237 1 boolean value (8 bit, 0 or 1). Indicates if middle emulation
238 is enabled or disabled.
239 libinput Natural Scrolling Enabled
241 1 boolean value (8 bit, 0 or 1). 1 enables natural scrolling
242 libinput Rotation Angle
244 1 32-bit float value [0.0 to 360.0). Sets the rotation angle of
245 the device, clockwise of its natural neutral position.
246 libinput Scroll Methods Available
248 3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge",
249 "button". Indicates which scroll methods are available on this
250 device.
251 libinput Scroll Method Enabled
253 3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge",
254 "button". Indicates which scroll method is currently enabled on
255 this device.
256 libinput Send Events Modes Available
258 2 boolean values (8 bit, 0 or 1), in order "disabled" and "dis‐
259 abled-on-external-mouse". Indicates which send-event modes are
260 available on this device.
261 libinput Send Events Mode Enabled
263 2 boolean values (8 bit, 0 or 1), in order "disabled" and "dis‐
264 abled-on-external-mouse". Indicates which send-event modes is
265 currently enabled on this device.
266 libinput Tablet Tool Pressurecurve
268 4 32-bit float values [0.0 to 1.0]. See section TABLET TOOL
269 PRESSURE CURVE libinput Tablet Tool Area Ratio 2 32-bit values,
270 corresponding to width and height. Special value 0, 0 resets to
271 the default ratio. See section TABLET TOOL AREA RATIO for more
272 information.
273 libinput Tapping Enabled
275 1 boolean value (8 bit, 0 or 1). 1 enables tapping
276 libinput Tapping Button Mapping Enabled
278 2 boolean value (8 bit, 0 or 1), in order "lrm" and "lmr". Indi‐
279 cates which button mapping is currently enabled on this device.
280 libinput Tapping Drag Lock Enabled
282 1 boolean value (8 bit, 0 or 1). 1 enables drag lock during tap‐
283 ping
284 libinput Disable While Typing Enabled
286 1 boolean value (8 bit, 0 or 1). Indicates if disable while typ‐
287 ing is enabled or disabled.
288 Most properties have a libinput <property name> Default equivalent that
290 indicates the default value for this setting on this device.
291
294 X clients receive events with logical button numbers, where 1, 2, 3 are
295 usually interpreted as left, middle, right and logical buttons 4, 5, 6,
296 7 are usually interpreted as scroll up, down, left, right. The fourth
297 and fifth physical buttons on a device will thus send logical buttons 8
298 and 9. The ButtonMapping option adjusts the logical button mapping, it
299 does not affect how a physical button is mapped to a logical button.
300 Traditionally, a device was set to left-handed button mode by applying
302 a button mapping of "3 2 1 ..." On systems using the libinput Xorg
303 input driver it is recommended to use the LeftHanded option instead.
304 The libinput Xorg input driver does not use the button mapping after
306 setup. Use XSetPointerMapping(3) to modify the button mapping at run‐
307 time.
308
311 Button drag lock holds a button logically down even when the button
312 itself has been physically released since. Button drag lock comes in
313 two modes.
314 If in "meta" mode, a meta button click activates drag lock for the next
316 button press of any other button. A button click in the future will
317 keep that button held logically down until a subsequent click of that
318 same button. The meta button events themselves are discarded. A sepa‐
319 rate meta button click is required each time a drag lock should be
320 activated for a button in the future.
321 If in "pairs" mode, each button can be assigned a target locking but‐
323 ton. On button click, the target lock button is held logically down
324 until the next click of the same button. The button events themselves
325 are discarded and only the target button events are sent.
326 This feature is provided by this driver, not by libinput.
328
331 The pressure curve affects how stylus pressure is reported. By default,
332 the hardware pressure is reported as-is. By setting a pressure curve,
333 the feel of the stylus can be adjusted to be more like e.g. a pencil or
334 a brush.
335 The pressure curve is a cubic Bezier curve, drawn within a normalized
337 range of 0.0 to 1.0 between the four points provided. This normalized
338 range is applied to the tablet's pressure input so that the highest
339 pressure maps to 1.0. The points must have increasing x coordinates, if
340 x0 is larger than 0.0 all pressure values lower than x0 are equivalent
341 to y0. If x3 is less than 1.0, all pressure values higher than x3 are
342 equivalent to y3.
343 The input for a linear curve (default) is "0.0/0.0 0.0/0.0 1.0/1.0
345 1.0/1.0"; a slightly depressed curve (firmer) might be "0.0/0.0
346 0.05/0.0 1.0/0.95 1.0/1.0"; a slightly raised curve (softer) might be
347 "0.0/0.0 0.0/0.05 0.95/1.0 1.0/1.0".
348 This feature is provided by this driver, not by libinput.
350
353 By default, a tablet tool can access the whole sensor area and the
354 tablet area is mapped to the available screen area. For external
355 tablets like the Wacom Intuos series, the height:width ratio of the
356 tablet may be different to that of the monitor, causing the skew of
357 input data.
358 To avoid this skew of input data, an area ratio may be set to match the
360 ratio of the screen device. For example, a ratio of 4:3 will reduce the
361 available area of the tablet to the largest available area with a ratio
362 of 4:3. Events within this area will scale to the tablet's announced
363 axis range, the area ratio is thus transparent to the X server. Any
364 events outside this area will send events equal to the maximum value of
365 that axis. The area always starts at the device's origin in it's cur‐
366 rent rotation, i.e. it takes left-handed-ness into account.
367 This feature is provided by this driver, not by libinput.
369
372 This driver does not work with Option "Device" set to an event node in
373 /dev/input/by-id and /dev/input/by-path. This can be usually be worked
374 by using Section "InputClass" with an appropriate Match* statement in
375 the xorg.conf(5).
376
379 Peter Hutterer
380
382 Xorg(1), xorg.conf(5), Xserver(1), X(7)
383X Version 11 xf86-input-libinput 0.27.1 LIBINPUT(4)