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 "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
110       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
116       Option "LeftHanded" "bool"
117              Enables  left-handed  button orientation, i.e. swapping left and
118              right buttons.
119
120       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
125       Option "NaturalScrolling" "bool"
126              Enables or disables natural scrolling behavior.
127
128       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
133       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
138       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
145       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
151       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
157       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
161       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
167       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
175       Option "Tapping" "bool"
176              Enables or disables tap-to-click behavior.
177
178       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
182       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
189       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
195       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
200

SUPPORTED PROPERTIES

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
208       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
213       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
218       libinput Accel Speed
219              1 32-bit float value, defines the pointer speed. Value range -1,
220              1
221
222       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
228       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
234       libinput Calibration Matrix
235              9  32-bit  float  values, representing a 3x3 calibration matrix,
236              order is row 1, row 2, row 3
237
238       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
243       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
248       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
253       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
257       libinput Horizontal Scroll Enabled
258              1  boolean  value  (8 bit, 0 or 1). Indicates whether horizontal
259              scrolling events are enabled or not.
260
261       libinput Left Handed Enabled
262              1 boolean value (8 bit, 0 or 1). Indicates if  left-handed  mode
263              is enabled or disabled.
264
265       libinput Middle Emulation Enabled
266              1  boolean  value (8 bit, 0 or 1). Indicates if middle emulation
267              is enabled or disabled.
268
269       libinput Natural Scrolling Enabled
270              1 boolean value (8 bit, 0 or 1). 1 enables natural scrolling
271
272       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
276       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
281       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
286       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
291       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
296       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
301       libinput Tablet Tool Pressurecurve
302              4  32-bit  float  values  [0.0  to 1.0]. See section TABLET TOOL
303              PRESSURE CURVE
304
305       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
310       libinput Tapping Enabled
311              1 boolean value (8 bit, 0 or 1). 1 enables tapping
312
313       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
317       libinput Tapping Drag Lock Enabled
318              1 boolean value (8 bit, 0 or 1). 1 enables drag lock during tap‐
319              ping
320
321       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
325       Most properties have a libinput <property name> Default equivalent that
326       indicates the default value for this setting on this device.
327
328

BUTTON MAPPING

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
337       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
341       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
345

BUTTON DRAG LOCK

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
351       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
358       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
363       This feature is provided by this driver, not by libinput.
364
365

TABLET TOOL PRESSURECURVE

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
372       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
380       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
385       This feature is provided by this driver, not by libinput.
386
387

TABLET TOOL AREA RATIO

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
395       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
404       This feature is provided by this driver, not by libinput.
405
406

SCROLL PIXEL DISTANCE

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
414       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

BUGS

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
426       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
432       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
438       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
442       This option is a temporary solution.  It may be removed in  any  future
443       update of this driver.
444
445

AUTHORS

447       Peter Hutterer
448

SEE ALSO

450       Xorg(1), xorg.conf(5), Xserver(1), X(7)
451
452
453
454X Version 11               xf86-input-libinput 1.2.1               LIBINPUT(4)
Impressum