517c88cbcf67a9006f82c837f3354ee1e86da073
[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 or Cintiq 21UX. 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 USAGE of expresskeys:
26
27 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
28
29 * Program can not be started unless X is running, and refuses to start
30 if another active instance of the program is detected (through a live
31 pid-file).
32
33 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
34
35 * Command line can be:
36
37 expresskeys <pad-device-name> [<pen-device-name>] [-d] [-v]
38
39 Where the pad name is mandatory. Specify a pen name
40 if you want the program to handle pen mode switches.
41 Use -d to make the program a daemon (run in the background).
42 Use -v to print info to the screen at many execution points.
43
44 Example: expresskeys pad stylus -d
45
46 The names are the "Identifier" strings in your X config file (xorg.conf)
47 Myself I start expresskeys just before the window manager in my 
48 .xinitrc with: /usr/local/bin/expresskeys pad stylus -d
49
50 OBS! I just found out that it should be started AFTER any usage of
51 the X program "xmodmap", else expresskeys could crash. Reason unknown.
52 See the BUGS file for further info.
53
54 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
55
56 * A minimal configuration file is written on first run to the user home
57 directory: ~/.expresskeys/expresskeys.conf
58
59 It contains "default", "Gimp", "Blender" and "XTerm" entries and is
60 recreated whenever a configuration file is missing on program start.
61
62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
63
64 * A file with the program PID number is written if run with -d in:
65 ~/.expresskeys/expresskeys.pid
66
67 The pid-file is deleted on normal program exit like "kill <pid>",
68 "killall expresskeys", "kill -TERM <pid>" etc. A brutal "kill -9 <pid>"
69 or a program crash will leave the pid-file undeleted. This is also
70 the case if the program is terminated by X close-down on some systems.
71
72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
73
74 * The configuration file is re-read upon receipt of the signal SIGUSR1.
75 Do a "kill -USR1 <pid-of-expresskeys>" after a config file edit (or -USR2).
76 The included shell script "expresskeys-reread.sh" will do it for you if
77 a pid-file from a daemon instance is present.
78
79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
80
81 * Use the X program "xev" to find keycodes when changing the configuration.
82
83 Since I've received a request for an explanation, I'll quote the reply:
84
85 --Begin Letter--
86
87 > I'm using your expresskeys for my intous3 but I'm
88 > a linux newbie and now I'm a bit confused, what is
89 > the right keycode or config for the arrow key.
90 >
91 > I want Space on 12
92 > Left arrow on 9
93 > Right arrow on 10
94
95 Keycodes are both confusing and simple, at the same time ;-) They are
96 different depending on your language and keyboard design, and also
97 different if you are in X or not, but share some common details.
98
99 To find how they are organized on your own keyboard, you must use a
100 program. First (if you are in X as you should be) open a terminal. The
101 only one I have per default is "xterm" since I don't use gnome or kde or
102 anything like that, where a terminal window can be called just
103 "terminal"... Other standalone terminals are "aterm", "rxvt", "eterm"
104 etc.
105
106 Now start a program from within the open terminal. One that _must_ be
107 present on your system (I think) is "xev". It comes as standard with X.
108 When you start xev it spawns another window (small white square) and
109 spits out a lot of info in the terminal window. You must move the mouse
110 pointer to the square window before doing any key presses.
111
112 Ok, now I'll press Space, Left Arrow and Right Arrow:
113
114 KeyPress event, serial 27, synthetic NO, window 0x1200001,
115     root 0x115, subw 0x0, time 5261195, (128,125), root:(138,145),
116     state 0x0, keycode 65 (keysym 0x20, space), same_screen YES,
117     XLookupString gives 1 bytes: (20) " "
118     XmbLookupString gives 1 bytes: (20) " "
119     XFilterEvent returns: False
120
121 The important information here is the "keycode 65 (keysym 0x20, space)".
122 There will be another information dump when you release the space key,
123 called KeyRelease.
124
125 So on my Swedish keyboard, X uses the keycode 65 to represent the
126 spacebar. Ok, here's Left Arrow:
127
128 KeyPress event, serial 27, synthetic NO, window 0x1200001,
129     root 0x115, subw 0x0, time 5281166, (128,125), root:(138,145),
130     state 0x0, keycode 100 (keysym 0xff51, Left), same_screen YES,
131     XLookupString gives 0 bytes: 
132     XmbLookupString gives 0 bytes: 
133     XFilterEvent returns: False
134
135 Keycode is 100 here. Let's go to Right Arrow:
136
137 KeyPress event, serial 27, synthetic NO, window 0x1200001,
138     root 0x115, subw 0x0, time 5283438, (128,125), root:(138,145),
139     state 0x0, keycode 102 (keysym 0xff53, Right), same_screen YES,
140     XLookupString gives 0 bytes: 
141     XmbLookupString gives 0 bytes: 
142     XFilterEvent returns: False
143
144 So it's 102. When you are finished looking for the keycodes, give the
145 terminal window focus (place the mouse cursor there or whatever) and
146 press Ctrl-c (you can also click on the close button of the white square
147 window).
148
149 That's how it looks on this Swedish keyboard. Now open the expresskeys
150 configuration file with any editor. The location is a hidden directory
151 in your home directory. Here's mine:
152
153 /home/loke/.expresskeys/expresskeys.conf
154
155 Replace the keycodes in the section you are interested in, I'd do:
156
157 10 Left Pad - Button 9:         100     # Button 9 Left Arrow
158 11 Left Pad - Button 9 Plus:    0       # Extra key
159
160 12 Left Pad - Button 10:        102     # Button 10 Right Arrow
161 13 Left Pad - Button 10 Plus:   0       # Extra key
162
163 14 Left Pad - Button 11:        37      # Button 11
164 15 Left Pad - Button 11 Plus:   0       # Extra key
165
166 16 Left Pad - Button 12:        65      # Button 12 Space (was default)
167 17 Left Pad - Button 12 Plus:   0       # Extra key
168
169 Save the file and read in the new values with the shell script I
170 supplied (expresskeys-reread.sh)
171
172 The extra key are for when you want two keys pressed. First the normal,
173 then the extra, like Ctrl-s or so. I've been informed that a US keyboard
174 doesn't have a single + key, it's shifted on their = key. So they must
175 use Shift-= in the expresskeys gimp section to zoom in, thereby wasting
176 the extra key. A workaround is to configure gimp itself to zoom by the =
177 key instead of +.
178
179 --End Letter--
180
181 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
182
183 * Use the X program "xprop" to find the name string to use when changing
184 the configuration. xprop without any arguments expects you to then click
185 on the target window. We are looking for the WM_CLASS info so running:
186
187 $ xprop | grep WM_CLASS
188 WM_CLASS(STRING) = "VCLSalFrame", "OpenOffice.org 1.1.4"
189
190 It's the last string we would use, the "OpenOffice.org 1.1.4". We always
191 use the last part, and the spelling is case sensitive. Putting
192 "openoffice.org 1.1.4" in the configuration file would not match up.
193
194 Also, since spaces are accepted as part of a class name, make sure there
195 are no space _before or after_ the name, within the double quotes:
196
197 "A ProgramName" <-- OK
198 " A ProgramName" or "A ProgramName " <-- NOT-OK
199
200 The extra space/s would become part of the class name. Not what you want.
201
202 The very first entry (at the top) in the configuration file is named
203 "default" and holds a key definition for all programs not specified
204 in another entry. It also takes care of the root window (the "background")
205 and programs lacking a class name in their WM_CLASS.
206
207 "default" must always stay as the first entry in the configuration file!
208
209 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
210
211 The "default" entry holds keycodes to make the pad buttons behave just
212 as Wacom list them in the Quick Start Guide: Shift, Alt, Ctrl and Space
213 mirrored on both sides. Touch Strip support is turned off by default. Use
214 the number 1 in the "Handle Touch Strips" field to turn it on. You then get
215 Arrow-key Up/Down on the left strip and Arrow-key Right/Left on the right.
216 Change direction of the movement by switching the "Up" and "Down" values.
217
218 Both pad buttons and touch strips can send two keys at a time if so
219 configured through usage of the "Plus" keycode fields.
220
221 If you want a button to do a mouse button press instead of a keypress,
222 use a value between 991 and 997 in the corresponding keycode field, where
223 991 represents mouse button 1, 992 button 2, and so on. Only existing mouse
224 buttons, defined through the driver of the active core pointer, can be
225 simulated. If buttons 4 and 5 are available they normally control vertical
226 scrolling, like the mouse's scroll wheel (button 4 scrolls up, button 5
227 scrolls down.) If buttons 6 and 7 are available they may control horizontal
228 scrolling (button 6 scrolls left, button 7 scrolls right) or may match
229 extra buttons on the mouse.
230
231 If you want a button to do pen mode toggling between Absolute and Relative,
232 use the value 999 in the corresponding keycode field. To be able to switch
233 mode anywhere each program block must contain one 999 definition. And,
234 of course, a pen name must be used on the command line when starting the
235 program. OBS: The pen mode toggle can only be assigned to a "real" button,
236 not the "Plus" version :OBS.
237
238 Please don't alter or remove the colons ":" before the class name or
239 keycodes. They must be there to separate the fields, just like the "%%" is
240 used to separate and define the program blocks.
241
242 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
243
244 The "Gimp" entry has the touch strips turned on by default, and I've
245 populated it with keycodes that I actually use myself. This was done to
246 minimize confusion about how to fill in the fields. As it stands, they
247 are (for my Swedish keyboard):
248
249 20 = "+" = Gimp Zoom In. Left touch strip up motion
250 61 = "-" = Gimp Zoom Out. Left touch strip down motion
251
252 64 = "Alt" plus 20 = "+" = Gimp Next Brush. Right touch strip up motion
253 64 = "Alt" plus 61 = "-" = Gimp Previous Brush. Right touch strip down motion
254
255 (The above has been configured through the Gimp menu: File -> Preferences ->
256 Interface -> Configure Keyboard Shortcuts -> Context)
257
258 50 = "Shift" = Button 9
259 64 = "Alt"   = Button 10 (Holding this, copies Right touch strip to Left!)
260 37 = "Ctrl"  = Button 11
261 65 = "Space" = Button 12
262
263 37 = "Ctrl" plus 29 = "y" = Gimp Redo. Button 13
264 37 = "Ctrl" plus 52 = "z" = Gimp Undo. Button 14
265 999 = "Pen Mode Toggle" = Button 15
266 65 = "Space" = Button 16
267
268 The "Blender" entry is similarly a private choice for the 3D program blender.
269
270 I felt, and feel, that an "XTerm" is too important a window to have _any_
271 interference from the pad. But observe that I want to be able to switch
272 pen mode even with such a window in focus, so I've set 999 in one field.
273
274 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
275
276 Below is some ASCII art showing the "default":
277
278 Left ExpressKey Pad
279 ------------ 
280 |  |   |   |            Wacom Intuos3 defaults are:
281 |  | 9 | T |
282 |11|---| O |            Key 9  = (left) Shift   = keycode 50
283 |  |10 | U |            Key 10 = (left) Alt     = keycode 64
284 |------| C |            Key 11 = (left) Control = keycode 37
285 |  12  | H |            Key 12 = Space          = keycode 65
286 ------------
287
288 Right ExpressKey Pad
289 ------------ 
290 |   |   |  |            Wacom Intuos3 defaults are:
291 | T |13 |  |
292 | O |---|15|            Key 13 = (left) Shift   = keycode 50
293 | U |14 |  |            Key 14 = (left) Alt     = keycode 64
294 | C |------|            Key 15 = (left) Control = keycode 37
295 | H |  16  |            Key 16 = Space          = keycode 65
296 ------------
297
298 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
299
300 Sometimes desktops or window managers "steal" certain
301 keypresses/combinations. If you experience that, look for
302 a way to change the keybindings of your environment.
303
304 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
305