44262bb9515a13c02e21ff4fd0785b7d782d241f
[expresskeys.git] / USAGE
1
2 Please direct any bug reports or questions to the top address in
3 the AUTHORS 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
8 released versions you must change the pad statement in X config
9 file to:
10
11 Section "ServerLayout"
12 [...]
13 InputDevice "pad" # Intuos3/Cintiq 21UX/Graphire4. It must NOT send core event
14 [...]
15 EndSection
16
17 See: http://linuxwacom.sourceforge.net/index.php/howto/srvlayout
18
19 If you use the old pad statement, any pad button press can jump the
20 mouse cursor to the upper left corner (0,0) when another tool isn't
21 in proximity.
22
23 ///////////////////////////////////////////////////////////////////////////
24
25 Important: linuxwacom-0.7.5 or greater is _required_ for Graphire4 support!
26
27 A quick way to find out which release you have installed is to do a
28 "xsetwacom -V" in a terminal (it should say 0.0.7 or more for linuxwacom-0.7.5
29 and newer releases). Ask your distro maintainers to update the linuxwacom
30 packages if they are too old. Or install from source yourself, it is not that
31 hard...
32
33 ///////////////////////////////////////////////////////////////////////////
34
35 Important: Gimp doesn't know _anything_ about a "pad" device, so the option
36 File --> Preferences --> Input Devices --> Configure Extended Input Devices...
37 --> [Device: pad  Mode: Disabled] is how it should be set. If you change it
38 to Sceen or Window, pressing pad buttons or using touch strips will NOT work.
39
40 ///////////////////////////////////////////////////////////////////////////
41
42 USAGE of expresskeys:
43
44 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
45
46 * Program can not be started unless X is running, and refuses to start
47 if a daemon instance of the program is detected (through a live pid-file).
48
49 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
50
51 * Command line:
52
53 Usage: expresskeys [OPTION]... [DEVICE]...
54 Any combination of pad and/or stylus can be specified.
55 An empty command line means automatic device search.
56 Options can be written like -dv or -d -v in any place.
57
58   -d makes the program a daemon (runs in the background).
59   -k terminates (kills) an already running daemon instance.
60   -r re-reads the configuration file of a running daemon.
61   -v prints info to the screen at many execution points.
62   -x sets -v and exits after some important info blocks.
63   -s tells a daemon instance to report status (file/screen).
64   -h unconditionally brings up this help text.
65
66 Example1: expresskeys -d (first 'pad' and/or 'stylus' found get used)
67 Example2: expresskeys 1stIntuos3Pad 1stIntuos3Stylus2 -d (named devices)
68 Example3: expresskeys -rv (visibly re-read the configuration file)
69
70 The names of pad or stylus devices are the "Identifier" strings in your
71 X config file (xorg.conf). Myself I start expresskeys just before the
72 window manager in .xinitrc with: /usr/local/bin/expresskeys -d
73
74 OBS! I've found out that it should be started AFTER any usage of
75 the X program "xmodmap", else expresskeys could crash. Reason unknown.
76 See the BUGS file for further info.
77
78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
79
80 * A minimal configuration file is written on first run to the user home
81 directory: ~/.expresskeys/intuos3.conf1 (graphire4.conf1 or padless.conf1)
82
83 It contains "default", "Gimp", "Blender" and "XTerm" entries and is
84 re-created whenever a configuration file is missing on program start.
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>"
94 etc. A brutal "kill -9 <pid>" or a program crash will leave the pid-file
95 undeleted. This is also the case if the program is terminated by X
96 close-down on some 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
106
107 * The configuration file is re-read when you do an "expresskeys -r" and a
108 daemon instance of the program is running.
109
110 What happens then is that we send the SIGUSR1 signal, which has been
111 defined to call the re_read_file_config function in on_signal.c The
112 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 3. Ed.]
201
202 LeftPadButton9        100     # Button 9 Left Arrow
203 LeftPadButton9Plus    0       # Extra keycode
204
205 LeftPadButton10       102     # Button 10 Right Arrow
206 LeftPadButton10Plus   0       # Extra keycode
207
208 LeftPadButton11       37      # Button 11
209 LeftPadButton11Plus   0       # Extra keycode
210
211 LeftPadButton12       65      # Button 12 Space (was default)
212 LeftPadButton12Plus   0       # Extra keycode
213
214 Save the file and read in the new values with "expresskeys -r"
215
216 The extra key are for when you want two keys pressed. First the normal,
217 then the extra, like Ctrl-s or so. I've been informed that a US keyboard
218 doesn't have a single + key, it's shifted on their = key. So they must
219 use Shift-= in the expresskeys gimp section to zoom in, thereby wasting
220 the extra key. A workaround is to configure gimp itself to zoom by the =
221 key instead of +.
222
223 --End Letter--
224
225 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
226
227 * Use the X program "xprop" to find the name string to use when changing
228 the configuration. xprop without any arguments expects you to then click
229 on the target window. We are looking for the WM_CLASS info so running:
230
231 $ xprop | grep WM_CLASS
232 WM_CLASS(STRING) = "VCLSalFrame", "OpenOffice.org 1.1.4"
233
234 It's the last string we would use, the "OpenOffice.org 1.1.4". We always
235 use the last part, and the spelling is case sensitive. Putting
236 "openoffice.org 1.1.4" in the configuration file would not match up.
237
238 A cleaner looking output from xprop can be had by eg running:
239
240 $ xprop | grep WM_CLASS | cut -d ',' -f2
241  "OpenOffice.org 1.1.4"
242
243 Also, since spaces are accepted as part of a class name, make sure there
244 are no space _before or after_ the name, within the double quotes:
245
246 "A ProgramName" <-- OK
247 " A ProgramName" or "A ProgramName " <-- NOT-OK
248
249 The extra space/s would become part of the class name. Not what you want.
250
251 The very first entry (at the top) in the configuration file is named
252 "default" and holds a key definition for all programs not specified
253 in another entry. It also takes care of the root window (the "background")
254 and programs lacking a class name in their WM_CLASS.
255
256 The "default" record must always exist in the configuration file! But it
257 doesn't matter _where_. Put it last or first or wherever...
258
259 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
260
261 NEW in expresskeys version 0.3.0 and above:
262
263 Config file version 3 is completely independent of how you organize the
264 program fields or records. Only limitation is that all the fields must
265 be _present_ somewhere in the record for it to be counted. In version 3
266 that means 27 fields for a 'pad' device user ('stylus' field is included),
267 11 fields for a Graphire4, and 2 fields for a 'stylus' device only user.
268
269 This open-ended nature was enforced to facilitate the inclusion of
270 future fields - or elimination of already existing ones - without
271 invalidating what the user already has (which happens now when going
272 from version 2 to 3).
273
274 The new field introduced with version 3 is Stylus1PressCurve. Here's
275 what I've written in the README file:
276
277 "It can also provide an automatic change of stylus pressure sensitivity
278 - aka PressCurve - going from one program window to the next, by way
279 of "xsetwacom" from the driver package at linuxwacom.sourceforge.net
280 This feature is totally independent of the connected Wacom tablet model."
281
282 Finding good numbers (they must be in groups of four) for this field is
283 not an intuitive act... The "wacomcpl" program - the tcl utility from
284 linuxwacom - uses a slider (stylus/eraser --> Feel --> Sensitivity)
285 with steps from 1 (Soft) to 7 (Firm) and 4 being the default. It then
286 calls the "xsetwacom" program to actually set a true "Bezier curve".
287
288 The seven curves chosen by wacomcpl are (Soft to Firm):
289
290 1               2               3               4 (default)
291 "0 75 25 100" | "0 50 50 100" | "0 25 75 100" | "0 0 100 100"
292 5               6               7
293 "25 0 100 75" | "50 0 100 50" | "75 0 100 25"
294
295 Experimenting with other values can probably be a fun... activity on a
296 rainy day. My thanks go to Pablo Gimenez, a user who wanted this
297 automatic pressure sensitivity change. He made me start thinking about
298 a possible implementation.
299
300 It works really well but, as I've written in the BUGS file:
301
302 --Quote--
303
304 _NOTABUG_
305
306 Any program built with the Qt3 toolkit (like eg the KDE desktop...)
307 completely swallows the 'stylus' DeviceButtonPress event that we've
308 registered to be notified of, through the Xlib XSelectExtensionEvent
309 call. The same event coming from the 'pad' device is all OK, though.
310
311 This is a (deliberate?) Qt pattern where only other Qt programs,
312 with difficulty, can get deliverance of these low-level events. At
313 least that's my impression after a first round of bug-report emails
314 between here and there --> Qt producer company Trolltech.
315
316 Why they let 'pad' button events pass through is probably due to lack
317 of knowledge. They recognize an oldtimer like the 'stylus', so BAM,
318 grab it. But this strange 'pad' thing... better stay out of contact...
319
320 Programs based on the GTK+ toolkit like the Gnome desktop (with the
321 notable exception being the Gimp canvas - more about that below) do
322 behave appropriate vis-a-vis both the 'stylus' and 'pad' button events.
323
324 This situation has led to one design compromise (performance slippage)
325 in expresskeys 0.3.0, and a not wholly ideal usability pattern when
326 dealing with Qt3 programs.
327
328 Performance wise we take a hit by also registering for and acting on
329 a 'stylus' ProximityIn event. These events are not blocked by Qt3.
330
331 Execution of the "automatic change of stylus pressure sensitivity"
332 in a Qt3 program is achieved by first lifting the pen slightly (until
333 it goes out of proximity - the cursor stops being effected by pen
334 movement) and then lowering the pen again on the target window.
335
336 If we happen to be in Gnome, it is enough to touch the Qt3 program on
337 the titlebar or on its other borders (since they are GTK+ derived).
338
339 GTK+ based programs suffer no such limitation. In those we just press
340 the pen tip in the window, and by that action the pressure sensitivity
341 change is performed. Unless the target is the Gimp canvas (at least as
342 high as version 2.2.10)...
343
344 The Gimp canvas is even _more_ broken (in regards to our expectations)
345 than the Qt3 programs. Here both the 'stylus' DeviceButtonPress AND
346 the ProximityIn events are filtered away from interested parties.
347
348 So in order to get the automatic change of stylus pressure sensitivity
349 when coming in from another program window, the pen tip or side button
350 rocker first must engage _somwhere else_ than the canvas. Just touching
351 the Gimp titlebar or touching an area outside of the canvas will work.
352
353 If we happen to be in KDE while using Gimp, then a simple titlebar
354 touch won't work (all the borders are Qt3 derived). Here we must do the
355 proximity out/in trick on a part not being the canvas, or touch
356 somewhere else than the window borders/Gimp canvas.
357
358 Phew. But there's a mitigating factor to all this Qt3/Gimp canvas
359 mess. We can use the "non-trigger" to our advantage.
360
361 For example, I normally like the PressCurve to be "0 25 75 100"
362 (sensitivity 3) in Gimp. But sometimes I'd like it to be a bit firmer.
363 So if the root window (the "background" in X) or some other window
364 nearby is set to sensitivity 4, it is a quick touch operation away to
365 either stay with a level 3, or switch to a level 4 while painting.
366
367 --Unquote--
368
369 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
370
371 The "default" entry holds keycodes to make the pad buttons behave just
372 as Wacom list them in the Quick Start Guide: Shift, Alt, Ctrl and Space
373 mirrored on both sides. Touch Strip support is turned on by default. Use
374 the number 0 in the "HandleTouchStrips" field to turn it off (a Graphire4
375 user changes the "HandleScrollWheel" field). You get "Mouse-scrolling"
376 Up/Down on the left strip and Arrow-key Right/Left on the right with the
377 values currently written to the minimal config file. Change direction of
378 the movement by switching the "Up" and "Down" values.
379
380 Both pad buttons and touch strips can send two keys at a time if so
381 configured through usage of the "...Plus" keycode fields.
382
383 If you want a button to do a mouse button press instead of a keypress,
384 use a value between 991 and 997 in the corresponding keycode field, where
385 991 represents mouse button 1, 992 button 2, and so on. Only existing mouse
386 buttons, defined through the driver of the active core pointer, can be
387 simulated. If buttons 4 and 5 are available they normally control vertical
388 scrolling, like the mouse's scroll wheel (button 4 scrolls up, button 5
389 scrolls down.) If buttons 6 and 7 are available they may control horizontal
390 scrolling (button 6 scrolls left, button 7 scrolls right) or may match
391 extra buttons on the mouse.
392
393 If you want a button to do pen mode toggling between Absolute and Relative,
394 use the value 999 in the corresponding keycode field. To be able to switch
395 mode anywhere each program block must contain one 999 definition.
396
397 OBS: The pen mode toggle can only be assigned to a "real" button,
398 not the "Plus" version :OBS.
399
400 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
401
402 The "Gimp" entry has the touch strips turned on by default, and I've
403 populated it with keycodes that I actually use myself. This was done to
404 minimize confusion about how to fill in the fields. As it stands, they
405 are (for my Swedish keyboard):
406
407 20 = "+" = Gimp Zoom In. Left touch strip up motion
408 61 = "-" = Gimp Zoom Out. Left touch strip down motion
409
410 64 = "Alt" plus 20 = "+" = Gimp Next Brush. Right touch strip up motion
411 64 = "Alt" plus 61 = "-" = Gimp Previous Brush. Right touch strip down motion
412
413 (The above has been configured through the Gimp menu: File -> Preferences ->
414 Interface -> Configure Keyboard Shortcuts -> Context)
415
416 50 = "Shift" = Button 9
417 64 = "Alt"   = Button 10 (Holding this, copies Right touch strip to Left!)
418 37 = "Ctrl"  = Button 11
419 65 = "Space" = Button 12
420
421 37 = "Ctrl" plus 29 = "y" = Gimp Redo. Button 13
422 37 = "Ctrl" plus 52 = "z" = Gimp Undo. Button 14
423 999 = "Pen Mode Toggle" = Button 15
424 65 = "Space" = Button 16
425
426 The "Blender" entry is similarly a private choice for the 3D program blender.
427
428 I felt, and feel, that an "XTerm" is too important a window to have _any_
429 interference from the pad. But observe that I want to be able to switch
430 pen mode even with such a window in focus, so I've set 999 in one field.
431
432 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
433
434 Below is some ASCII art showing the "default":
435
436 Left ExpressKey Pad
437 ------------
438 |  |   |   |            Wacom Intuos3 defaults are:
439 |  | 9 | T |
440 |11|---| O |            Key 9  = (left) Shift   = keycode 50
441 |  |10 | U |            Key 10 = (left) Alt     = keycode 64
442 |------| C |            Key 11 = (left) Control = keycode 37
443 |  12  | H |            Key 12 = Space          = keycode 65
444 ------------
445
446 Right ExpressKey Pad
447 ------------
448 |   |   |  |            Wacom Intuos3 defaults are:
449 | T |13 |  |
450 | O |---|15|            Key 13 = (left) Shift   = keycode 50
451 | U |14 |  |            Key 14 = (left) Alt     = keycode 64
452 | C |------|            Key 15 = (left) Control = keycode 37
453 | H |  16  |            Key 16 = Space          = keycode 65
454 ------------
455
456 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
457
458 Sometimes desktops or window managers "steal" certain
459 keypresses/combinations. If you experience that, look for
460 a way to change the keybindings of your environment.
461
462 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
463