man/evdev.man

   1 .\" shorthand for double quote that works everywhere.
   2 .ds q \N'34'
   3 .TH EVDEV __drivermansuffix__ __vendorversion__
   4 .SH NAME
   5 evdev \- Generic Linux input driver
   6 .SH SYNOPSIS
   7 .nf
   8 .B "Section \*qInputDevice\*q"
   9 .BI "  Identifier \*q" devname \*q
  10 .B  "  Driver \*qevdev\*q"
  11 .BI "  Option \*qDevice\*q   \*q" devpath \*q
  12 .BI "  Option \*qEmulate3Buttons\*q     \*q" True \*q
  13 .BI "  Option \*qEmulate3Timeout\*q     \*q" 50 \*q
  14 .BI "  Option \*qGrabDevice\*q     \*q" False \*q
  15 \ \ ...
  16 .B EndSection
  17 .fi
  18 .SH DESCRIPTION
  19 .B evdev
  20 is an __xservername__ input driver for Linux\'s generic event devices.  It
  21 therefore supports all input devices that the kernel knows about, including
  22 most mice, keyboards, tablets and touchscreens.
  23 .B evdev
  24 is the default driver on the major Linux distributions.
  25 .PP
  26 The
  27 .B evdev
  28 driver can serve as both a pointer and a keyboard input device. Multiple
  29 input devices are supported by multiple instances of this driver, with one
  30 InputDevice section of your __xconfigfile__ for each input device that will
  31 use this driver.
  32 .PP
  33 It is recommended that
  34 .B evdev
  35 devices are configured through the
  36 .B InputClass
  37 directive (refer to __xconfigfile__(__filemansuffix__)) instead of manual
  38 per-device configuration. Devices configured in the
  39 __xconfigfile__(__filemansuffix__) are not hot-plug capable.
  40 .PP
  41 .SH SUPPORTED HARDWARE
  42 In general, any input device that the kernel has a driver for can be accessed
  43 through the
  44 .B evdev
  45 driver.  See the Linux kernel documentation for a complete list.
  46 .PP
  47 .SH CONFIGURATION DETAILS
  48 Please refer to __xconfigfile__(__filemansuffix__) for general configuration
  49 details and for options that can be used with all input drivers.  This
  50 section only covers configuration details specific to this driver.
  51 .PP
  52 The following driver
  53 .B Options
  54 are supported:
  55 .TP 7
  56 .BI "Option \*qButtonMapping\*q \*q" string \*q
  57 Sets the button mapping for this device. The mapping is a space-separated list
  58 of button mappings that correspond in order to the physical buttons on the
  59 device (i.e. the first number is the mapping for button 1, etc.). The default
  60 mapping is "1 2 3 ... 32". A mapping of 0 deactivates the button. Multiple
  61 buttons can have the same mapping.
  62 For example, a left-handed mouse with deactivated scroll-wheel would use a
  63 mapping of "3 2 1 0 0". Invalid mappings are ignored and the default mapping
  64 is used. Buttons not specified in the user's mapping use the default mapping.
  65 .TP 7
  66 .BI "Option \*qDevice\*q \*q" string \*q
  67 Specifies the device through which the device can be accessed.  This will
  68 generally be of the form \*q/dev/input/eventX\*q, where X is some integer.
  69 The mapping from device node to hardware is system-dependent. Property:
  70 "Device Node" (read-only).
  71 .TP 7
  72 .BI "Option \*qDragLockButtons\*q \*q" "L1 B2 L3 B4" \*q
  73 Sets \*qdrag lock buttons\*q that simulate holding a button down, so
  74 that low dexterity people do not have to hold a button down at the
  75 same time they move a mouse cursor. Button numbers occur in pairs,
  76 with the lock button number occurring first, followed by the button
  77 number that is the target of the lock button. Property: "Evdev
  78 Drag Lock Buttons".
  79 .TP 7
  80 .BI "Option \*qDragLockButtons\*q \*q" "M1" \*q
  81 Sets a \*qmaster drag lock button\*q that acts as a \*qMeta Key\*q
  82 indicating that the next button pressed is to be
  83 \*qdrag locked\*q. Property: "Evdev Drag Lock Buttons".
  84 .TP 7
  85 .TP 7
  86 .BI "Option \*qEmulate3Buttons\*q \*q" boolean \*q
  87 Enable/disable the emulation of the third (middle) mouse button for mice
  88 which only have two physical buttons.  The third button is emulated by
  89 pressing both buttons simultaneously.  Default: off. Property: "Evdev Middle
  90 Button Emulation".
  91 .TP 7
  92 .BI "Option \*qEmulate3Timeout\*q \*q" integer \*q
  93 Sets the timeout (in milliseconds) that the driver waits before deciding
  94 if two buttons where pressed "simultaneously" when 3 button emulation is
  95 enabled.  Default: 50. Property: "Evdev Middle Button Timeout".
  96 .TP 7
  97 .BI "Option \*qEmulateWheel\*q \*q" boolean \*q
  98 Enable/disable "wheel" emulation.  Wheel emulation means emulating button
  99 press/release events when the mouse is moved while a specific real button
 100 is pressed.  Wheel button events (typically buttons 4 and 5) are
 101 usually used for scrolling.  Wheel emulation is useful for getting wheel-like
 102 behaviour with trackballs.  It can also be useful for mice with 4 or
 103 more buttons but no wheel.  See the description of the
 104 .BR EmulateWheelButton ,
 105 .BR EmulateWheelInertia ,
 106 .BR EmulateWheelTimeout ,
 107 .BR XAxisMapping ,
 108 and
 109 .B YAxisMapping
 110 options.  Default: off. Property "Evdev Wheel Emulation".
 111 .TP 7
 112 .BI "Option \*qEmulateWheelButton\*q \*q" integer \*q
 113 Specifies which button must be held down to enable wheel emulation mode.
 114 While this button is down, X and/or Y pointer movement will generate button
 115 press/release events as specified for the
 116 .B XAxisMapping
 117 and
 118 .B YAxisMapping
 119 settings. If the button is 0 and
 120 .BR EmulateWheel
 121 is on, any motion of the device is converted into wheel events. Default: 4.
 122 Property: "Evdev Wheel Emulation Button".
 123 .TP 7
 124 .BI "Option \*qEmulateWheelInertia\*q \*q" integer \*q
 125 Specifies how far (in pixels) the pointer must move to generate button
 126 press/release events in wheel emulation mode.  Default: 10. Property: "Evdev
 127 Wheel Emulation Inertia".
 128 .TP 7
 129 .BI "Option \*qEmulateWheelTimeout\*q \*q" integer \*q
 130 Specifies the time in milliseconds the
 131 .BR EmulateWheelButton
 132 must be pressed before wheel emulation is started. If the
 133 .BR EmulateWheelButton
 134 is released before this timeout, the original button press/release event
 135 is sent.  Default: 200. Property: "Evdev Wheel Emulation Timeout".
 136 .TP 7
 137 .BI "Option \*qEmulateThirdButton\*q \*q" boolean \*q
 138 Enable third button emulation. Third button emulation emits a right button
 139 event (by default) by pressing and holding the first button. The first
 140 button must be held down for the configured timeout and must not move more
 141 than the configured threshold for the emulation to activate. Otherwise, the
 142 first button event is posted as normal. Default: off.  Property: "Evdev
 143 Third Button Emulation".
 144 .TP 7
 145 .BI "Option \*qEmulateThirdButtonTimeout\*q \*q" integer \*q
 146 Specifies the timeout in milliseconds between the initial button press and
 147 the generation of the emulated button event.
 148 Default: 1000. Property: "Evdev Third Button Emulation Timeout".
 149 .TP 7
 150 .BI "Option \*qEmulateThirdButtonButton\*q \*q" integer \*q
 151 Specifies the physical button number to be emitted if third button emulation
 152 is triggered.
 153 Default: 3.  Property: "Evdev Third Button Button".
 154 .TP 7
 155 .BI "Option \*qEmulateThirdButtonMoveThreshold\*q \*q" integer \*q
 156 Specifies the maximum move fuzz in device coordinates for third button
 157 emulation. If the device moves by more than this threshold before the third
 158 button emulation is triggered, the emulation is cancelled and a first button
 159 event is generated as normal.
 160 Default: 20. Property: "Evdev Third Button Emulation Threshold".
 161 .TP 7
 162 .BI "Option \*qGrabDevice\*q \*q" boolean \*q
 163 Force a grab on the event device. Doing so will ensure that no other driver
 164 can initialise the same device and it will also stop the device from sending
 165 events to /dev/kbd or /dev/input/mice. Events from this device will not be
 166 sent to virtual devices (e.g. rfkill or the Macintosh mouse button emulation).
 167 Default: disabled.
 168 .TP 7
 169 .BI "Option \*qInvertX\*q \*q" Bool \*q
 170 .TP 7
 171 .BI "Option \*qInvertY\*q \*q" Bool \*q
 172 Invert the given axis. Default: off. Property: "Evdev Axis Inversion".
 173 .TP 7
 174 .BI "Option \*qIgnoreRelativeAxes\*q \*q" Bool \*q
 175 .TP 7
 176 .BI "Option \*qIgnoreAbsoluteAxes\*q \*q" Bool \*q
 177 Ignore the specified type of axis. Default: unset. The X server cannot deal
 178 with devices that have both relative and absolute axes. Evdev tries to guess
 179 wich axes to ignore given the device type and disables absolute axes for
 180 mice and relative axes for tablets, touchscreens and touchpad. These options
 181 allow to forcibly disable an axis type. Mouse wheel axes are exempt and will
 182 work even if relative axes are ignored. No property, this configuration must
 183 be set in the configuration.
 184 .br
 185 If either option is set to False, the driver will not ignore the specified
 186 axes regardless of the presence of other axes. This may trigger buggy
 187 behavior and events from this axis are always forwarded. Users are
 188 discouraged from setting this option.
 189 .TP 7
 190 .BI "Option \*qCalibration\*q \*q" "min-x max-x min-y max-y" \*q
 191 Calibrates the X and Y axes for devices that need to scale to a different
 192 coordinate system than reported to the X server. This feature is required
 193 for devices that need to scale to a different coordinate system than
 194 originally reported by the kernel (e.g. touchscreens). The scaling to the
 195 custom coordinate system is done in-driver and the X server is unaware of
 196 the transformation. Property: "Evdev Axis Calibration".
 197 .TP 7
 198 .B Option \*qMode\*q \*qRelative\*q\fP|\fP\*qAbsolute\*q
 199 Sets the mode of the device if device has absolute axes.
 200 The default value for touchpads is relative, for other absolute.
 201 This option has no effect on devices without absolute axes.
 202 .TP 7
 203 .BI "Option \*qSwapAxes\*q \*q" Bool \*q
 204 Swap x/y axes. Default: off. Property: "Evdev Axes Swap".
 205 .TP 7
 206 .BI "Option \*qXAxisMapping\*q \*q" "N1 N2" \*q
 207 Specifies which buttons are mapped to motion in the X direction in wheel
 208 emulation mode.  Button number
 209 .I N1
 210 is mapped to the negative X axis motion and button number
 211 .I N2
 212 is mapped to the positive X axis motion.  Default: no mapping. Property:
 213 "Evdev Wheel Emulation Axes".
 214 .TP 7
 215 .BI "Option \*qYAxisMapping\*q \*q" "N1 N2" \*q
 216 Specifies which buttons are mapped to motion in the Y direction in wheel
 217 emulation mode.  Button number
 218 .I N1
 219 is mapped to the negative Y axis motion and button number
 220 .I N2
 221 is mapped to the positive Y axis motion.  Default: "4 5". Property:
 222 "Evdev Wheel Emulation Axes".
 223
 224 .SH SUPPORTED PROPERTIES
 225 The following properties are provided by the
 226 .B evdev
 227 driver.
 228 .TP 7
 229 .BI "Evdev Axis Calibration"
 230 4 32-bit values, order min-x, max-x, min-y, max-y or 0 values to disable
 231 in-driver axis calibration.
 232 .TP 7
 233 .BI "Evdev Axis Inversion"
 234 2 boolean values (8 bit, 0 or 1), order X, Y. 1 inverts the axis.
 235 .TP 7
 236 .BI "Evdev Axes Swap"
 237 1 boolean value (8 bit, 0 or 1). 1 swaps x/y axes.
 238 .TP 7
 239 .BI "Evdev Drag Lock Buttons"
 240 8-bit. Either 1 value or pairs of values. Value range 0-32, 0 disables a
 241 value.
 242 .TP 7
 243 .BI "Evdev Middle Button Emulation"
 244 1 boolean value (8 bit, 0 or 1).
 245 .TP 7
 246 .BI "Evdev Middle Button Timeout"
 247 1 16-bit positive value.
 248 .TP 7
 249 .BI "Evdev Wheel Emulation"
 250 1 boolean value (8 bit, 0 or 1).
 251 .TP 7
 252 .BI "Evdev Wheel Emulation Axes"
 253 4 8-bit values, order X up, X down, Y up, Y down. 0 disables a value.
 254 .TP 7
 255 .BI "Evdev Wheel Emulation Button"
 256 1 8-bit value, allowed range 0-32, 0 disables the button.
 257 .TP 7
 258 .BI "Evdev Wheel Emulation Inertia"
 259 1 16-bit positive value.
 260 .TP 7
 261 .BI "Evdev Wheel Emulation Timeout"
 262 1 16-bit positive value.
 263
 264 .SH AUTHORS
 265 Kristian Høgsberg, Peter Hutterer
 266 .SH "SEE ALSO"
 267 __xservername__(__appmansuffix__), __xconfigfile__(__filemansuffix__), Xserver(__appmansuffix__), X(__miscmansuffix__)