* updating Changelog
[expresskeys.git] / USAGE
1
2 Please direct any bug reports or questions to the top address in the AUTHORS
3 file. This program is _not_ a linuxwacom project.
4
5 ///////////////////////////////////////////////////////////////////////////
6
7 Important: If you use the linuxwacom-0.6.7-beta or in the future released
8 versions you must change the pad statement in X config file to:
9
10 Section "ServerLayout"
11 [...]
12 InputDevice "pad" # Intuos3/Cintiq 21UX/Graphire4. It must NOT send core event
13 [...]
14 EndSection
15
16 See: http://linuxwacom.sourceforge.net/index.php/howto/srvlayout
17
18 If you use the old pad statement, any pad button press can jump the mouse
19 cursor to the upper left corner (0,0) when another tool isn't in proximity.
20
21 ///////////////////////////////////////////////////////////////////////////
22
23 Important: linuxwacom-0.7.5-2 or greater is now required for ALL tablets!
24
25 A quick way to find out which release you have installed is to do a
26 "xsetwacom -V" in a terminal (it should say 0.0.7 or more for linuxwacom-0.7.5-2
27 and newer releases). Ask your distro maintainers to update the linuxwacom
28 packages if they are too old. Or install from source yourself, it is not that
29 hard...
30
31 ///////////////////////////////////////////////////////////////////////////
32
33 Important: Gimp doesn't know _anything_ about a "pad" device, so the option
34 File --> Preferences --> Input Devices --> Configure Extended Input Devices...
35 --> [Device: pad  Mode: Disabled] is how it should be set. If you change it
36 to Sceen or Window, pressing pad buttons or using touch strips will NOT work.
37
38 ///////////////////////////////////////////////////////////////////////////
39
40 USAGE of expresskeys:
41
42 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
43
44 * Program can not be started unless X is running (except for sending signals
45 to an already launched copy), and refuses to start if a daemon instance of the
46 program is detected (through a live pid-file).
47
48 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
49
50 * Command line:
51
52 Usage: expresskeys [OPTION]... [DEVICE]...
53 Any combination of pad and/or stylus can be specified.
54 An empty command line means automatic device search.
55 Options can be written like -dv or -d --v in any place.
56
57   -d makes the program a daemon (runs in the background).
58   -k terminates (kills) an already running daemon instance.
59   -r re-reads the configuration files of a running daemon.
60   -s tells a daemon instance to report status (file/screen).
61   -v prints info to the screen at many execution points.
62   -x sets -v and exits after some important info blocks.
63   -h unconditionally brings up this help text.
64
65 Example1: expresskeys -d (All 'pad's and/or 'stylus'es found get used)
66 Example2: expresskeys 1stIntuos3Pad 1stIntuos3Stylus2 -d (named devices)
67 Example3: expresskeys -rv (visibly re-read the configuration file)
68
69 The names of pad or stylus devices are the "Identifier" strings in your X
70 config file (xorg.conf). Myself I start expresskeys just before the window
71 manager in .xinitrc with: /usr/local/bin/expresskeys -d
72
73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
74
75 * Minimal configuration files are written on first run to the user home
76 directory: ~/.expresskeys/intuos3.conf1 (.conf2 .conf3) for each connected
77 tablet. Max 15: intuos3.conf1/2/3, intuos3s.conf1/2/3, graphire4.conf1/2/3,
78 graphire4bt.conf1/2/3 and padless.conf1/2/3.
79
80 'Models': nopad, Graphire4 BlueTooth, Graphire4, Intuos3 small, Intuos3/Cintiq
81
82 The files contain "default", "Gimp", "Blender" and "XTerm" entries and are
83 re-created on program start whenever a configuration file for a connected
84 tablet is missing.
85
86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
87
88 * A file with the program PID number is written if run with -d in:
89 ~/.expresskeys/expresskeys.pid
90
91 The pid-file is deleted on normal program exit like "expresskeys -k"
92
93 You can also type "kill <pid>", "killall expresskeys", "kill -TERM <pid>" etc.
94 A brutal "kill -9 <pid>" or a program crash will leave the pid-file undeleted.
95 This is also the case if the program is terminated by X close-down on some
96 systems.
97
98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
99
100 * The ~/.expresskeys/status.log (created on program daemon launch) is updated
101 whenever an "expresskeys -s" is used. It provides the same information as a
102 non-daemon run with "expresskeys -x" would do. Just like the pid-file, it is
103 deleted on normal program exit.
104
105 This action can also be performed by doing a "kill -USR2 <pid-of-expresskeys>".
106
107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
108
109 * All the configuration files are re-read when you do an "expresskeys -r" and a
110 daemon instance of the program is running.
111
112 This action can also be performed by doing a "kill -USR1 <pid-of-expresskeys>"
113 after a config file edit.
114
115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
116
117 NOTE: There's a graphical point-and-click program in the offing at:
118 http://alavaliant.googlepages.com that already supports expresskeys 0.2.x
119 config file editing. The pygtk (2.8+) program is called "wacom-config"
120 and will be updated to support expresskeys 0.3.x. It really does obsolete
121 the following explanations of how to find keycodes and program names :NOTE
122
123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
124
125 * Use the X program "xev" to find keycodes when changing the configuration.
126
127 Since I've received a request for an explanation, I'll quote the reply:
128
129 --Begin Letter--
130
131 > I'm using your expresskeys for my intous3 but I'm
132 > a linux newbie and now I'm a bit confused, what is
133 > the right keycode or config for the arrow key.
134 >
135 > I want Space on 12
136 > Left arrow on 9
137 > Right arrow on 10
138
139 Keycodes are both confusing and simple, at the same time ;-) They are
140 different depending on your language and keyboard design, and also
141 different if you are in X or not, but share some common details.
142
143 To find how they are organized on your own keyboard, you must use a
144 program. First (if you are in X as you should be) open a terminal. The
145 only one I have per default is "xterm" since I don't use gnome or kde or
146 anything like that, where a terminal window can be called just
147 "terminal"... Other standalone terminals are "aterm", "rxvt", "eterm"
148 etc.
149
150 Now start a program from within the open terminal. One that _must_ be
151 present on your system (I think) is "xev". It comes as standard with X.
152 When you start xev it spawns another window (small white square) and
153 spits out a lot of info in the terminal window. You must move the mouse
154 pointer to the square window before doing any key presses.
155
156 Ok, now I'll press Space, Left Arrow and Right Arrow:
157
158 KeyPress event, serial 27, synthetic NO, window 0x1200001,
159     root 0x115, subw 0x0, time 5261195, (128,125), root:(138,145),
160     state 0x0, keycode 65 (keysym 0x20, space), same_screen YES,
161     XLookupString gives 1 bytes: (20) " "
162     XmbLookupString gives 1 bytes: (20) " "
163     XFilterEvent returns: False
164
165 The important information here is the "keycode 65 (keysym 0x20, space)".
166 There will be another information dump when you release the space key,
167 called KeyRelease.
168
169 So on my Swedish keyboard, X uses the keycode 65 to represent the
170 spacebar. Ok, here's Left Arrow:
171
172 KeyPress event, serial 27, synthetic NO, window 0x1200001,
173     root 0x115, subw 0x0, time 5281166, (128,125), root:(138,145),
174     state 0x0, keycode 100 (keysym 0xff51, Left), same_screen YES,
175     XLookupString gives 0 bytes:
176     XmbLookupString gives 0 bytes:
177     XFilterEvent returns: False
178
179 Keycode is 100 here. Let's go to Right Arrow:
180
181 KeyPress event, serial 27, synthetic NO, window 0x1200001,
182     root 0x115, subw 0x0, time 5283438, (128,125), root:(138,145),
183     state 0x0, keycode 102 (keysym 0xff53, Right), same_screen YES,
184     XLookupString gives 0 bytes:
185     XmbLookupString gives 0 bytes:
186     XFilterEvent returns: False
187
188 So it's 102. When you are finished looking for the keycodes, give the
189 terminal window focus (place the mouse cursor there or whatever) and
190 press Ctrl-c (you can also click on the close button of the white square
191 window).
192
193 That's how it looks on this Swedish keyboard. Now open the expresskeys
194 configuration file with any editor. The location is a hidden directory
195 in your home directory. Here's mine:
196
197 /home/loke/.expresskeys/intuos3.conf1
198
199 Replace the keycodes in the section you are interested in, I'd do:
200 [Original configfile version 2 text here updated to version 4. Ed.]
201
202 LeftPadButton9        100     # Button 9 Left Arrow (Max keycodes to send is 32)
203 LeftPadButton10       102     # Button 10 Right Arrow
204 LeftPadButton11       37      # Button 11 Control
205 LeftPadButton12       65      # Button 12 Space (was default)
206
207 Save the file and read in the new values with "expresskeys -r"
208
209 [Since each button/touch strip/scroll wheel now can send 32 keycodes at a time,
210 I've deleted the original paragraph here. Ed.]
211
212 --End Letter--
213
214 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
215
216 * Use the X program "xprop" to find the name string to use when changing
217 the configuration. xprop without any arguments expects you to then click
218 on the target window. We are looking for the WM_CLASS info so running:
219
220 $ xprop | grep WM_CLASS
221 WM_CLASS(STRING) = "VCLSalFrame", "OpenOffice.org 1.1.4"
222
223 It's the last string we would use, the "OpenOffice.org 1.1.4". We always
224 use the last part, and the spelling is case sensitive. Putting
225 "openoffice.org 1.1.4" in the configuration file would not match up.
226
227 A cleaner looking output from xprop can be had by eg running:
228
229 $ xprop | grep WM_CLASS | cut -d ',' -f2
230  "OpenOffice.org 1.1.4"
231
232 Also, since spaces are accepted as part of a class name, make sure there
233 are no space _before or after_ the name, within the double quotes:
234
235 "A ProgramName" <-- OK
236 " A ProgramName" or "A ProgramName " <-- NOT-OK
237
238 The extra space/s would become part of the class name. Not what you want.
239
240 The very first entry (at the top) in the configuration file is named
241 "default" and holds a key definition for all programs not specified in
242 another entry. It also takes care of the root window (the "background")
243 and programs lacking a class name in their WM_CLASS.
244
245 [NOTE: the backgrounds in desktop programs like Gnome and KDE are not true
246 'roots' and therefore have their own names, currently "Kdesktop" and "Nautilus".
247 Create separate entries with these names if you want them to be handled
248 differently than how the "default" program record does things :END NOTE]
249
250 The "default" record must always exist in the configuration file! But it
251 doesn't matter _where_. Put it last or first or wherever...
252
253 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
254
255 NEW in expresskeys version 0.4.0 and above:
256
257 Config file version 4 has gone even further than version 3 in independence.
258 For example, this is a minimally accepted configuration file:
259
260 ConfigVersion 4
261 %%
262 ProgramName "default"
263
264 Expresskeys will not accomplish anything with such a minimalistic file, but
265 we pass it as valid. That is, all fields not explicitly defined on the first
266 file read are set to zero (0). Though, deleted fields are not reset to zero on
267 a re-read. If more than one field with the same keyword is written in a program
268 record, only the last one found is used on a re-read of the configuration file
269 (except for the 'string' fields ProgramName, Stylus1PressCurve and
270 Stylus2PressCurve, where only the first occurrence found is used).
271
272 All the fields ending with "Plus" have been eliminated in version 4. They are
273 not needed anymore since each regular keycode field can have as much as 32
274 keycodes specified.
275
276 New fields in version 4 (and their default values) are:
277
278 _All tablets_:
279
280 (Yet another stylus to have an automatic PressCurve set)
281 Stylus2PressCurve "0 0 100 100" # PressCurve must be within double quotes ""
282
283 _Graphire4 BlueTooth, Graphire4, Intuos3 small, Intuos3/Cintiq_:
284
285 (A pause to place between sending of each keycode)
286 DelayEachKeycode        0.0     # Seconds (Max 10 - Min 0.01 - Or no delay)
287
288 (How long to wait before beginning auto-repeat of a held down button)
289 ButtonRepeatAfter       0.5     # Seconds (Max 10 - Min 0.01 - Or no delay)
290
291 (A pause to place between each button repeat when in auto-repeat mode)
292 DelayButtonRepeat       0.1     # Seconds (Max 10 - Min 0.01 - Or no delay)
293
294 _Intuos3 small, Intuos3/Cintiq_:
295
296 (If a button should auto-repeat or not)
297 RepeatButton9           0       # Switch 1/0 (Press and hold button repeat keys)
298 RepeatButton10          0       # Switch 1/0 (Press and hold button repeat keys)
299 .
300 .
301
302 _Graphire4 BlueTooth, Graphire4_:
303
304 (If a button should auto-repeat or not)
305 RepeatLeft              0       # Switch 1/0 (Press and hold button repeat keys)
306 RepeatRight             0       # Switch 1/0 (Press and hold button repeat keys)
307
308 _Intuos3 small, Intuos3/Cintiq_:
309
310 (How long to wait before beginning auto-repeat of a held touch strip)
311 TouchRepeatAfter        0.6     # Seconds (Max 10 - Min 0.01 - Or no delay)
312
313 (A pause to place between each touch strip repeat when in auto-repeat mode)
314 DelayTouchRepeat        0.1     # Seconds (Max 10 - Min 0.01 - Or no delay)
315
316 (If a touch strip should auto-repeat or not)
317 RepeatLeftUp            1       # Switch 1/0 (Finger held at top repeat keys)
318 RepeatLeftDown          1       # Switch 1/0 (Finger held at bottom repeat keys)
319 .
320 .
321
322 Apart from these fields there are some new 'fake keycodes' to use (for tablet
323 Rotate and stylus PressCurve). Full information is provided in a section
324 further down in this file.
325
326 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
327
328 NEW in expresskeys version 0.3.0 and above:
329
330 Config file version 3 is completely independent of how you organize the
331 program fields or records. Only limitation [deleted obsolete limitation. Ed.]
332
333 This open-ended nature was enforced to facilitate the inclusion of
334 future fields - or elimination of already existing ones - without
335 invalidating what the user already has (which happens now when going
336 from version 2 to 3).
337
338 The new field introduced with version 3 is Stylus1PressCurve. Here's
339 what I've written in the README file:
340
341 "It can also provide an automatic change of stylus pressure sensitivity - aka
342 PressCurve - going from one program window to the next, by way of "xsetwacom"
343 from the driver package at linuxwacom.sourceforge.net This feature is
344 independent of the connected tablet model."
345
346 Finding good numbers (they must be in groups of four) for this field is
347 not an intuitive act... The "wacomcpl" program - the tcl utility from
348 linuxwacom - uses a slider (stylus/eraser --> Feel --> Sensitivity)
349 with steps from 1 (Soft) to 7 (Firm) and 4 being the default. It then
350 calls the "xsetwacom" program to actually set a true "Bezier curve".
351
352 The seven curves chosen by wacomcpl are (Soft to Firm):
353
354 1               2               3               4 (default)
355 "0 75 25 100" | "0 50 50 100" | "0 25 75 100" | "0 0 100 100"
356 5               6               7
357 "25 0 100 75" | "50 0 100 50" | "75 0 100 25"
358
359 Experimenting with other values can probably be a fun... activity on a
360 rainy day. My thanks go to Pablo Gimenez, a user who wanted this
361 automatic pressure sensitivity change. He made me start thinking about
362 a possible implementation.
363
364 It works really well but, as I've written in the BUGS file:
365
366 --Quote--
367
368 [The grisly story about Qt-based programs, like KDE, deleted. See BUGS. Ed.]
369
370 --Unquote--
371
372 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
373
374 The "default" entry holds keycodes to make the pad buttons behave just
375 as Wacom list them in the Quick Start Guide: Shift, Alt, Ctrl and Space
376 mirrored on both sides. Touch Strip and Scroll Wheel support is turned on by
377 default. Use the number 0 in the "HandleTouchStrips" field to turn it off
378 (a Graphire4 user changes the "HandleScrollWheel" field). You get
379 'Mouse-scrolling' Up/Down on the left strip (wheel) and Arrow-key Right/Left
380 on the right with the values currently written to the minimal config file.
381 Change direction of the movement by switching the "Up" and "Down" values.
382
383 Both pad buttons and touch strips/scroll wheel can send 32 keys at a time if
384 so configured.
385
386 * Fake keycodes: 991, 992, 993, 994, 995, 996, 997 *
387 If you want a button to do a mouse button press instead of a keypress,
388 use a value between 991 and 997 in the corresponding keycode field, where
389 991 represents mouse button 1, 992 button 2, and so on. Only existing mouse
390 buttons, defined through the driver of the active core pointer, can be
391 simulated. If buttons 4 and 5 are available they normally control vertical
392 scrolling, like the mouse's scroll wheel (button 4 scrolls up, button 5
393 scrolls down.) If buttons 6 and 7 are available they may control horizontal
394 scrolling (button 6 scrolls left, button 7 scrolls right) or may match
395 extra buttons on the mouse.
396
397 * Fake keycode: 999 *
398 If you want a button to do stylus mode toggling between Absolute and Relative,
399 use the value 999 in the corresponding keycode field. To be able to switch
400 mode anywhere each program block must contain one 999 definition.
401
402 * Fake keycodes: 1001, 1002, 1003 *
403 Instead of defining a fixed stylus PressCurve for different program blocks,
404 you can use three values as keycodes to alter the curve interactively. 1001
405 will decrease the PressCurve, while 1003 will increase it. 1002 restores the
406 curve to its default state: "0 0 100 100". Both the upward and downward curve
407 changes flip over in a carousel fashion at the top and bottom values.
408
409 * Fake keycodes: 1004, 1005, 1006, 1007, 1008, 1009 *
410 Use the value 1004 to return from a tablet rotation (NONE), 1005 to flip a
411 tablet 180 degrees (HALF), 1006 to rotate 90 degrees clock-wise (CW) and
412 1007 to rotate 90 degrees counter-clock-wise (CCW). By using 1008 you can
413 rotate the tablet endlessly in a clock-wise manner (CW-HALF-CCW-NONE-CW-)
414 and 1009 does the same motion counter-clock-wise (CCW-HALF-CW-NONE-CCW-).
415 Looking down on the tablet and tilting the head '90' degrees to the right
416 would simulate a CW operation.
417
418 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
419
420 The "Gimp" entry also has the touch strips (wheel) turned on by default,
421 and I've populated it with keycodes that I actually use myself. This was
422 done to minimize confusion about how to fill in the fields. As it stands,
423 they are (for my Swedish keyboard):
424
425 20 = "+" = Gimp Zoom In. Left touch strip up motion (G4: wheel up)
426 61 = "-" = Gimp Zoom Out. Left touch strip down motion (G4: wheel down)
427
428 64 = "Alt" plus 20 = "+" = Gimp Next Brush. Right touch strip up motion
429 64 = "Alt" plus 61 = "-" = Gimp Previous Brush. Right touch strip down motion
430
431 (The above has been configured through the Gimp menu: File -> Preferences ->
432 Interface -> Configure Keyboard Shortcuts -> Context)
433
434 50 = "Shift" = Button 9
435 64 = "Alt"   = Button 10 (Holding this, copies Right touch strip to Left!)
436 37 = "Ctrl"  = Button 11
437 65 = "Space" = Button 12
438
439 37 = "Ctrl" plus 29 = "y" = Gimp Redo. Button 13 (G4: left button)
440 37 = "Ctrl" plus 52 = "z" = Gimp Undo. Button 14 (G4: right button)
441 999 = "Stylus Mode Toggle" = Button 15
442 65 = "Space" = Button 16
443
444 The "Blender" entry is similarly a private choice for the 3D program blender.
445
446 I felt, and feel, that an "XTerm" is too important a window to have _any_
447 interference from the pad. But observe that I want to be able to switch
448 stylus mode even with such a window in focus, so I've set 999 in one field.
449
450 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
451
452 Below is some ASCII art showing the "default" program record:
453
454 Left ExpressKey Pad
455 ------------
456 |  |   |   |            Wacom Intuos3 defaults are:
457 |  | 9 | T |
458 |11|---| O |            Key 9  = (left) Shift   = keycode 50
459 |  |10 | U |            Key 10 = (left) Alt     = keycode 64
460 |------| C |            Key 11 = (left) Control = keycode 37
461 |  12  | H |            Key 12 = Space          = keycode 65
462 ------------
463
464 Right ExpressKey Pad
465 ------------
466 |   |   |  |            Wacom Intuos3 defaults are:
467 | T |13 |  |
468 | O |---|15|            Key 13 = (left) Shift   = keycode 50
469 | U |14 |  |            Key 14 = (left) Alt     = keycode 64
470 | C |------|            Key 15 = (left) Control = keycode 37
471 | H |  16  |            Key 16 = Space          = keycode 65
472 ------------
473
474
475            ExpressKeys Pad
476 --------------------------------------
477 | Left Button | Wheel | Right Button |
478 --------------------------------------
479
480     Wacom Graphire4 defaults are:
481
482 Left Button  = (left) Shift   = keycode 50
483 Right Button = (left) Alt     = keycode 64
484
485
486            ExpressKeys Pad
487     -------------------------------
488     | Left Button || Right Button |
489     -------------------------------
490
491     Wacom Graphire4 BT defaults are:
492
493 Left Button  = (left) Shift   = keycode 50
494 Right Button = (left) Alt     = keycode 64
495
496 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
497
498 Sometimes desktops or window managers "steal" certain keypresses/combinations.
499 If you experience that, look for a way to change the keybindings of your
500 environment.
501
502 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
503