1LIBINPUT(4)                Kernel Interfaces Manual                LIBINPUT(4)
2
3
4

NAME

6       libinput - libinput-based X.Org input driver
7

SYNOPSIS

9       Section "InputDevice"
10         Identifier "devname"
11         Driver "libinput"
12         Option "Device"   "devpath"
13         ...
14       EndSection
15
16

NOTE

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
22

DESCRIPTION

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
28       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
33

CONFIGURATION DETAILS

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
39       The following driver Options are supported:
40
41       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
48       Option "AccelSpeed" "float"
49              Sets the pointer acceleration speed within the range [-1, 1]
50
51       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
62       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
68       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
74       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
79       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
86       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
91              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
95              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
100              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
104       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
110       Option "LeftHanded" "bool"
111              Enables left-handed button orientation, i.e. swapping  left  and
112              right buttons.
113
114       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
119       Option "NaturalScrolling" "bool"
120              Enables or disables natural scrolling behavior.
121
122       Option "RotationAngle" "float"
123              Sets the rotation angle of the device to the given angle, in de‐
124              grees clockwise. The angle must be between 0.0  (inclusive)  and
125              360.0 (exclusive).
126
127       Option "ScrollButton" "int"
128              Designates  a  button  as  scroll button. If the ScrollMethod is
129              button and the button is logically down, x/y  axis  movement  is
130              converted into scroll events.
131
132       Option "ScrollButtonLock" "bool"
133              Enables  or  disables  the  scroll  button lock. If enabled, the
134              ScrollButton is considered logically down after the first  click
135              and  remains down until the second click of that button. If dis‐
136              abled (the default), the ScrollButton button is considered logi‐
137              cally down while held down and up once physically released.
138
139       Option "ScrollMethod" "string"
140              Enables  a  scroll method. Permitted values are none, twofinger,
141              edge, button.  Not all devices support all options, if an option
142              is  unsupported,  the  default  scroll option for this device is
143              used.
144
145       Option "ScrollPixelDistance" "int"
146              Sets the movement distance, in "pixels", required to trigger one
147              logical  wheel  click.  This  option  only applies to the scroll
148              methods twofinger, edge, button.  See section SCROLL PIXEL  DIS‐
149              TANCE for more details.
150
151       Option "SendEventsMode" "(disabled|enabled|disabled-on-external-mouse)"
152              Sets the send events mode to disabled, enabled, or "disable when
153              an external mouse is connected".
154
155       Option "TabletToolPressureCurve" "x0/y0 x1/y1 x2/y2 x3/y3"
156              Set the pressure curve for a tablet stylus to the bezier  formed
157              by the four points. The respective x/y coordinate must be in the
158              [0.0, 1.0] range. For more information see section TABLET STYLUS
159              PRESSURE CURVE.
160
161       Option "TabletToolAreaRatio" "w:h"
162              Sets the area ratio for a tablet tool. The area always starts at
163              the origin (0/0) and expands to the largest available area  with
164              the specified aspect ratio. Events outside this area are cropped
165              to the area. The special value "default" is used for the default
166              mapping  (i.e.  the device-native mapping). For more information
167              see section TABLET TOOL AREA RATIO.
168
169       Option "Tapping" "bool"
170              Enables or disables tap-to-click behavior.
171
172       Option "TappingButtonMap" "(lrm|lmr)"
173              Set the button mapping for 1/2/3-finger taps to  left/right/mid‐
174              dle or left/middle/right, respectively.
175
176       Option "TappingDrag" "bool"
177              Enables  or  disables  drag  during  tapping behavior ("tap-and-
178              drag"). When enabled, a tap  followed  by  a  finger  held  down
179              causes  a  single  button  down only, all motions of that finger
180              thus translate into dragging motion.  Tap-and-drag requires  op‐
181              tion Tapping to be enabled.
182
183       Option "TappingDragLock" "bool"
184              Enables  or disables drag lock during tapping behavior. When en‐
185              abled, a finger up during tap-and-drag will not immediately  re‐
186              lease  the  button.  If  the finger is set down again within the
187              timeout, the dragging process continues.
188
189       For all options, the options are only parsed  if  the  device  supports
190       that  configuration  option.  For all options, the default value is the
191       one used by libinput. On configuration failure, the  default  value  is
192       applied.
193
194

SUPPORTED PROPERTIES

196       libinput exports runtime-configurable options as properties. If a prop‐
197       erty listed below is not available, the matching  configuration  option
198       is  not  available  on the device. This however does not imply that the
199       feature is not available on the device. The  following  properties  are
200       provided by the libinput driver.
201
202       libinput Accel Profiles Available
203              2  boolean  values (8 bit, 0 or 1), in order "adaptive", "flat".
204              Indicates which acceleration profiles are available on this  de‐
205              vice.
206
207       libinput Accel Profile Enabled
208              2  boolean  values (8 bit, 0 or 1), in order "adaptive", "flat".
209              Indicates which acceleration profile  is  currently  enabled  on
210              this device.
211
212       libinput Accel Speed
213              1 32-bit float value, defines the pointer speed. Value range -1,
214              1
215
216       libinput Button Scrolling Button
217              1 32-bit value.  Sets  the  button  number  to  use  for  button
218              scrolling.  This setting is independent of the scroll method, to
219              enable button scrolling  the  method  must  be  set  to  button-
220              scrolling and a valid button must be set.
221
222       libinput Button Scrolling Button Lock Enabled
223              1  boolean  value.  If  true, the scroll button lock is enabled.
224              This setting is independent of the scroll method or  the  scroll
225              button,  to  enable  button  scrolling the method must be set to
226              button-scrolling and a valid button must be set.
227
228       libinput Calibration Matrix
229              9 32-bit float values, representing a  3x3  calibration  matrix,
230              order is row 1, row 2, row 3
231
232       libinput Click Methods Available
233              2  boolean  values  (8  bit,  0  or  1), in order "buttonareas",
234              "clickfinger".  Indicates which click methods are  available  on
235              this device.
236
237       libinput Click Methods Enabled
238              2  boolean  values  (8  bit,  0  or  1), in order "buttonareas",
239              "clickfinger".  Indicates which click  methods  are  enabled  on
240              this device.
241
242       libinput Drag Lock Buttons
243              Either  one 8-bit value specifying the meta drag lock button, or
244              a list of button pairs. See section BUTTON  DRAG  LOCK  for  de‐
245              tails.
246
247       libinput Horizontal Scrolling Enabled
248              1  boolean  value  (8 bit, 0 or 1). Indicates whether horizontal
249              scrolling events are enabled or not.
250
251       libinput Left Handed Enabled
252              1 boolean value (8 bit, 0 or 1). Indicates if  left-handed  mode
253              is enabled or disabled.
254
255       libinput Middle Emulation Enabled
256              1  boolean  value (8 bit, 0 or 1). Indicates if middle emulation
257              is enabled or disabled.
258
259       libinput Natural Scrolling Enabled
260              1 boolean value (8 bit, 0 or 1). 1 enables natural scrolling
261
262       libinput Rotation Angle
263              1 32-bit float value [0.0 to 360.0). Sets the rotation angle  of
264              the device, clockwise of its natural neutral position.
265
266       libinput Scroll Methods Available
267              3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge",
268              "button".  Indicates which scroll methods are available on  this
269              device.
270
271       libinput Scroll Method Enabled
272              3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge",
273              "button".  Indicates which scroll method is currently enabled on
274              this device.
275
276       libinput Scroll Pixel Distance
277              1  32-bit value (nonzero, with additional implementation-defined
278              range checks).  Changes the movement distance required to  trig‐
279              ger one logical wheel click.
280
281       libinput Send Events Modes Available
282              2  boolean values (8 bit, 0 or 1), in order "disabled" and "dis‐
283              abled-on-external-mouse". Indicates which send-event  modes  are
284              available on this device.
285
286       libinput Send Events Mode Enabled
287              2  boolean values (8 bit, 0 or 1), in order "disabled" and "dis‐
288              abled-on-external-mouse". Indicates which  send-event  modes  is
289              currently enabled on this device.
290
291       libinput Tablet Tool Pressurecurve
292              4  32-bit  float  values  [0.0  to 1.0]. See section TABLET TOOL
293              PRESSURE CURVE
294
295       libinput Tablet Tool Area Ratio
296              2 32-bit values, corresponding  to  width  and  height.  Special
297              value  0, 0 resets to the default ratio. See section TABLET TOOL
298              AREA RATIO for more information.
299
300       libinput Tapping Enabled
301              1 boolean value (8 bit, 0 or 1). 1 enables tapping
302
303       libinput Tapping Button Mapping Enabled
304              2 boolean value (8 bit, 0 or 1), in order "lrm" and "lmr". Indi‐
305              cates which button mapping is currently enabled on this device.
306
307       libinput Tapping Drag Lock Enabled
308              1 boolean value (8 bit, 0 or 1). 1 enables drag lock during tap‐
309              ping
310
311       libinput Disable While Typing Enabled
312              1 boolean value (8 bit, 0 or 1). Indicates if disable while typ‐
313              ing is enabled or disabled.
314
315       Most properties have a libinput <property name> Default equivalent that
316       indicates the default value for this setting on this device.
317
318

BUTTON MAPPING

320       X clients receive events with logical button numbers, where 1, 2, 3 are
321       usually interpreted as left, middle, right and logical buttons 4, 5, 6,
322       7 are usually interpreted as scroll up, down, left, right.  The  fourth
323       and fifth physical buttons on a device will thus send logical buttons 8
324       and 9.  The ButtonMapping option adjusts the logical button mapping, it
325       does not affect how a physical button is mapped to a logical button.
326
327       Traditionally,  a device was set to left-handed button mode by applying
328       a button mapping of "3 2 1 ..." On systems using the libinput Xorg  in‐
329       put driver it is recommended to use the LeftHanded option instead.
330
331       The  libinput  Xorg  input driver does not use the button mapping after
332       setup.  Use XSetPointerMapping(3) to modify the button mapping at  run‐
333       time.
334
335

BUTTON DRAG LOCK

337       Button drag lock holds a button logically down even when the button it‐
338       self has been physically released since. Button drag lock comes in  two
339       modes.
340
341       If in "meta" mode, a meta button click activates drag lock for the next
342       button press of any other button. A button click  in  the  future  will
343       keep  that  button held logically down until a subsequent click of that
344       same button. The meta button events themselves are discarded.  A  sepa‐
345       rate  meta button click is required each time a drag lock should be ac‐
346       tivated for a button in the future.
347
348       If in "pairs" mode, each button can be assigned a target  locking  but‐
349       ton.   On  button  click, the target lock button is held logically down
350       until the next click of the same button. The button  events  themselves
351       are discarded and only the target button events are sent.
352
353       This feature is provided by this driver, not by libinput.
354
355

TABLET TOOL PRESSURECURVE

357       The pressure curve affects how stylus pressure is reported. By default,
358       the hardware pressure is reported as-is. By setting a  pressure  curve,
359       the feel of the stylus can be adjusted to be more like e.g. a pencil or
360       a brush.
361
362       The pressure curve is a cubic Bezier curve, drawn within  a  normalized
363       range  of  0.0 to 1.0 between the four points provided. This normalized
364       range is applied to the tablet's pressure input  so  that  the  highest
365       pressure maps to 1.0. The points must have increasing x coordinates, if
366       x0 is larger than 0.0 all pressure values lower than x0 are  equivalent
367       to  y0. If x3 is less than 1.0, all pressure values higher than x3  are
368       equivalent to y3.
369
370       The input for a linear  curve  (default) is  "0.0/0.0  0.0/0.0  1.0/1.0
371       1.0/1.0";  a  slightly  depressed  curve  (firmer)  might  be  "0.0/0.0
372       0.05/0.0 1.0/0.95 1.0/1.0"; a slightly raised curve (softer) might   be
373       "0.0/0.0 0.0/0.05 0.95/1.0 1.0/1.0".
374
375       This feature is provided by this driver, not by libinput.
376
377

TABLET TOOL AREA RATIO

379       By  default,  a  tablet  tool  can access the whole sensor area and the
380       tablet area is mapped  to  the  available  screen  area.  For  external
381       tablets  like  the  Wacom  Intuos series, the height:width ratio of the
382       tablet may be different to that of the monitor, causing the skew of in‐
383       put data.
384
385       To avoid this skew of input data, an area ratio may be set to match the
386       ratio of the screen device. For example, a ratio of 4:3 will reduce the
387       available area of the tablet to the largest available area with a ratio
388       of 4:3. Events within this area will scale to  the  tablet's  announced
389       axis  range,  the  area  ratio is thus transparent to the X server. Any
390       events outside this area will send events equal to the maximum value of
391       that  axis.  The area always starts at the device's origin in it's cur‐
392       rent rotation, i.e.  it takes left-handed-ness into account.
393
394       This feature is provided by this driver, not by libinput.
395
396

SCROLL PIXEL DISTANCE

398       The X server does not support per-pixel scrolling but it  does  support
399       smooth  scrolling. All scroll events however are based around a logical
400       unit of scrolling (traditionally corresponding to a wheel  click).   It
401       is  thus  not possible to scroll by 10 pixels, but it is possible for a
402       driver to scroll by 1/10th of a logical wheel click.
403
404       libinput provides scroll data in pixels. The ScrollPixelDistance option
405       defines the amount of movement equivalent to one wheel click. For exam‐
406       ple, a value of 50 means the user has to move a finger by 50 pixels  to
407       generate  one  logical  click event and each pixel is 1/50th of a wheel
408       click.
409

BUGS

411       This driver does not work with Option "Device" set to an event node  in
412       /dev/input/by-id  and /dev/input/by-path. This can be usually be worked
413       by using Section "InputClass" with an appropriate Match*  statement  in
414       the xorg.conf(5).
415
416       This  driver  does not know about the display pixel density and submits
417       motion events assuming an approximate  display  density  of  96dpi.  On
418       high-dpi screens this results in a slower physical motion of the cursor
419       (a one-pixel movement is a smaller physical movement  on  the  screen).
420       This can make interaction with the desktop difficult.
421
422       Option "DPIScaleFactor" float
423              This  is  a  temporary solution. The factor should be set to the
424              approximate ratio of the host display compared  to  the  default
425              96dpi. For example, a display with 200dpi should set a factor of
426              2.0.
427
428       If set, x/y motion will be unconditionally multiplied by  this  factor,
429       resulting  in  faster  movement  of the cursor. Note that this may make
430       some pixels unadressable and should be used with caution.
431
432       This option is a temporary solution.  It may be removed in  any  future
433       update of this driver.
434
435

AUTHORS

437       Peter Hutterer
438

SEE ALSO

440       Xorg(1), xorg.conf(5), Xserver(1), X(7)
441
442
443
444X Version 11               xf86-input-libinput 1.2.0               LIBINPUT(4)
Impressum