version 0.3.0
[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: Gimp doesn't know _anything_ about a "pad" device, so the option
26 File --> Preferences --> Input Devices --> Configure Extended Input Devices...
27 --> [Device: pad  Mode: Disabled] is how it should be set. If you change it
28 to Sceen or Window, pressing pad buttons or using touch strips will NOT work.
29
30 ///////////////////////////////////////////////////////////////////////////
31
32 USAGE of expresskeys:
33
34 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
35
36 * Program can not be started unless X is running, and refuses to start
37 if a daemon instance of the program is detected (through a live pid-file).
38
39 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
40
41 * Command line:
42
43 Usage: expresskeys [OPTION]... [DEVICE]...
44 Any combination of pad and/or stylus can be specified.
45 An empty command line means automatic device search.
46 Options can be written like -dv or -d -v in any place.
47
48   -d makes the program a daemon (runs in the background).
49   -k terminates (kills) an already running daemon instance.
50   -r re-reads the configuration file of a running daemon.
51   -v prints info to the screen at many execution points.
52   -x sets -v and exits after some important info blocks.
53   -s tells a daemon instance to report status (info block).
54   -h unconditionally brings up this help text.
55
56 Example1: expresskeys -d (first 'pad' and/or 'stylus' found get used)
57 Example2: expresskeys 1stIntuos3Pad 1stIntuos3Stylus2 -d (named devices)
58 Example3: expresskeys -rv (visibly re-read the configuration file)
59
60 The names of pad or stylus devices are the "Identifier" strings in your
61 X config file (xorg.conf). Myself I start expresskeys just before the
62 window manager in .xinitrc with: /usr/local/bin/expresskeys -d
63
64 OBS! I've found out that it should be started AFTER any usage of
65 the X program "xmodmap", else expresskeys could crash. Reason unknown.
66 See the BUGS file for further info.
67
68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
69
70 * A minimal configuration file is written on first run to the user home
71 directory: ~/.expresskeys/intuos3.conf1 (or padless.conf1)
72
73 It contains "default", "Gimp", "Blender" and "XTerm" entries and is
74 re-created whenever a configuration file is missing on program start.
75
76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
77
78 * A file with the program PID number is written if run with -d in:
79 ~/.expresskeys/expresskeys.pid
80
81 The pid-file is deleted on normal program exit like "expresskeys -k"
82
83 You can also type "kill <pid>", "killall expresskeys", "kill -TERM <pid>"
84 etc. A brutal "kill -9 <pid>" or a program crash will leave the pid-file
85 undeleted. This is also the case if the program is terminated by X
86 close-down on some systems.
87
88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
89
90 * The configuration file is re-read when you do an "expresskeys -r" and a
91 daemon instance of the program is running.
92
93 What happens then is that we send the SIGUSR1 signal, which has been
94 defined to call the re_read_file_config function in on_signal.c The
95 action can also be performed by doing a "kill -USR1 <pid-of-expresskeys>"
96 after a config file edit.
97
98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
99
100 NOTE: There's a graphical point-and-click program in the offing at:
101 http://alavaliant.googlepages.com that already supports expresskeys 0.2.x
102 config file editing. The pygtk (2.8+) program is called "wacom-config"
103 and will be updated to support expresskeys 0.3.x. It really does obsolete
104 the following explanations of how to find keycodes and program names :NOTE
105
106 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
107
108 * Use the X program "xev" to find keycodes when changing the configuration.
109
110 Since I've received a request for an explanation, I'll quote the reply:
111
112 --Begin Letter--
113
114 > I'm using your expresskeys for my intous3 but I'm
115 > a linux newbie and now I'm a bit confused, what is
116 > the right keycode or config for the arrow key.
117 >
118 > I want Space on 12
119 > Left arrow on 9
120 > Right arrow on 10
121
122 Keycodes are both confusing and simple, at the same time ;-) They are
123 different depending on your language and keyboard design, and also
124 different if you are in X or not, but share some common details.
125
126 To find how they are organized on your own keyboard, you must use a
127 program. First (if you are in X as you should be) open a terminal. The
128 only one I have per default is "xterm" since I don't use gnome or kde or
129 anything like that, where a terminal window can be called just
130 "terminal"... Other standalone terminals are "aterm", "rxvt", "eterm"
131 etc.
132
133 Now start a program from within the open terminal. One that _must_ be
134 present on your system (I think) is "xev". It comes as standard with X.
135 When you start xev it spawns another window (small white square) and
136 spits out a lot of info in the terminal window. You must move the mouse
137 pointer to the square window before doing any key presses.
138
139 Ok, now I'll press Space, Left Arrow and Right Arrow:
140
141 KeyPress event, serial 27, synthetic NO, window 0x1200001,
142     root 0x115, subw 0x0, time 5261195, (128,125), root:(138,145),
143     state 0x0, keycode 65 (keysym 0x20, space), same_screen YES,
144     XLookupString gives 1 bytes: (20) " "
145     XmbLookupString gives 1 bytes: (20) " "
146     XFilterEvent returns: False
147
148 The important information here is the "keycode 65 (keysym 0x20, space)".
149 There will be another information dump when you release the space key,
150 called KeyRelease.
151
152 So on my Swedish keyboard, X uses the keycode 65 to represent the
153 spacebar. Ok, here's Left Arrow:
154
155 KeyPress event, serial 27, synthetic NO, window 0x1200001,
156     root 0x115, subw 0x0, time 5281166, (128,125), root:(138,145),
157     state 0x0, keycode 100 (keysym 0xff51, Left), same_screen YES,
158     XLookupString gives 0 bytes:
159     XmbLookupString gives 0 bytes:
160     XFilterEvent returns: False
161
162 Keycode is 100 here. Let's go to Right Arrow:
163
164 KeyPress event, serial 27, synthetic NO, window 0x1200001,
165     root 0x115, subw 0x0, time 5283438, (128,125), root:(138,145),
166     state 0x0, keycode 102 (keysym 0xff53, Right), same_screen YES,
167     XLookupString gives 0 bytes:
168     XmbLookupString gives 0 bytes:
169     XFilterEvent returns: False
170
171 So it's 102. When you are finished looking for the keycodes, give the
172 terminal window focus (place the mouse cursor there or whatever) and
173 press Ctrl-c (you can also click on the close button of the white square
174 window).
175
176 That's how it looks on this Swedish keyboard. Now open the expresskeys
177 configuration file with any editor. The location is a hidden directory
178 in your home directory. Here's mine:
179
180 /home/loke/.expresskeys/intuos3.conf1
181
182 Replace the keycodes in the section you are interested in, I'd do:
183 [Original configfile version 2 text here updated to version 3. Ed.]
184
185 LeftPadButton9        100     # Button 9 Left Arrow
186 LeftPadButton9Plus    0       # Extra keycode
187
188 LeftPadButton10       102     # Button 10 Right Arrow
189 LeftPadButton10Plus   0       # Extra keycode
190
191 LeftPadButton11       37      # Button 11
192 LeftPadButton11Plus   0       # Extra keycode
193
194 LeftPadButton12       65      # Button 12 Space (was default)
195 LeftPadButton12Plus   0       # Extra keycode
196
197 Save the file and read in the new values with "expresskeys -r"
198
199 The extra key are for when you want two keys pressed. First the normal,
200 then the extra, like Ctrl-s or so. I've been informed that a US keyboard
201 doesn't have a single + key, it's shifted on their = key. So they must
202 use Shift-= in the expresskeys gimp section to zoom in, thereby wasting
203 the extra key. A workaround is to configure gimp itself to zoom by the =
204 key instead of +.
205
206 --End Letter--
207
208 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
209
210 * Use the X program "xprop" to find the name string to use when changing
211 the configuration. xprop without any arguments expects you to then click
212 on the target window. We are looking for the WM_CLASS info so running:
213
214 $ xprop | grep WM_CLASS
215 WM_CLASS(STRING) = "VCLSalFrame", "OpenOffice.org 1.1.4"
216
217 It's the last string we would use, the "OpenOffice.org 1.1.4". We always
218 use the last part, and the spelling is case sensitive. Putting
219 "openoffice.org 1.1.4" in the configuration file would not match up.
220
221 A cleaner looking output from xprop can be had by eg running:
222
223 $ xprop | grep WM_CLASS | cut -d ',' -f2
224  "OpenOffice.org 1.1.4"
225
226 Also, since spaces are accepted as part of a class name, make sure there
227 are no space _before or after_ the name, within the double quotes:
228
229 "A ProgramName" <-- OK
230 " A ProgramName" or "A ProgramName " <-- NOT-OK
231
232 The extra space/s would become part of the class name. Not what you want.
233
234 The very first entry (at the top) in the configuration file is named
235 "default" and holds a key definition for all programs not specified
236 in another entry. It also takes care of the root window (the "background")
237 and programs lacking a class name in their WM_CLASS.
238
239 The "default" record must always exist in the configuration file! But it
240 doesn't matter _where_. Put it last or first or wherever...
241
242 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
243
244 NEW in expresskeys version 0.3.0:
245
246 Config file version 3 is completely independent of how you organize the
247 program fields or records. Only limitation is that all the fields must
248 be _present_ somewhere in the record for it to be counted. In version 3
249 that means 27 fields for a 'pad' device user ('stylus' field is included),
250 and 2 fields for a 'stylus' device only user.
251
252 This open-ended nature was enforced to facilitate the inclusion of
253 future fields - or elimination of already existing ones - without
254 invalidating what the user already has (which happens now when going
255 from version 2 to 3).
256
257 The new field introduced with version 3 is Stylus1PressCurve. Here's
258 what I've written in the README file:
259
260 "It can also provide an automatic change of stylus pressure sensitivity
261 - aka PressCurve - going from one program window to the next, by way
262 of "xsetwacom" from the driver package at linuxwacom.sourceforge.net
263 This feature is totally independent of the connected Wacom tablet model."
264
265 Finding good numbers (they must be in groups of four) for this field is
266 not an intuitive act... The "wacomcpl" program - the tcl utility from
267 linuxwacom - uses a slider (stylus/eraser --> Feel --> Sensitivity)
268 with steps from 1 (Soft) to 7 (Firm) and 4 being the default. It then
269 calls the "xsetwacom" program to actually set a true "Bezier curve".
270
271 The seven curves chosen by wacomcpl are (Soft to Firm):
272
273 1               2               3               4 (default)
274 "0 75 25 100" | "0 50 50 100" | "0 25 75 100" | "0 0 100 100"
275 5               6               7
276 "25 0 100 75" | "50 0 100 50" | "75 0 100 25"
277
278 Experimenting with other values can probably be a fun... activity on a
279 rainy day. My thanks go to Pablo Gimenez, a user who wanted this
280 automatic pressure sensitivity change. He made me start thinking about
281 a possible implementation.
282
283 It works really well but, as I've written in the BUGS file:
284
285 --Quote--
286
287 _NOTABUG_
288
289 Any program built with the Qt3 toolkit (like eg the KDE desktop...)
290 completely swallows the 'stylus' DeviceButtonPress event that we've
291 registered to be notified of, through the Xlib XSelectExtensionEvent
292 call. The same event coming from the 'pad' device is all OK, though.
293
294 This is a (deliberate?) Qt pattern where only other Qt programs,
295 with difficulty, can get deliverance of these low-level events. At
296 least that's my impression after a first round of bug-report emails
297 between here and there --> Qt producer company Trolltech.
298
299 Why they let 'pad' button events pass through is probably due to lack
300 of knowledge. They recognize an oldtimer like the 'stylus', so BAM,
301 grab it. But this strange 'pad' thing... better stay out of contact...
302
303 Programs based on the GTK+ toolkit like the Gnome desktop (with the
304 notable exception being the Gimp canvas - more about that below) do
305 behave appropriate vis-a-vis both the 'stylus' and 'pad' button events.
306
307 This situation has led to one design compromise (performance slippage)
308 in expresskeys 0.3.0, and a not wholly ideal usability pattern when
309 dealing with Qt3 programs.
310
311 Performance wise we take a hit by also registering for and acting on
312 a 'stylus' ProximityIn event. These events are not blocked by Qt3.
313
314 Execution of the "automatic change of stylus pressure sensitivity"
315 in a Qt3 program is achieved by first lifting the pen slightly (until
316 it goes out of proximity - the cursor stops being effected by pen
317 movement) and then lowering the pen again on the target window.
318
319 If we happen to be in Gnome, it is enough to touch the Qt3 program on
320 the titlebar or on its other borders (since they are GTK+ derived).
321
322 GTK+ based programs suffer no such limitation. In those we just press
323 the pen tip in the window, and by that action the pressure sensitivity
324 change is performed. Unless the target is the Gimp canvas (at least as
325 high as version 2.2.10)...
326
327 The Gimp canvas is even _more_ broken (in regards to our expectations)
328 than the Qt3 programs. Here both the 'stylus' DeviceButtonPress AND
329 the ProximityIn events are filtered away from interested parties.
330
331 So in order to get the automatic change of stylus pressure sensitivity
332 when coming in from another program window, the pen tip or side button
333 rocker first must engage _somwhere else_ than the canvas. Just touching
334 the Gimp titlebar or touching an area outside of the canvas will work.
335
336 If we happen to be in KDE while using Gimp, then a simple titlebar
337 touch won't work (all the borders are Qt3 derived). Here we must do the
338 proximity out/in trick on a part not being the canvas, or touch
339 somewhere else than the window borders/Gimp canvas.
340
341 Phew. But there's a mitigating factor to all this Qt3/Gimp canvas
342 mess. We can use the "non-trigger" to our advantage.
343
344 For example, I normally like the PressCurve to be "0 25 75 100"
345 (sensitivity 3) in Gimp. But sometimes I'd like it to be a bit firmer.
346 So if the root window (the "background" in X) or some other window
347 nearby is set to sensitivity 4, it is a quick touch operation away to
348 either stay with a level 3, or switch to a level 4 while painting.
349
350 --Unquote--
351
352 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
353
354 The "default" entry holds keycodes to make the pad buttons behave just
355 as Wacom list them in the Quick Start Guide: Shift, Alt, Ctrl and Space
356 mirrored on both sides. Touch Strip support is turned off by default. Use
357 the number 1 in the "HandleTouchStrips" field to turn it on. You then get
358 Arrow-key Up/Down on the left strip and Arrow-key Right/Left on the right.
359 Change direction of the movement by switching the "Up" and "Down" values.
360
361 Both pad buttons and touch strips can send two keys at a time if so
362 configured through usage of the "...Plus" keycode fields.
363
364 If you want a button to do a mouse button press instead of a keypress,
365 use a value between 991 and 997 in the corresponding keycode field, where
366 991 represents mouse button 1, 992 button 2, and so on. Only existing mouse
367 buttons, defined through the driver of the active core pointer, can be
368 simulated. If buttons 4 and 5 are available they normally control vertical
369 scrolling, like the mouse's scroll wheel (button 4 scrolls up, button 5
370 scrolls down.) If buttons 6 and 7 are available they may control horizontal
371 scrolling (button 6 scrolls left, button 7 scrolls right) or may match
372 extra buttons on the mouse.
373
374 If you want a button to do pen mode toggling between Absolute and Relative,
375 use the value 999 in the corresponding keycode field. To be able to switch
376 mode anywhere each program block must contain one 999 definition.
377
378 OBS: The pen mode toggle can only be assigned to a "real" button,
379 not the "Plus" version :OBS.
380
381 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
382
383 The "Gimp" entry has the touch strips turned on by default, and I've
384 populated it with keycodes that I actually use myself. This was done to
385 minimize confusion about how to fill in the fields. As it stands, they
386 are (for my Swedish keyboard):
387
388 20 = "+" = Gimp Zoom In. Left touch strip up motion
389 61 = "-" = Gimp Zoom Out. Left touch strip down motion
390
391 64 = "Alt" plus 20 = "+" = Gimp Next Brush. Right touch strip up motion
392 64 = "Alt" plus 61 = "-" = Gimp Previous Brush. Right touch strip down motion
393
394 (The above has been configured through the Gimp menu: File -> Preferences ->
395 Interface -> Configure Keyboard Shortcuts -> Context)
396
397 50 = "Shift" = Button 9
398 64 = "Alt"   = Button 10 (Holding this, copies Right touch strip to Left!)
399 37 = "Ctrl"  = Button 11
400 65 = "Space" = Button 12
401
402 37 = "Ctrl" plus 29 = "y" = Gimp Redo. Button 13
403 37 = "Ctrl" plus 52 = "z" = Gimp Undo. Button 14
404 999 = "Pen Mode Toggle" = Button 15
405 65 = "Space" = Button 16
406
407 The "Blender" entry is similarly a private choice for the 3D program blender.
408
409 I felt, and feel, that an "XTerm" is too important a window to have _any_
410 interference from the pad. But observe that I want to be able to switch
411 pen mode even with such a window in focus, so I've set 999 in one field.
412
413 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
414
415 Below is some ASCII art showing the "default":
416
417 Left ExpressKey Pad
418 ------------
419 |  |   |   |            Wacom Intuos3 defaults are:
420 |  | 9 | T |
421 |11|---| O |            Key 9  = (left) Shift   = keycode 50
422 |  |10 | U |            Key 10 = (left) Alt     = keycode 64
423 |------| C |            Key 11 = (left) Control = keycode 37
424 |  12  | H |            Key 12 = Space          = keycode 65
425 ------------
426
427 Right ExpressKey Pad
428 ------------
429 |   |   |  |            Wacom Intuos3 defaults are:
430 | T |13 |  |
431 | O |---|15|            Key 13 = (left) Shift   = keycode 50
432 | U |14 |  |            Key 14 = (left) Alt     = keycode 64
433 | C |------|            Key 15 = (left) Control = keycode 37
434 | H |  16  |            Key 16 = Space          = keycode 65
435 ------------
436
437 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
438
439 Sometimes desktops or window managers "steal" certain
440 keypresses/combinations. If you experience that, look for
441 a way to change the keybindings of your environment.
442
443 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
444