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