1XKeyCaps(1)                 General Commands Manual                XKeyCaps(1)
2
3
4

NAME

6       xkeycaps - graphically display and edit the X keyboard mapping
7

SYNOPSIS

9       xkeycaps [-toolkitoption ...] [-option ...]
10

DESCRIPTION

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

OPTIONS

20       xkeycaps accepts all of the standard toolkit options, and also  accepts
21       the following options:
22
23       -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
29           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
35       -help
36           Lists the recognized values for the -keyboard option.
37
38       -gutterwidth number or -gw number
39           Specifies the number of pixels of space to leave between each key.
40
41       -font fontname
42           Specifies the font to use to display the keycaps.
43
44
45       The following standard X Toolkit command line  arguments  are  commonly
46       used with xkeycaps:
47
48       -display host:dpy
49           This option specifies the X server to contact.
50
51       -geometry geometry
52           This  option  specifies the preferred size and position of the win‐
53           dow.
54
55       -bg color
56           This option specifies the color to use for the  background  of  the
57           window.  The default is light gray.
58
59       -fg color
60           This  option  specifies  the color to use for the foreground of the
61           window.  The default is black.
62
63       -bw number
64           This option specifies the width in pixels of the border surrounding
65           the window.
66
67       -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

DISPLAY

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
78       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
81       KeyCode:    This displays the text printed on the physical key, and the
82                   keycode generated by that key in hex, decimal, and octal.
83
84       KeySym:     This displays the set of KeySyms that  this  key  currently
85                   generates.
86
87       ASCII:      This displays the ASCII equivalent of this key, taking into
88                   account the current modifier keys which are down.
89
90       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
94       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

COMMANDS

101       There are several buttons in the upper left corner of the window.  They
102       are:
103
104       Quit
105           Exits the program.
106
107       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
113       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
119           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
125       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
133       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
138           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
142           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
146           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
154       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
161       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
168       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
171       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
178       Clicking right on a key pops up a menu of commands for the  given  key.
179       They are:
180
181       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
186       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
193       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
198       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
203       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
207           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
213           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
218           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
225           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
229           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

KEYSYMS AND KEYCODES

236       To effectively edit your keyboard mapping, there  are  some  terms  you
237       need to be familiar with:
238
239       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
243                 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
247       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
252                 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
257                 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
264       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
268       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
273       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
279                 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
283       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
288                 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
294                 Analogously, a control key must  have  the  Control  modifier
295                 set, and use one of the keysyms Control_L or Control_R.
296
297                 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
303                 Keys  like  Meta (and Super, Hyper, etc.) are a bit more com‐
304                 plicated (see below.)
305
306       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
313                 That is, the Control modifier means Control if it is attached
314                 to Control_L or Control_R, and is illegal elsewhere.
315
316                 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
322                 If  you're  thinking  that  this  is  all senselessly compli‐
323                 cated... you're right.
324

X PROTOCOL DOCUMENT ON KEYMAPS

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
330           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
339           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
350           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
355           Which  group  to  use  is  determined by modifier state.  Switching
356           between groups is controlled by the KeySym named Mode_switch.
357
358           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
364           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

ICCCM ON THE MODIFIER MAPPING

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
380           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
385           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
391           Clients should determine the meaning of a  modifier  bit  from  the
392           keysyms being used to control it.
393
394           A  client  needing  to  use  an  extra modifier,  for example Meta,
395           should:
396
397             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
401             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
405               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
408               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
411               if the controlling set is still empty,  interact with the  user
412               to select one or more keys to be Meta.
413
414             If  there  are no unused modifier bits, ask the user to take cor‐
415             rective action.
416
417       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
423       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

THE MODE_SWITCH KEYSYM

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
434       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

THE MULTI_KEY KEYSYM

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
443       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
450       For  example,  one traditional binding would be for Multi_key, followed
451       by single-quote, followed by A to produce the Aacute keysym.
452
453       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
459       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
464       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

DEAD KEYSYMS

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
479       Again,  these  are not supported by all versions of the Xt library (but
480       can be simulated by XEmacs.)
481
482       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

THINGS YOU CAN'T DO

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
496       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
506       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
510       It is also not possible to make a keyboard key behave as a  mouse  but‐
511       ton.
512

LOSER VENDORS

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
517       As explained above, it is undefined behavior for one modifier bit to be
518       shared between two keys with dissimilar semantics.
519
520       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
524       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
528       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
532       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
537       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
545       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
548       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
552       If  you  have any pull with these vendors, I encourage you to encourage
553       them to get their act together.
554

X RESOURCES

556       XKeyCaps understands all of the core resource names and classes as well
557       as:
558
559       *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
564       *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
568       *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
573       *Keyboard.Key.keycapColor (class Foreground)
574           The color to paint the keycap string.
575
576       *Keyboard.Key.keycodeColor (class Foreground)
577           The color to paint the keycode number.
578
579       *Keyboard.Key.borderColor (class Color)
580           The color of the box around each key.
581
582       *Keyboard.Key.keycapFont (class Font)
583           The font to use to draw the keycap string.
584
585       *Keyboard.Key.keycodeFont (class Font)
586           The font to use to draw the keycode number.
587
588       *Keyboard.Key.borderWidth (class Int)
589           The thickness of the box around each key.
590
591       *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
595       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

ACTIONS

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
606       HighlightKey(condition, arg)
607           This places the key in question in the highlighted state.
608
609           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
616           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
621           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
632       UnhighlightKey(condition, arg)
633           This  places the key in question in the unhighlighted state.  Argu‐
634           ments are as above.
635
636       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
640       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
644       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
648       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
655       UntrackKey(condition, arg)
656           This makes the key in question no longer be ``tracked.''
657
658       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
663       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
691       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
695       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

ENVIRONMENT

709       DISPLAY
710           to get the default host and display number.
711
712       XENVIRONMENT
713           to get the name of  a  resource  file  that  overrides  the  global
714           resources stored in the RESOURCE_MANAGER property.
715
716       XKEYSYMDB
717           to  get the location of the XKeysymDB file, which lists the vendor-
718           specific keysyms.
719

UPGRADES

721       The latest version can always be found at http://www.jwz.org/xkeycaps/
722

SEE ALSO

724       X(1), xmodmap(1), xset(1), xdpyinfo(1)
725

BUGS

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
732       The  NeXT  default map is believed to be incorrect; someone with access
733       to a NeXT will need to debug this.
734
735       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
740       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
745       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
748       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
752       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
761       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
765       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
769       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
774       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
778       It  needs  to  know  about  more  keyboard  types  (and no doubt always
779       will...)
780
781       L-shaped keys aren't drawn accurately.  We should use the Shape  exten‐
782       sion for that.
783
784       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
790       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
795       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
800       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
805       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
811       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
819       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

AUTHOR

833       Jamie Zawinski <jwz@jwz.org>, 10-nov-91.
834
835       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
842       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.
878
879
880
881X Version 11                       16-Aug-98                       XKeyCaps(1)
Impressum