chiark / gitweb /
Offsets: In button zone code, cope with negative "pos" values
[xf86-input-mtrack.git] / README.md
1 xf86-input-mtrack
2 =================
3
4 An Xorg driver for multitouch trackpads. Supports any trackpad whose kernel
5 driver uses the slotted multitouch protocol. For more information on the
6 protocol see the [kernel documentation][1].
7
8 This driver is compatible with Xorg server versions 1.7 to 1.12. It requires
9 the [mtdev][4] library to operate.
10
11 License
12 -------
13
14 * Copyright (C) 2011 Ryan Bourgeois <bluedragonx@gmail.com>
15 * Copyright (C) 2008 Henrik Rydberg <rydberg@euromail.se>
16
17 This software is licensed under the [GPLv2][2] and is a fork of the
18 [xf86-input-multitouch][3] driver by Henrik Rydberg.
19
20 Binaries
21 --------
22
23 * [Gentoo][5]
24 * [Ubuntu][6]
25 * [Arch][7]
26
27 Arch package contributed and maintained by Mike Zackles.
28
29 Building and Installing
30 -----------------------
31 This is a standard autoconf package. So:
32
33     ./configure
34     make && make install
35
36 It is likely that you will need to change system-dependent paths such as the
37 xorg module directory. See `configure --help` for options.
38
39 Configuration
40 -------------
41
42 The following is a minimal working InputClass section for xorg.conf:
43
44     Section "InputClass"
45         MatchIsTouchpad "on"
46         Identifier      "Touchpads"
47         Driver          "mtrack"
48     EndSection
49
50 Configuration options may be defined inside the InputClass section to configure
51 the driver. Available options and their defaults are as follows.
52
53 **TrackpadDisable** -
54 Disables trackpad touch input. A value of 0 will enable the trackpad. A value
55 of 1 will disable tapping and gestures but not movement. A value of 2 will
56 disable all input. A value of 3 will also disable physical buttons. Integer.
57 Default is 0.
58
59 **Sensitivity** - 
60 Adjusts the sensitivity (movement speed) of the touchpad. This is a real number
61 greater than or equal to zero. Default is 1. A value of 0 will disable pointer
62 movement.
63
64 **FingerHigh** - 
65 Defines the pressure at which a finger is detected as a touch. This is a
66 percentage represented as an integer. Default is 5.
67
68 **FingerLow** - 
69 Defines the pressure at which a finger is detected as a release. This is a
70 percentage represented as an integer. Default is 5.
71
72 **IgnoreThumb** - 
73 Whether or not to ignore touches that are determined to be thumbs. Boolean
74 value. Defaults to false.
75
76 **IgnorePalm** - 
77 Whether or not to ignore touches that are determined to be palms. Boolean
78 value. Defaults to false.
79
80 **DisableOnThumb** - 
81 Whether or not to disable the entire trackpad when a thumb is touching. Boolean
82 value. Defaults to false.
83
84 **DisableOnPalm** - 
85 Whether or not to disable the entire trackpad when a palm is touching. Boolean
86 value. Defaults to false.
87
88 **ThumbRatio** - 
89 The width/length ratio of what's considered a thumb. It is expected that a
90 thumb is longer than it is wide. This tells the driver how much longer.
91 Percentage represented by an integer. Defaults to 70.
92
93 **ThumbSize** - 
94 The minimum size of what's considered a thumb. It is expected that a thumb
95 will be larger than other fingers. This is represented as a percentage of the
96 maximum touch value and is dependent on the trackpad hardware. Integer value.
97 Defaults to 25.
98
99 **PalmSize** - 
100 The minimum size of what's considered a palm. Palms are expected to be very
101 large on the trackpad. This is represented as a percentage of the maximum touch
102 value and is dependent on the trackpad hardware. Integer value. Defaults to 40.
103
104 **BottomEdge** -
105 The size of an area at the bottom of the trackpad where new touches are ignored
106 (fingers traveling into this area from above will still be tracked). This is
107 represented as a percentage of the total trackpad height. Defaults to 10.
108
109 **ButtonEnable** - 
110 Whether or not to enable the physical buttons on or near the trackpad. Boolean
111 value. Defaults to true.
112
113 **ButtonIntegrated** - 
114 Whether or not the physical buttons are integrated with the trackpad. If you
115 have a one-piece trackpad like on newer MacBooks, this should be set to true.
116 Button emulation depends on this value being correct. Boolean value. Defaults
117 to true.
118
119 **ButtonMoveEmulate**
120 Whether or not to count the moving finger when emulating button clicks. Useful to disable if you use two hands on trackpad. Boolean value. Defaults to true.
121
122 **ButtonZonesEnable** -
123 Whether or not to enable button zones. If button zones are enabled then the
124 trackpad will be split into one, two, or three vertical zones. Clicking the
125 integrated button in one of these zones will send the button event for
126 ClickFinger1, ClickFinger2, or ClickFinger3. The driver will only add zones for
127 those ClickFinger values that are enabled. So setting ClickFinger1 to 0 and
128 enabling the other two will create two zones, one for ClickFinger2 and one for
129 ClickFinger3. Boolean value. Defaults to false.
130
131 **BottomEdgeZonesEnable** -
132 Whether to enable button zones in the bottom edge.  If this feature is
133 enabled then touches in the BottomEdge region determine which button
134 is sent.  The vertical division of the zones is as for
135 ButtonZonesEnable.  If there is no touch in the bottom edge, then
136 button 0 will be sent (or the button according to ButtonZonesEnable,
137 if that is enabled).  This is particularly useful for clickpads with
138 integrated buttons. Defaults to false.
139
140 **ButtonTouchExpire** - 
141 How long (in ms) to consider a touching finger as part of button emulation. A
142 value of 0 will not expire touches. Integer value. Defaults to 100.
143
144 **ClickFinger1** - 
145 Which button to emulate when one finger is touching the trackpad during a
146 click. Integer value. A value of 0 disables one-touch emulation. Defaults to 3.
147
148 **ClickFinger2** - 
149 Which button to emulate when two fingers are touching the trackpad during a
150 click. Integer value. A value of 0 disabled one-touch emulation. Defaults to 2.
151
152 **ClickFinger3** - 
153 Which button to emulate when three fingers are touching the trackpad during a
154 click. Integer value. A value of 0 disabled one-touch emulation. Defaults to 0.
155
156 **TapButton1** - 
157 Which button to emulate for one-finger tapping. Integer value. A value of 0
158 disables one-finger tapping. Defaults to 1.
159
160 **TapButton2** - 
161 Which button to emulate for two-finger tapping. Integer value. A value of 0
162 disables two-finger tapping. Defaults to 3.
163
164 **TapButton3** - 
165 Which button to emulate for three-finger tapping. Integer value. A value of 0
166 disables three-finger tapping. Defaults to 2.
167
168 **TapButton4** - 
169 Which button to emulate for four-finger tapping. Integer value. A value of 0
170 disables three-finger tapping. Defaults to 0.
171
172 **ClickTime** - 
173 When tapping, how much time to hold down the emulated button. Integer value
174 representing milliseconds. Defaults to 50.
175
176 **MaxTapTime** - 
177 The amount of time to wait for a tap to release before counting it as a move.
178 Integer value representing milliseconds. Defaults to 120.
179
180 **MaxTapMove** - 
181 How far a touch is allowed to move before counting it is no longer considered a
182 tap. Integer value. Defaults to 400.
183
184 **GestureClickTime** - 
185 When a gesture triggers a click, how much time to hold down the emulated button.
186 Integer value representing milliseconds. Defaults to 10.
187
188 **GestureWaitTime** - 
189 Touches are allowed to transition from one gesture to another. For example, you
190 may go from scrolling to swiping without releasing your fingers from the pad.
191 This value is the amount of time you must be performing the new gesture before
192 it is triggered. This prevents accidental touches from triggering other
193 gestures. Integer value representing milliseconds. Defaults to 100.
194
195 **ScrollDistance** - 
196 For two finger scrolling. How far you must move your fingers before a button
197 click is triggered. Integer value. Defaults to 150.
198
199 **ScrollUpButton** - 
200 For two finger scrolling. The button that is triggered by scrolling up. Integer
201 value. A value of 0 disables scrolling up. Defaults to 4.
202
203 **ScrollDownButton** - 
204 For two finger scrolling. The button that is triggered by scrolling down.
205 Integer value. A value of 0 disables scrolling down. Defaults to 5.
206
207 **ScrollLeftButton** - 
208 For two finger scrolling. The button that is triggered by scrolling left.
209 Integer value. A value of 0 disables scrolling left. Defaults to 6.
210
211 **ScrollRightButton** - 
212 For two finger scrolling. The button that is triggered by scrolling right.
213 Integer value. A value of 0 disables scrolling right. Defaults to 7.
214
215 **SwipeDistance** - 
216 For three finger swiping. How far you must move your fingers before a button
217 click is triggered. Integer value. Defaults to 700.
218
219 **SwipeUpButton** - 
220 For three finger swiping. The button that is triggered by swiping up. Integer
221 value. A value of 0 disables swiping up. Defaults to 8.
222
223 **SwipeDownButton** - 
224 For three finger swiping. The button that is triggered by swiping down. Integer
225 value. A value of 0 disables swiping down. Defaults to 9.
226
227 **SwipeLeftButton** - 
228 For three finger swiping. The button that is triggered by swiping left. Integer
229 value. A value of 0 disables swiping left. Defaults to 10.
230
231 **SwipeRightButton** - 
232 For three finger swiping. The button that is triggered by swiping right. Integer
233 value. A value of 0 disables swiping right. Defaults to 11.
234
235 **Swipe4Distance** - 
236 For four finger swiping. How far you must move your fingers before a button
237 click is triggered. Integer value. Defaults to 700.
238
239 **Swipe4UpButton** - 
240 For four finger swiping. The button that is triggered by swiping up. Integer
241 value. A value of 0 disables swiping up. Defaults to 8.
242
243 **Swipe4DownButton** - 
244 For four finger swiping. The button that is triggered by swiping down. Integer
245 value. A value of 0 disables swiping down. Defaults to 9.
246
247 **Swipe4LeftButton** - 
248 For four finger swiping. The button that is triggered by swiping left. Integer
249 value. A value of 0 disables swiping left. Defaults to 10.
250
251 **Swipe4RightButton** - 
252 For four finger swiping. The button that is triggered by swiping right. Integer
253 value. A value of 0 disables swiping right. Defaults to 11.
254
255 **ScaleDistance** - 
256 For pinch scaling. How far you must move your fingers before a button click is
257 triggered. Integer value. Defaults to 150.
258
259 **ScaleUpButton** - 
260 For pinch scaling. The button that is triggered by scaling up. Integer value. A
261 value of 0 disables scaling up. Defaults to 12.
262
263 **ScaleDownButton** - 
264 For pinch scaling. The button that is triggered by scaling down. Integer value.
265 A value of 0 disables scaling down. Defaults to 13.
266
267 **RotateDistance** - 
268 For two finger rotation. How far you must move your fingers before a button
269 click is triggered. Integer value. Defaults to 150.
270
271 **RotateLeftButton** - 
272 For two finger rotation. The button that is triggered by rotating left. Integer
273 value. A value of 0 disables rotation left. Defaults to 14.
274
275 **RotateRightButton** - 
276 For two finger rotation. The button that is triggered by rotating right. Integer
277 value. A value of 0 disables rotation right. Defaults to 15.
278
279 **TapDragEnable** - 
280 Whether or not to enable tap-to-drag functionality. Boolean value. Defaults to
281 true.
282
283 **TapDragTime** - 
284 The tap-to-drag timeout. This is how long the driver will wait after a single
285 tap for a movement event before sending the click. Integer value representing
286 milliseconds. Defaults to 350.
287
288 **TapDragWait**
289 How long after detecting movement to trigger a button down event. During this
290 time pointer movement will be disabled. Increase this value if you find you're
291 draggin when you don't wish it. Integer value representing milliseconds.
292 Defaults to 40.
293
294 **TapDragDist**
295 How far the finger is allowed to move during drag wait time. If the finger
296 moves farther than this distance during the wait time then dragging will be
297 canceled and pointer movement will resume. Integer value. Defaults to 200.
298
299 **AxisXInvert**
300 Whether or not to invert the X axis. Boolean value. Defaults to false.
301
302 **AxisYInvert**
303 Whether or not to invert the Y axis. Boolean value. Defaults to false.
304
305 [1]: http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt     "Kernel Multitouch Protocol"
306 [2]: http://www.gnu.org/licenses/gpl-2.0.html                                   "GNU General Public License, version 2"
307 [3]: http://bitmath.org/code/multitouch/                                        "xf86-input-multitouch website"
308 [4]: http://bitmath.org/code/mtdev/                                             "mtdev library website"
309 [5]: http://www.dev.fatalmachine.org/xf86-input-mtrack/gentoo                   "Gentoo Ebuilds"
310 [6]: http://www.dev.fatalmachine.org/xf86-input-mtrack/ubuntu                   "Ubuntu Packages"
311 [7]: http://aur.archlinux.org/packages.php?ID=48505                             "Arch Package"
312