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
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
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
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
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
124              degrees 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 held down, x/y axis  movement
130              is converted into scroll events.
131
132       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
138       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
142       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
148       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
156       Option "Tapping" "bool"
157              Enables or disables tap-to-click behavior.
158
159       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
163       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
170       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
176       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
181

SUPPORTED PROPERTIES

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
189       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
194       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
199       libinput Accel Speed
200              1 32-bit float value, defines the pointer speed. Value range -1,
201              1
202
203       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
209       libinput Calibration Matrix
210              9 32-bit float values, representing a  3x3  calibration  matrix,
211              order is row 1, row 2, row 3
212
213       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
218       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
223       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
228       libinput Horizontal Scrolling Enabled
229              1  boolean  value  (8 bit, 0 or 1). Indicates whether horizontal
230              scrolling events are enabled or not.
231
232       libinput Left Handed Enabled
233              1 boolean value (8 bit, 0 or 1). Indicates if  left-handed  mode
234              is enabled or disabled.
235
236       libinput Middle Emulation Enabled
237              1  boolean  value (8 bit, 0 or 1). Indicates if middle emulation
238              is enabled or disabled.
239
240       libinput Natural Scrolling Enabled
241              1 boolean value (8 bit, 0 or 1). 1 enables natural scrolling
242
243       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
247       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
252       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
257       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
262       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
267       libinput Tablet Tool Pressurecurve
268              4  32-bit  float  values  [0.0  to 1.0]. See section TABLET TOOL
269              PRESSURE CURVE
270
271       libinput Tablet Tool Area Ratio
272              2 32-bit values, corresponding  to  width  and  height.  Special
273              value  0, 0 resets to the default ratio. See section TABLET TOOL
274              AREA RATIO for more information.
275
276       libinput Tapping Enabled
277              1 boolean value (8 bit, 0 or 1). 1 enables tapping
278
279       libinput Tapping Button Mapping Enabled
280              2 boolean value (8 bit, 0 or 1), in order "lrm" and "lmr". Indi‐
281              cates which button mapping is currently enabled on this device.
282
283       libinput Tapping Drag Lock Enabled
284              1 boolean value (8 bit, 0 or 1). 1 enables drag lock during tap‐
285              ping
286
287       libinput Disable While Typing Enabled
288              1 boolean value (8 bit, 0 or 1). Indicates if disable while typ‐
289              ing is enabled or disabled.
290
291       Most properties have a libinput <property name> Default equivalent that
292       indicates the default value for this setting on this device.
293
294

BUTTON MAPPING

296       X clients receive events with logical button numbers, where 1, 2, 3 are
297       usually interpreted as left, middle, right and logical buttons 4, 5, 6,
298       7 are usually interpreted as scroll up, down, left, right.  The  fourth
299       and fifth physical buttons on a device will thus send logical buttons 8
300       and 9.  The ButtonMapping option adjusts the logical button mapping, it
301       does not affect how a physical button is mapped to a logical button.
302
303       Traditionally,  a device was set to left-handed button mode by applying
304       a button mapping of "3 2 1 ..." On  systems  using  the  libinput  Xorg
305       input driver it is recommended to use the LeftHanded option instead.
306
307       The  libinput  Xorg  input driver does not use the button mapping after
308       setup.  Use XSetPointerMapping(3) to modify the button mapping at  run‐
309       time.
310
311

BUTTON DRAG LOCK

313       Button  drag  lock  holds  a button logically down even when the button
314       itself has been physically released since. Button drag  lock  comes  in
315       two modes.
316
317       If in "meta" mode, a meta button click activates drag lock for the next
318       button press of any other button. A button click  in  the  future  will
319       keep  that  button held logically down until a subsequent click of that
320       same button. The meta button events themselves are discarded.  A  sepa‐
321       rate  meta  button  click  is  required each time a drag lock should be
322       activated for a button in the future.
323
324       If in "pairs" mode, each button can be assigned a target  locking  but‐
325       ton.   On  button  click, the target lock button is held logically down
326       until the next click of the same button. The button  events  themselves
327       are discarded and only the target button events are sent.
328
329       This feature is provided by this driver, not by libinput.
330
331

TABLET TOOL PRESSURECURVE

333       The pressure curve affects how stylus pressure is reported. By default,
334       the hardware pressure is reported as-is. By setting a  pressure  curve,
335       the feel of the stylus can be adjusted to be more like e.g. a pencil or
336       a brush.
337
338       The pressure curve is a cubic Bezier curve, drawn within  a  normalized
339       range  of  0.0 to 1.0 between the four points provided. This normalized
340       range is applied to the tablet's pressure input  so  that  the  highest
341       pressure maps to 1.0. The points must have increasing x coordinates, if
342       x0 is larger than 0.0 all pressure values lower than x0 are  equivalent
343       to  y0. If x3 is less than 1.0, all pressure values higher than x3  are
344       equivalent to y3.
345
346       The input for a linear  curve  (default) is  "0.0/0.0  0.0/0.0  1.0/1.0
347       1.0/1.0";  a  slightly  depressed  curve  (firmer)  might  be  "0.0/0.0
348       0.05/0.0 1.0/0.95 1.0/1.0"; a slightly raised curve (softer) might   be
349       "0.0/0.0 0.0/0.05 0.95/1.0 1.0/1.0".
350
351       This feature is provided by this driver, not by libinput.
352
353

TABLET TOOL AREA RATIO

355       By  default,  a  tablet  tool  can access the whole sensor area and the
356       tablet area is mapped  to  the  available  screen  area.  For  external
357       tablets  like  the  Wacom  Intuos series, the height:width ratio of the
358       tablet may be different to that of the monitor,  causing  the  skew  of
359       input data.
360
361       To avoid this skew of input data, an area ratio may be set to match the
362       ratio of the screen device. For example, a ratio of 4:3 will reduce the
363       available area of the tablet to the largest available area with a ratio
364       of 4:3. Events within this area will scale to  the  tablet's  announced
365       axis  range,  the  area  ratio is thus transparent to the X server. Any
366       events outside this area will send events equal to the maximum value of
367       that  axis.  The area always starts at the device's origin in it's cur‐
368       rent rotation, i.e.  it takes left-handed-ness into account.
369
370       This feature is provided by this driver, not by libinput.
371
372

BUGS

374       This driver does not work with Option "Device" set to an event node  in
375       /dev/input/by-id  and /dev/input/by-path. This can be usually be worked
376       by using Section "InputClass" with an appropriate Match*  statement  in
377       the xorg.conf(5).
378
379       This  driver  does not know about the display pixel density and submits
380       motion events assuming an approximate  display  density  of  96dpi.  On
381       high-dpi screens this results in a slower physical motion of the cursor
382       (a one-pixel movement is a smaller physical movement  on  the  screen).
383       This can make interaction with the desktop difficult.
384
385       Option "DPIScaleFactor" float
386              This  is  a  temporary solution. The factor should be set to the
387              approximate ratio of the host display compared  to  the  default
388              96dpi. For example, a display with 200dpi should set a factor of
389              2.0.
390
391       If set, x/y motion will be unconditionally multiplied by  this  factor,
392       resulting  in  faster  movement  of the cursor. Note that this may make
393       some pixels unadressable and should be used with caution.
394
395       This option is a temporary solution.  It may be removed in  any  future
396       update of this driver.
397
398

AUTHORS

400       Peter Hutterer
401

SEE ALSO

403       Xorg(1), xorg.conf(5), Xserver(1), X(7)
404
405
406
407X Version 11              xf86-input-libinput 0.29.0               LIBINPUT(4)
Impressum