1XKeyCaps(1) General Commands Manual XKeyCaps(1)
2
6 xkeycaps - graphically display and edit the X keyboard mapping
7
9 xkeycaps [-toolkitoption ...] [-option ...]
10
12 The xkeycaps program displays a keyboard. Moving the mouse over a key
13 describes the keysyms and modifiers that that key generates. Clicking
14 left on a key simulates a KeyPress event. Clicking right on a key
15 brings up a menu of operations, including a command to change the
16 keysyms that the key generates. This program is, in part, a graphical
17 front-end to xmodmap(1).
18
20 xkeycaps accepts all of the standard toolkit options, and also accepts
21 the following options:
22 -keyboard keyboard-name or -kbd keyboard-name
24 Specifies the type of keyboard to display. There are many differ‐
25 ent computer keyboards in the world, and xkeycaps must know which
26 one you are using in order to function correctly. Case does not
27 matter when specifying a keyboard name.
28 If you're running on the console display of a Sun or HP, then xkey‐
30 caps will interrogate the attached keyboard hardware directly to
31 determine what keyboard you're using. But if you're running
32 remotely, or on another type of machine, then you must specify a
33 keyboard somehow.
34 -help
36 Lists the recognized values for the -keyboard option.
37 -gutterwidth number or -gw number
39 Specifies the number of pixels of space to leave between each key.
40 -font fontname
42 Specifies the font to use to display the keycaps.
43 The following standard X Toolkit command line arguments are commonly
46 used with xkeycaps:
47 -display host:dpy
49 This option specifies the X server to contact.
50 -geometry geometry
52 This option specifies the preferred size and position of the win‐
53 dow.
54 -bg color
56 This option specifies the color to use for the background of the
57 window. The default is light gray.
58 -fg color
60 This option specifies the color to use for the foreground of the
61 window. The default is black.
62 -bw number
64 This option specifies the width in pixels of the border surrounding
65 the window.
66 -xrm resourcestring
68 This option specifies a resource string to be used. This is espe‐
69 cially useful for setting resources that do not have separate com‐
70 mand line options.
71
73 The bottom part of the window is a drawing of a keyboard. In the top
74 left of each key is printed the string which actually appears on the
75 surface of the key. In the bottom right of the key is the (hexadeci‐
76 mal) keycode that this key generates.
77 At the top of the screen are several lines of text describing the key
79 under the mouse (or the most recently typed key.) These lines are:
80 KeyCode: This displays the text printed on the physical key, and the
82 keycode generated by that key in hex, decimal, and octal.
83 KeySym: This displays the set of KeySyms that this key currently
85 generates.
86 ASCII: This displays the ASCII equivalent of this key, taking into
88 account the current modifier keys which are down.
89 Modifiers: this displays the modifier bits which this key generates.
91 If a key generates modifiers, it is a chord-key like Shift
92 or Control.
93 AutoRepeat: Whether the X server claims that this key autorepeats. I
95 say ``claims'' because the OpenWindows X server is the only
96 one I have encountered for which this information is accu‐
97 rate. The per-key autorepeat flag seems to be almost-uni‐
98 versally ignored.
99
101 There are several buttons in the upper left corner of the window. They
102 are:
103 Quit
105 Exits the program.
106 Select Keyboard
108 Pops up a dialog box from which you can change which keyboard is
109 displayed. The left column lists the known types of keyboards, and
110 the right column lists the known layouts (mappings) of those key‐
111 boards.
112 Type At Window
114 After selecting this, you are asked to click on some other window.
115 After doing this, clicking on keys on the keyboard display will
116 simulate key events on the window you selected. Selecting the root
117 window or the xkeycaps window turns this off.
118 If you are using a window manager (for example, twm(1)) in which
120 you can lock the keyboard focus on a window and still click on
121 other windows without having the focus change, then you can accom‐
122 plish the same thing merely by focusing on another window and
123 clicking on the keys in the xkeycaps window.
124 Restore Default Map
126 This command restores the keyboard to its default state. If you
127 execute this command while displaying a keyboard which is not the
128 type of keyboard you are really using, your keymap will be in a
129 nonsensical state. There is no way for xkeycaps to tell what key‐
130 board you are using except by taking your word for it, so don't
131 lie.
132 Write Output
134 This command writes an xmodmap input file representing the current
135 state of the keyboard (including all of your changes) to a file in
136 your home directory.
137 The file will be called .xmodmap-hostname, where hostname is the
139 name of the machine you're running on. It will warn you if the
140 file already exists.
141 It prompts you with a dialog box: you can either write an xmodmap
143 file representing the state of every key, or you can write a
144 smaller file which describes only the changes.
145 The idea is that in the appropriate startup script, you would add a
147 line like
148 xmodmap /.xmodmap-`uname -n`
149 in the appropriate init file, so that those keyboard modifications
150 are made each time you log in. (If you're not sure where this com‐
151 mand should go, ask your system administrator, as that tends to
152 vary from site to site.)
153 Clicking left on a key simulates a KeyPress event. Releasing the but‐
155 ton simulates a KeyRelease event. If you click left on a key and move
156 the mouse while the button is down, KeyPress and KeyRelease events will
157 be simulated on every key you move the mouse over. Think of the mouse
158 as your finger: if you drag the mouse over several keys, they will go
159 down and up in turn.
160 Clicking left on a key which is associated with modifier bits (such as
162 Shift or Control) causes that key to ``lock'' down. Clicking left
163 again releases the key. In this way, you can generate key-chords with
164 the mouse: to generate Control-C, click left on the Control key, and
165 then click on the C key. Click on Control again to turn the control
166 modifier off.
167 Typing a key on the real keyboard simulates a KeyPress/KeyRelease event
169 pair in the same way that clicking on a key does.
170 You can also combine mouse and keyboard input: for example, if you use
172 the mouse to select the Shift key, and type a character, the event that
173 is simulated will have the Shift modifier set. And if you hold down
174 the real Control key, and click on the C key in the window, a Control-C
175 event will be generated. (Assuming, that is, that your window manager
176 does not intercept control-left-button for its own purposes.)
177 Clicking right on a key pops up a menu of commands for the given key.
179 They are:
180 Exchange Keys
182 After selecting this menu item, you are asked to click on another
183 key. That key and the key on which you brought up the menu will be
184 exchanged. This changes the keyboard mapping immediately.
185 Duplicate Key
187 After selecting this menu item, you are asked to click on another
188 key. That key will be made a copy of the key on which you brought
189 up the menu. That is, the two keys will generate the same set of
190 keysyms and modifiers. This changes the keyboard mapping immedi‐
191 ately.
192 Disable Key
194 The key on which you brought up the menu will be made to generate
195 no keysyms and no modifiers. This changes the keyboard mapping
196 immediately.
197 Restore Key To Default
199 The key on which you brought up the menu will be restored to its
200 default state; no other key will be altered. This actually changes
201 the current keyboard mapping.
202 Edit KeySyms of Key
204 This pops up the "Edit Key" window, which allows you to arbitrarily
205 change which keysyms and modifiers this key generates.
206 On the left side of the window is the list of the keysyms that this
208 key currently generates. (A key may generate up to eight keysyms;
209 the interpretation of these keysyms is described in the X protocol
210 document, and is summarized later in the KEYSYMS AND KEYCODES sec‐
211 tion of this man page.)
212 The second column is a multiple-choice list of the eight modifier
214 bits that this key may generate. For example, if you want a key to
215 behave as a ``control'' key, you should select the Control modi‐
216 fier.
217 The third and fourth column (the scrolling lists) are for changing
219 the keysym associated with the key. When you select a keysym-posi‐
220 tion from the first column, the character set and keysym will be
221 displayed in the scrolling lists. Clicking on a keysym in the
222 ``KeySym'' column will install that keysym in the highlighted slot
223 in the first column.
224 To select a keysym from a different character set, click on the
226 character set name in the second column. (The Latin1 and Keyboard
227 character sets are the most commonly used.)
228 At the bottom of the window are three buttons: Undo, Abort, and Ok.
230 Clicking on Undo reverts the Edit Key window to the current state
231 of the key in question. Abort closes the Edit Key window without
232 making any changes. Ok closes the Edit Key window and installs
233 your changes (the current keyboard mapping is modified.)
234
236 To effectively edit your keyboard mapping, there are some terms you
237 need to be familiar with:
238 KeyCode This is a raw scan-code that is read from the keyboard; each
240 physical key on the keyboard has a different number associ‐
241 ated with it; this mapping cannot be changed (but that's ok.)
242 Generally, every keyboard has its own set of KeyCodes, which
244 is why you will probably need to have a different keymap for
245 every system you use.
246 KeySym This is a symbol which can be generated by a single press of
248 one key on the keyboard: for example, all letters, numbers,
249 and punctuation are keysyms, and so are more abstract things
250 like ``shift'' and ``control''.
251 Each KeyCode (that is, key on the keyboard) is associated
253 with certain KeySyms. The KeySyms are what give the keys
254 their semantics (and makes the A key generate an A), not the
255 KeyCodes.
256 Usually keys are associated with one or two keysyms, which
258 correspond to the symbols generated when the key is pressed,
259 and when it is pressed while the shift key is held down.
260 There is a special case, which is that if the key contains
261 only one KeySym, and it is a letter, then the Shift key does
262 the obvious thing that one does to letters.
263 KeyCap Not to be confused with KeySyms, this refers to the text
265 which is printed on the physical keys: it is immutable
266 (unless you repaint your keyboard...)
267 Chord This term refers to a set of two or more keys held down
269 simultaniously (by analogy with piano keyboards.) All but
270 one of the keys will generally be Modifier Keys. Sometimes
271 Constellation is used to mean the same thing.
272 Modifier Key
274 This is a key like shift or control, which is used to alter
275 the interpretation of other keys which are held down at the
276 same time. Generally, pressing a modifier key without also
277 pressing a non-modifier key does nothing.
278 A key is a modifier key if it has a Modifier KeySym on it.
280 (More specifically, if the KeyCode of that key is associated
281 with a Modifier KeySym.)
282 Modifier KeySym
284 A KeySym is a modifier keysym if it has a Modifier Bit asso‐
285 ciated with it. But, the rules are a little more complicated
286 than that. It's easier to describe by example:
287 For a key to behave as one expects a shift key to behave, the
289 keycode should have the Shift modifier bit set; and the key
290 should generate one of the keysyms Shift_L and Shift_R. If
291 either of these is not true, the key will not behave as a
292 shift key.
293 Analogously, a control key must have the Control modifier
295 set, and use one of the keysyms Control_L or Control_R.
296 This implies that if you wanted to swap your shift and con‐
298 trol keys, it would not be enough to simply swap their modi‐
299 fier bits: you must swap their keysyms as well. If you only
300 swap the modifier bits, it might appear to work at first, but
301 other things would malfunction.
302 Keys like Meta (and Super, Hyper, etc.) are a bit more com‐
304 plicated (see below.)
305 Modifier Bit
307 Modifier bits are attributes which certain keysyms can have.
308 Some modifier bits have predefined semantics: Shift, Lock,
309 and Control. The remaining modifier bits (Mod1 through Mod5)
310 have semantics which are defined by the keys with which they
311 are associated.
312 That is, the Control modifier means Control if it is attached
314 to Control_L or Control_R, and is illegal elsewhere.
315 But Mod1 means Meta if it is attached to Meta_L or Meta_R;
317 but it would mean Alt if it were attached to Alt_L or Alt_R;
318 or Hyper with Hyper_L or Hyper_R; and so on. (It could not,
319 however, be attached to Control_L, since the Control modifier
320 has already spoken for those keysyms.)
321 If you're thinking that this is all senselessly compli‐
323 cated... you're right.
324
326 The following is a more precise technical explanation of how keymapping
327 works. This description is from the X Protocol document, and is
328 reprinted here for your convenience:
329 A list of KeySyms is associated with each KeyCode. If that list
331 (ignoring trailing NoSymbol entries) is a single KeySym ``K'', then
332 the list is treated as if it were the list ``K NoSymbol K NoSym‐
333 bol''. If the list (ignoring trailing NoSymbol entries) is a pair
334 of KeySyms ``K1 K2'', then the list is treated as if it were the
335 list ``K1 K2 K1 K2''. If the list (ignoring trailing NoSymbol
336 entries) is a triple of KeySyms ``K1 K2 K3'', then the list is
337 treated as if it were the list ``K1 K2 K3 NoSymbol''.
338 The first four elements of the list are split into two groups of
340 KeySyms. Group 1 contains the first and second KeySyms, Group 2
341 contains third and fourth KeySyms. Within each group, if the sec‐
342 ond element of the group is NoSymbol, then the group should be
343 treated as if the second element were the same as the first ele‐
344 ment, except when the first element is an alphabetic KeySym ``K''
345 for which both lowercase and uppercase forms are defined. In that
346 case, the group should be treated as if the first element were the
347 lowercase form of ``K'' and the second element were the uppercase
348 form of ``K''.
349 The standard rules for obtaining a KeySym from a KeyPress event
351 make use of only the Group 1 and Group 2 KeySyms; no interpretation
352 of other KeySyms in the list is given here. (That is, the last
353 four KeySyms are unused.)
354 Which group to use is determined by modifier state. Switching
356 between groups is controlled by the KeySym named Mode_switch.
357 By attaching that KeySym to some KeyCode and attaching that KeyCode
359 to any one of the modifiers Mod1 through Mod5. This modifier is
360 called the ``group modifier''. For any KeyCode, Group 1 is used
361 when the group modifier is off, and Group 2 is used when the group
362 modifier is on.
363 Within a group, which KeySym to use is also determined by modifier
365 state. The first KeySym is used when the Shift and Lock modifiers
366 are off. The second KeySym is used when the Shift modifier is on,
367 or when the Lock modifier is on and the second KeySym is uppercase
368 alphabetic, or when the Lock modifier is on and is interpreted as
369 ShiftLock. Otherwise, when the Lock modifier is on and is inter‐
370 preted as CapsLock, the state of the Shift modifier is applied
371 first to select a KeySym, but if that KeySym is lowercase alpha‐
372 betic, then the corresponding uppercase KeySym is used instead.
373
375 The following is a more precise technical explanation of how modifier
376 keys are interpreted. This description is from the Inter-Client Commu‐
377 nications Conventions Manual, and is reprinted here for your conve‐
378 nience:
379 X11 supports 8 modifier bits, of which 3 are pre-assigned to
381 Shift, Lock and Control. Each modifier bit is controlled by the
382 state of a set of keys, and these sets are specified in a table
383 accessed by GetModifierMapping() and SetModifierMapping().
384 A client needing to use one of the pre-assigned modifiers should
386 assume that the modifier table has been set up correctly to control
387 these modifiers. The Lock modifier should be interpreted as Caps
388 Lock or Shift Lock according as the keycodes in its controlling set
389 include XK_Caps_Lock or XK_Shift_Lock.
390 Clients should determine the meaning of a modifier bit from the
392 keysyms being used to control it.
393 A client needing to use an extra modifier, for example Meta,
395 should:
396 Scan the existing modifier mappings. If it finds a modifier that
398 contains a keycode whose set of keysyms includes XK_Meta_L or
399 XK_Meta_R, it should use that modifier bit.
400 If there is no existing modifier controlled by XK_Meta_L or
402 XK_Meta_R, it should select an unused modifier bit (one with an
403 empty controlling set) and:
404 If there is a keycode with XL_Meta_L in its set of keysyms, add
406 that keycode to the set for the chosen modifier, then
407 if there is a keycode with XL_Meta_R in its set of keysyms, add
409 that keycode to the set for the chosen modifier, then
410 if the controlling set is still empty, interact with the user
412 to select one or more keys to be Meta.
413 If there are no unused modifier bits, ask the user to take cor‐
415 rective action.
416 The above means that the Mod1 modifier does not necessarily mean Meta,
418 although some applications (such as twm and emacs 18) assume that. Any
419 of the five unassigned modifier bits could mean Meta; what matters is
420 that a modifier bit is generated by a keycode which is bound to the
421 keysym Meta_L or Meta_R.
422 Therefore, if you want to make a ``meta'' key, the right way is to make
424 the keycode in question generate both a Meta keysym, and some previ‐
425 ously-unassigned modifier bit.
426
428 In case the above didn't make sense, what the Mode_switch keysym does
429 is, basically, act as an additional kind of shift key. If you have
430 four keysyms attached to the A key, then those four keysyms will be
431 accessed by the chords: A; Shift-A, Mode_Switch-A; and Mode_Switch-
432 Shift-A, respectively.
433 Like any Modifier Key, for Mode_switch to function, it must have a mod‐
435 ifier bit attached to it. So, select one of the bits Mod1 through Mod5
436 (whichever is unused) and attach that to the Mode_switch key.
437
439 Not to be confused with Mode_switch, Multi_key allows the input of mul‐
440 tiple character sequences that represent a single character (keysym.)
441 A more traditional name for this keysym might have been Compose.
442 The Multi_key keysym is not a modifier keysym. That is, for it to
444 function properly, it should not have any modifier bits associated with
445 it. This is because it is not a ``chording'' key: you do not hold it
446 down along with other keys. Rather, you press Multi_key, then release
447 it, then press and release another key, and the two together yield a
448 new character.
449 For example, one traditional binding would be for Multi_key, followed
451 by single-quote, followed by A to produce the Aacute keysym.
452 Not all vendors support the use of the Multi_key keysym; in particular,
454 Digital, Sun, and HP support it, but the X Consortium does not. (The
455 reason for this, I am told, is that ``Compose'' sequences are consid‐
456 ered obsolete; the party line is that you should be using Input Methods
457 to do this.)
458 Whether Multi_key works is a property of the Xt library (not the X
460 server) so it's possible that on a single system, Multi_key might work
461 with some applications and not others (depending on how those applica‐
462 tions were compiled and linked.)
463 If you use Lucid Emacs or XEmacs, then you can take advantage of
465 Multi_key sequences even if your version of Xt doesn't support it, by
466 loading the x-compose library, which simulates the traditional Xt
467 behavior. For more info, read the commentary at the top of the file
468 "/usr/local/lib/xemacs-*/lisp/x11/x-compose.el".
469
471 Dead keys work similarly Multi_key, but they are two-keystroke commands
472 instead of three. For example, pressing the Dead_tilde key, releasing
473 it, then pressing the A key would generate the single keysym Atilde.
474 (They are called ``dead'' keys because they do not, by themselves,
475 insert characters, but instead modify the following character typed.
476 But HP likes to call them ``mute'' instead of ``dead,'' no doubt to
477 avoid frightening the children.)
478 Again, these are not supported by all versions of the Xt library (but
480 can be simulated by XEmacs.)
481 Also note that different vendors have different names for the dead
483 keysyms. For example: depending on your vendor, X server version, and
484 the phase of the moon, you might find that the name of ``dead-tilde''
485 is Dead_Tilde, Dtilde, SunFA_Tilde, SunXK_FA_Tilde, DXK_tilde,
486 DXK_tilde_accent, hpmute_asciitilde, hpXK_mute_asciitilde, or even
487 XK_mute_asciitilde. It's a mess! You'll have to just try it and see
488 what works, if anything.
489
491 People often ask if xkeycaps or xmodmap can be used to make one key
492 generate a sequence of characters. Unfortunately, no: you can't do
493 this sort of thing by manipulating the server's keymaps. The X key‐
494 board model just doesn't work that way.
495 The way to do such things is to set translation resources on particular
497 widgets. It has to be done on an application-by-application basis.
498 For example, here's how you would convince xterm(1) to insert the
499 string next when you hit F17:
500 xterm*VT100.Translations: #override \
501 <Key>F17: string("next")
502 Other applications may have different mechanisms for accomplishing the
503 same thing, and some applications might not support it at all. Check
504 the relevant man pages for specifics.
505 Likewise, you can't convince one key to generate another key with modi‐
507 fiers (for example, you can't make F1 behave like Ctrl-A except by
508 using translations, as above.)
509 It is also not possible to make a keyboard key behave as a mouse but‐
511 ton.
512
514 Both HP and S.u.S.E. ship their systems with broken keyboard settings
515 by default. They really should know better, but they don't.
516 As explained above, it is undefined behavior for one modifier bit to be
518 shared between two keys with dissimilar semantics.
519 By default, HP uses Mod1 for both Meta and Mode_switch. This means
521 that it's impossible for a program to tell the difference between, for
522 example, Meta-X and Mode_switch-X.
523 So, to repair this mess, you need to give the Mode_switch key a differ‐
525 ent modifier bit (mod2, for example.) Or, you could just remove it
526 from the keymap entirely.
527 S.u.S.E. Linux is even more screwed up than HP: whereas HP's default
529 keymap contains only one bug, S.u.S.E.'s default map contains three
530 completely different errors!
531 First, their default keymap has the Control modifier attached to both
533 the Control key and the Multi_key. This is completely crazy, because
534 not only is Multi_key not a control key, it's not even a chording key!
535 It mustn't have any modifier bits attached to it at all.
536 Second, they attach Mod1 to Meta_L and also to Alt_R. Some people
538 think that ``meta'' and ``alt'' are synonyms, but the fact is that the
539 X Window System does not agree. Those are distinct keys. It's possi‐
540 ble to have both ``meta'' and ``alt'' keys on the keyboard at the same
541 time, and to have programs interpret them distinctly. But of course
542 only if they don't bogusly share the same modifier bit, making the
543 interpretation of that bit be ambiguous.
544 Third, they attach Mod5 to both Scroll_Lock and to Hyper_R, which is
546 wrong for reasons that should by now be obvious.
547 The easiest way to fix your S.u.S.E. configuration is to: remove con‐
549 trol from Multi_key; change the left Alt key to generate Alt_L instead
550 of Meta_L; and delete the Hyper_R keysym from the keyboard.
551 If you have any pull with these vendors, I encourage you to encourage
553 them to get their act together.
554
556 XKeyCaps understands all of the core resource names and classes as well
557 as:
558 *Keyboard.keyboard (class Keyboard)
560 Which keyboard to display; this is the same as the -keyboard com‐
561 mand-line option. If this is not specified, the default keyboard
562 is guessed, based on the server's vendor identification string.
563 *Keyboard.Keyboard.selectCursor (class Cursor)
565 The cursor to use when selecting a key or window with the mouse.
566 The default is the crosshair cursor.
567 *Keyboard.Key.highlight (class Background)
569 The color to use to highlight a key when it is depressed. If this
570 is the same as the background color of the key, it is highlighted
571 with a stipple pattern instead.
572 *Keyboard.Key.keycapColor (class Foreground)
574 The color to paint the keycap string.
575 *Keyboard.Key.keycodeColor (class Foreground)
577 The color to paint the keycode number.
578 *Keyboard.Key.borderColor (class Color)
580 The color of the box around each key.
581 *Keyboard.Key.keycapFont (class Font)
583 The font to use to draw the keycap string.
584 *Keyboard.Key.keycodeFont (class Font)
586 The font to use to draw the keycode number.
587 *Keyboard.Key.borderWidth (class Int)
589 The thickness of the box around each key.
590 *Keyboard.Key.gutterWidth (class Int)
592 How many pixels to leave between this key and it's neighbors to the
593 right and bottom.
594 The class of each key widget is ``Key,'' as you see above. The name of
596 each key is the string(s) printed on its face. So if you wanted (for
597 example) the Shift keys to have wider borders, you could specify that
598 with
599 xkeycaps*Keyboard.Shift.borderWidth: 2
600
602 It is possible to rebind the actions which happen when a key or mouse
603 button is pressed or released. These actions are available on the Key‐
604 board widget:
605 HighlightKey(condition, arg)
607 This places the key in question in the highlighted state.
608 If no argument is passed to this action, then the key is determined
610 by the event which invoked this action. If this action is invoked
611 by a KeyPress or KeyRelease event, the key-widget is the key corre‐
612 sponding to the key that the event represents. If it is a Button‐
613 Press, ButtonRelease, or PointerMotion event, then the key-widget
614 is the one under the mouse.
615 The argument may be one of the words mouse, highlighted, or dis‐
617 played, meaning the key under the mouse, the key most recently
618 highlighted, or the key currently being described in the ``Info''
619 area at the top of the window, respectively.
620 The condition may be one of the words ifmod, unlessmod, iftracking,
622 unlesstracking, ifhighlighted, or unlesshighlighted. If ifmod was
623 specified and the key in question (as determined by the argument or
624 by the invoking event) is not a modifier key, then this action is
625 not executed. The unlessmod condition is the opposite. The
626 iftracking and unlesstracking conditions allow you to do some
627 actions only if (or unless) the key is being ``tracked'' with the
628 mouse (see below.) The ifhighlighted and unlesshighlighted actions
629 allow you to do some things only if (or unless) the key in question
630 is currently in the highlighted state.
631 UnhighlightKey(condition, arg)
633 This places the key in question in the unhighlighted state. Argu‐
634 ments are as above.
635 ToggleKey(condition, arg)
637 This makes the key be highlighted if it is unhighlighted, or
638 unhighlighted if it is highlighted. Arguments are as above.
639 SimulateKeyPress(condition, arg)
641 This action makes a KeyPress event corresponding to the key be syn‐
642 thesized on the focus window. Arguments are as above.
643 SimulateKeyRelease(condition, arg)
645 This action makes a KeyRelease event corresponding to the key be
646 synthesized on the focus window. Arguments are as above.
647 TrackKey(condition, arg)
649 This makes the key in question begin being ``tracked'', which means
650 that moving the mouse off of it will simulate a button-release
651 action, and then will simulate a button-press action on the key
652 that the mouse has moved on to. This action may only be invoked
653 from a ButtonPress or ButtonRelease event.
654 UntrackKey(condition, arg)
656 This makes the key in question no longer be ``tracked.''
657 DescribeKey(condition, arg)
659 This action causes the key and its bindings to be displayed in the
660 ``Info'' section at the top of the window, if it is not already
661 described there.
662 The default actions for the Keyboard widget are:
664 <Motion>: DescribeKey(mouse,unlessTracking) \n\
665 \
666 <KeyDown>: HighlightKey() \
667 DescribeKey(unlessMod) \
668 DescribeKey(displayed) \
669 SimulateKeyPress() \n\
670 \
671 <KeyUp>: UnhighlightKey() \
672 DescribeKey(displayed) \
673 SimulateKeyRelease() \n\
674 \
675 <Btn1Down>: HighlightKey(unlessMod) \
676 ToggleKey(ifMod) \
677 TrackKey(unlessMod) \
678 SimulateKeyPress(ifHighlighted) \
679 SimulateKeyRelease(unlessHighlighted) \n\
680 \
681 <Btn1Up>: UntrackKey(highlighted) \
682 SimulateKeyRelease(highlighted,unlessMod) \
683 UnhighlightKey(highlighted,unlessMod) \n\
684 \
685 <Btn3Down>: XawPositionSimpleMenu(keyMenu) \
686 MenuPopup(keyMenu) \n
687 If you don't want a key to be described each time the mouse moves over
688 it, you can remove the <Motion> action. In that case, you should prob‐
689 ably add DescribeKey() to the <Btn1Down> and <KeyDown> actions.
690 If you want the key under the mouse to be described even while the
692 mouse is moving with a button down, then remove the unlessTracking
693 parameter from the DescribeKey action bound to <Motion>.
694 If you don't want the modifier keys to toggle, then change the Button1
696 actions to
697 xkeycaps*Keyboard.actions: #override \
698 <Btn1Down>: HighlightKey() \
699 TrackKey(unlessmod) \
700 SimulateKeyPress() \n\
701 <Btn1Up>: UntrackKey(highlighted) \
702 SimulateKeyRelease(highlighted) \
703 UnhighlightKey(highlighted) \n
704 Remember that these actions exist on the Keyboard widget, not on the
705 Key widgets. If you add actions to the Key widgets, things will mal‐
706 function.
707
709 DISPLAY
710 to get the default host and display number.
711 XENVIRONMENT
713 to get the name of a resource file that overrides the global
714 resources stored in the RESOURCE_MANAGER property.
715 XKEYSYMDB
717 to get the location of the XKeysymDB file, which lists the vendor-
718 specific keysyms.
719
721 The latest version can always be found at http://www.jwz.org/xkeycaps/
722
724 X(1), xmodmap(1), xset(1), xdpyinfo(1)
725
727 Because this program has default colors that aren't "black" and
728 "white", the -rv command-line option doesn't work. But the incantation
729 % xkeycaps -fg white -bg black -bd white
730 will do what you want on a monochrome screen.
731 The NeXT default map is believed to be incorrect; someone with access
733 to a NeXT will need to debug this.
734 There is no portable way to be sure what keyboard is being used; this
736 means it will often not default to the correct one, and if the user
737 makes changes to the keymap while displaying a keyboard which is not
738 the right one, very bad things can happen.
739 If you depress more than a dozen keys at a time, many X servers get
741 confused, and don't transmit enough KeyRelease events; the result of
742 this is that the xkeycaps keys will get ``stuck'' until they are
743 pressed again. (Don't go like that.)
744 The AutoRepeat flag is apparently useless on all X servers except the
746 OpenWindows one (I've never seen another server that didn't ignore it.)
747 You don't get to select from the set of Vendor keysyms (those keysyms
749 which are defined in the XKeysymDB file) unless you're running X11r5 or
750 newer.
751 NCD's non-US keyboards do not use the standard R4/R5 mechanism for
753 attaching more than two keysyms to one key; instead of simply having
754 three or four keysyms attached to the keycode in question, the Compose
755 key changes the actual keycode of the key (it turns its high bit on.)
756 The xkeycaps program doesn't really understand this. Someone from NCD
757 support told me that in future releases they will do things the R4/R5
758 way instead of the way they do things now, so hacking xkeycaps to
759 understand the current behavior is probably not worth the effort.
760 The Type at Window command doesn't seem to work on the WreckStation
762 version of XTerm. I assume some variation of the normal XTerm's Allow
763 SendEvents command is necessary.
764 If you can't select anything from the right-button popup menu, it might
766 be because you have NumLock or CapsLock down. I'm not sure how to fix
767 this, it seems to be some dumb Xt thing.
768 If the popup menu is always greyed out, or doesn't correspond to the
770 key that you clicked on, it might be because you're running xswarm, an
771 old version of xautolock, or some other program that antisocially
772 interferes with event-propagation. (Don't go like that.)
773 Because of the nonlinear way in which this program uses XLookupString,
775 there's no sensible way for it to do compose processing, and show you
776 the results of ``dead'' key or Multi_key sequences.
777 It needs to know about more keyboard types (and no doubt always
779 will...)
780 L-shaped keys aren't drawn accurately. We should use the Shape exten‐
782 sion for that.
783 In addition to displaying the ASCII version of the given character, it
785 should display the corresponding character in the character set
786 (Latin2, Kana, Greek, etc.) This would require having fonts for all of
787 those character sets, though, and as far as I can tell, they don't all
788 come standard.
789 When running on a Sun and talking to an OpenWindows server, we should
791 parse the appropriate file from $OPENWINHOME/etc/keytables/ to deter‐
792 mine the default keymap. No doubt there are system-specific ways of
793 doing this in other environments as well.
794 The HP C compiler complains about "invalid pointer initialization" in
796 the header files. This is a bug in that compiler, not in xkeycaps.
797 This compiler bug goes away if you invoke HP's cc with the the -Aa
798 (ANSI) option.
799 The xmodmap program still sucks. Since its ADD and REMOVE directives
801 take keysyms as arguments instead of keycodes, there are things that
802 you can do with XKeyCaps that you can't represent in an xmodmap script
803 (at least, not without great pain.)
804 The xmodmap program has no commands for changing the autorepeat status
806 of keys, so that information is not written in the output. Perhaps we
807 could write out an appropriate xset command instead. (For example, to
808 turn on autorepeat on PgUp (which happens to have key code 103) on
809 Solaris, you would do: "xset r 103".)
810 Some versions of OpenWound use a nonstandard mechanism for specifying
812 which keys have toggle (lock-like) behavior (whereas most other X
813 servers base this behavior on the keysym: if Caps_Lock or Shift_Lock is
814 generated, the key locks, otherwise it does not.) XKeyCaps doesn't
815 know how to change the lock status on these servers. This is because I
816 don't know how, either. If you know what system calls are necessary to
817 hack this behavior, tell me.
818 The XKB interface of X11R6 looks to provide most of the information
820 which xkeycaps needs to know, but I haven't had time to investigate
821 this yet.
822
824 Copyright © 1991-1999 by Jamie Zawinski. Permission to use, copy, mod‐
825 ify, distribute, and sell this software and its documentation for any
826 purpose is hereby granted without fee, provided that the above copy‐
827 right notice appear in all copies and that both that copyright notice
828 and this permission notice appear in supporting documentation. No rep‐
829 resentations are made about the suitability of this software for any
830 purpose. It is provided "as is" without express or implied warranty.
831
833 Jamie Zawinski <jwz@jwz.org>, 10-nov-91.
834 Please send me any changes you make! Especially new keyboards. The
836 strength of this program lies in the fact that it knows about so many
837 different keyboards, thanks to the hundreds contributions I've received
838 over the years. If you have to make your own modifications, please do
839 your part! Send the changes back to me so that I can incorporate them
840 into a future release.
841 Thanks to:
843 Jonathan Abbey, Alon Albert, Vladimir Alexiev, David Arnold, David
844 Axmark, Ruediger Back, Pedro Bayon, Corne Beerse, Eric Benson,
845 Christoph Berg, Markus Berndt, Roger Binns, Stefan Bj|rnelund,
846 black@westford.ccur.com, Mark Borges, Volker Bosch, Dave Brooks,
847 Lorenzo M. Catucci, Michel Catudal, Francois Regis Colin, John Cop‐
848 pens, Cesar Crusius, Bart Van Cutsem, Matthew Davey, Christopher
849 Davis, Albrecht Dress, Kristian Ejvind, Michael Elbel, Joe English,
850 Eric Fischer, Morgan Fletcher, Olivier Galibert, Carson Gaspar,
851 Andre Gerhard, Daniel Glastonbury, Christian F. Goetze, Dan R.
852 Greening, Edgar Greuter, John Gotts, Berthold Gunreben, Jens Haf‐
853 steinsson, Adam Hamilton, Magnus Hammerin, Kenneth Harker, Ben Har‐
854 ris, Mikael Hedin, Tom Ivar Helbekkmo, Mick Hellstrom, Neil Hendin,
855 Andre Heynatz, Mike Hicks, Alan Ho, Hide Horiuchi, Dirk
856 Jablonowski, Alan Jaffray, Anders Wegge Jakobsen, Chris Jones, Jor‐
857 gen Jonsson, Peter Kaiser, Heikki Kantola, Tufan Karadere, Benedikt
858 Kessler, Philippe Kipfer, Edwin Klement, John Knox, Haavard
859 Kvaalen, Frederic Leguern, Simon Leinen, Michael Lemke, Tor Lil‐
860 lqvist, Torbj|rn Lindgren, Tony Lindstrom, Richard Lloyd, Ulric
861 Longyear, Ulf Magnusson, Cliff Marcellus, John A. Martin, Tom
862 McConnell, Grant McDorman, Hein Meling, Jason Merrill, Aleksandar
863 Milivojevic, Manuel Moreno, Ken Nakata, Pekka Nikander, Todd Nix,
864 Leif Nixon, Christian Nybo, Antoni Pamies Olive, Edgar Bonet
865 Orozco, Steven W. Orr, Martin Ouwehand, Daniel Packman, John
866 Palmieri, Chris Paulson-Ellis, Eduardo Perez, Michael Piotrowski,
867 Andrej Presern, Jeremy Prior, Dominique Quatravaux, Matthias Rabe,
868 Garst R. Reese, Peter Remmers, Todd Richmond, Ken Rose, Pavel
869 Rosendorf, Gael Roualland, Lucien Saviot, Johannes Schmidt-Fischer,
870 Andreas Schuch, Larry Schwimmer, Joe Siegrist, Jarrod Smith, Tom
871 Spindler, Robin Stephenson, Joerg Stippa, D. Stolte, A. A. Stoorvo‐
872 gel, Juergen Stuber, Markus Stumpf, Jeffrey Templon, Jay Thorne,
873 Anthony Thyssen, Christoph Tietz, tkil@scrye.com, Juha Vainikka,
874 Poonlap Veeratanabutr, Ivo Vollrath, Gord Vreugdenhil, Ronan Waide,
875 Jan Wedekind, Bj|rn Wennberg, Mats Wichmann, Stephen Williams,
876 Barry Warsaw, Steven Winikoff, Carl Witty, Stephen Wray, Endre Wit‐
877 zoe, Kazutaka Yokota, Yair Zadik, and Robert Zwickenpflug.
878X Version 11 16-Aug-98 XKeyCaps(1)