XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
NAME
xkeycaps - graphically display and edit the keyboard mapping
SYNOPSIS
xkeycaps [-toolkitoption ...] [-option ...]
DESCRIPTION
The xkeycaps program displays a keyboard. Moving the mouse over a key
describes the keysyms and modifiers that that key generates. Clicking
left on a key simulates a KeyPress event. Clicking right on a key brings
up a menu of operations, including a command to change the keysyms that
the key generates. This program is, in part, a graphical front-end to
xmodmap.
OPTIONS
xkeycaps accepts all of the standard toolkit options, and also accepts
the following options:
-keyboard keyboard-name or -kbd keyboard-name
Specifies the type of keyboard to display. There are many
different computer keyboards in the world, and xkeycaps must know
which one you are using in order to function correctly. The
following keyboards are known:
Dell PC
Sun type2
Sun type3
Sun type4
NCD N97
NCD N101
NCD N102
NCD N102 Swedish/Finnish Layout
NCD N108
NCD vt220
DEC LK201
DEC LK401
IBM RS/6000
SCO 110
HP 720
HP PC
Atari TT
TI Explorer
Case does not matter when specifying a keyboard name, but you may
need to quote the spaces, as in
% xkeycaps -keyboard "sun type4"
-gutterwidth number or -gw number
Specifies the number of pixels of space to leave between each
key.
10/89 Page 1
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
-font fontname
Specifies the font to use to display the keycaps.
The following standard X Toolkit command line arguments are commonly
used with xkeycaps:
-display host:dpy
This option specifies the X server to contact.
-geometry geometry
This option specifies the preferred size and position of the
window.
-bg color
This option specifies the color to use for the background of the
window. The default is light gray.
-fg color
This option specifies the color to use for the foreground of the
window. The default is black.
-bw number
This option specifies the width in pixels of the border
surrounding the window.
-xrm resourcestring
This option specifies a resource string to be used. This is
especially useful for setting resources that do not have separate
command line options.
DISPLAY
The bottom part of the window is a drawing of a keyboard. In the top
left of each key is printed the string which actually appears on the
surface of the key. In the bottom right of the key is the (hexadecimal)
keycode that this key generates.
At the top of the screen are several lines of text describing the key
under the mouse (or the most recently typed key.) These lines are:
KeyCode: This displays the text printed on the physical key, and the
keycode generated by that key in hex, decimal, and octal.
KeySym: This displays the set of KeySyms that this key currently
generates.
ASCII: This displays the ASCII equivalent of this key, taking into
account the current modifier keys which are down.
Modifiers: this displays the modifier bits which this key generates. If
a key generates modifiers, it is a chord-key like Shift or
Control.
Page 2 10/89
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
AutoRepeat: Whether the X server claims that this key autorepeats. I say
``claims'' because I have yet to encounter an X server for
which this information is accurate. The per-key autorepeat
flag seems to be universally ignored.
COMMANDS
There are several buttons in the upper left corner of the window. They
are:
Quit Exits the program.
Select Keyboard
Pops up a menu from which you can change which keyboard is
displayed.
Type At Window
After selecting this, you are asked to click on some other
window. After doing this, clicking on keys on the keyboard
display will simulate key events on the window you selected.
Selecting the root window or the xkeycaps window turns this off.
If you are using a window manager (twm, for example) in which you
can lock the keyboard focus on a window and still click on other
windows without having the focus change, then you can accomplish
the same thing merely by focusing on another window and clicking
on the keys in the xkeycaps window.
Restore Default Map
This command restores the keyboard to its default state. If you
execute this command while displaying a keyboard which is not the
type of keyboard you are really using, your keymap will be in a
nonsensical state. There is no way for xkeycaps to tell what
keyboard you are using except by taking your word for it, so
don't lie.
Write Output
This command writes an xmodmap input file representing the
current state of the keyboard (including all of your changes) to
the standard output. It prompts you with a dialog box: you can
either write an xmodmap file representing the state of every key,
or you can write a smaller file which describes only the changes.
You can arrange for these bindings to be installed each time you
log in by placing the command
xmodmap the-file-written-by-xkeycaps
in the appropriate init file. If you don't know where that is,
ask your system administrator.
10/89 Page 3
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
Clicking left on a key simulates a KeyPress event. Releasing the button
simulates a KeyRelease event. If you click left on a key and move the
mouse while the button is down, KeyPress and KeyRelease events will be
simulated on every key you move the mouse over. Think of the mouse as
your finger: if you drag the mouse over several keys, they will go down
and up in turn.
Clicking left on a key which is associated with modifier bits (such as
Shift or Control) causes that key to ``lock'' down. Clicking left again
releases the key. In this way, you can generate key-chords with the
mouse: to generate Control-C, click left on the Control key, and then
click on the C key. Click on Control again to turn the control modifier
off.
Typing a key on the real keyboard simulates a KeyPress/KeyRelease event
pair in the same way that clicking on a key does.
You can also combine mouse and keyboard input: for example, if you use
the mouse to select the Shift key, and type a character, the event that
is simulated will have the Shift modifier set. And if you hold down the
real Control key, and click on the C key in the window, a control-C event
will be generated. (Assuming, that is, that your window manager does not
intercept control-left-button for its own purposes.)
Clicking right on a key pops up a menu of commands for the given key.
They are:
Exchange Keys
After selecting this menu item, you are asked to click on another
key. That key and the key on which you brought up the menu will
be exchanged. This actually changes the current keyboard
mapping.
Duplicate Key
After selecting this menu item, you are asked to click on another
key. That key will be made a copy of the key on which you
brought up the menu. That is, the two keys will generate the
same set of keysyms and modifiers. This actually changes the
current keyboard mapping.
Disable Key
The key on which you brought up the menu will be made to generate
no keysyms and no modifiers. This actually changes the current
keyboard mapping.
Restore Key To Default
The key on which you brought up the menu will be restored to its
default state; no other key will be altered. This actually
changes the current keyboard mapping.
Page 4 10/89
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
Edit KeySyms of Key
This pops up the "Edit Key" window, which allows you to
arbitrarily change which keysyms and modifiers this key
generates.
On the left side of the window is the list of the keysyms that
this key currently generates. (A key may generate up to eight
keysyms; the interpretation of these keysyms is described in the
X protocol document, and is summarized later in the KEYSYMS AND
KEYCODES section of this man page.)
The second column is a multiple-choice list of the eight modifier
bits that this key may generate. For example, if you want a key
to behave as a ``control'' key, you should select the Control
modifier.
The third and fourth column (the scrolling lists) are for
changing the keysym associated with the key. When you select a
keysym-position from the first column, the character set and
keysym will be displayed in the scrolling lists. Clicking on a
keysym in the ``KeySym'' column will install that keysym in the
highlighted slot in the first column.
To select a keysym from a different character set, click on the
character set name in the second column. (The Latin1 and
Keyboard character sets are the most commonly used.)
At the bottom of the window are three buttons: Undo, Abort, and
Ok. Clicking on Undo reverts the Edit Key window to the current
state of the key in question. Abort closes the Edit Key window
without making any changes. Ok closes the Edit Key window and
installs your changes (the current keyboard mapping is modified.)
X DEFAULTS
xkeycaps understands all of the core resource names and classes as well
as:
*Keyboard.keyboard (class Keyboard)
Which keyboard to display; this is the same as the -keyboard
command-line option. If this is not specified, the default
keyboard is guessed, based on the server's vendor identification
string.
*Keyboard.Keyboard.selectCursor (class Cursor)
The cursor to use when selecting a key or window with the mouse.
The default is the crosshair cursor.
*Keyboard.Key.highlight (class Background)
The color to use to highlight a key when it is depressed. If
this is the same as the background color of the key, it is
highlighted with a stipple pattern instead.
10/89 Page 5
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
*Keyboard.Key.keycapColor (class Foreground)
The color to paint the keycap string.
*Keyboard.Key.keycodeColor (class Foreground)
The color to paint the keycode number.
*Keyboard.Key.borderColor (class Color)
The color of the box around each key.
*Keyboard.Key.keycapFont (class Font)
The font to use to draw the keycap string.
*Keyboard.Key.keycodeFont (class Font)
The font to use to draw the keycode number.
*Keyboard.Key.borderWidth (class Int)
The thickness of the box around each key.
*Keyboard.Key.gutterWidth (class Int)
How many pixels to leave between this key and it's neighbors to
the right and bottom.
The class of each key widget is ``Key,'' as you see above. The name of
each key is the string(s) printed on its face. So if you wanted (for
example) the Shift keys to have wider borders, you could specify that
with
xkeycaps*Keyboard.Shift.borderWidth: 2
ACTIONS
It is possible to rebind the actions which happen when a key or mouse
button is pressed or released. These actions are available on the
Keyboard widget:
HighlightKey(condition, arg)
This places the key in question in the highlighted state.
If no argument is passed to this action, then the key is
determined by the event which invoked this action. If this
action is invoked by a KeyPress or KeyRelease event, the key-
widget is the key corresponding to the key that the event
represents. If it is a ButtonPress, ButtonRelease, or
PointerMotion event, then the key-widget is the one under the
mouse.
The argument may be one of the words mouse, highlighted, or
displayed, meaning the key under the mouse, the key most recently
highlighted, or the key currently being described in the ``Info''
area at the top of the window, respectively.
The condition may be one of the words ifmod, unlessmod,
Page 6 10/89
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
iftracking, unlesstracking, ifhighlighted, or unlesshighlighted.
If ifmod was specified and the key in question (as determined by
the argument or by the invoking event) is not a modifier key,
then this action is not executed. The unlessmod condition is the
opposite. The iftracking and unlesstracking conditions allow you
to do some actions only if (or unless) the key is being
``tracked'' with the mouse (see below.) The ifhighlighted and
unlesshighlighted actions allow you to do some things only if (or
unless) the key in question is currently in the highlighted
state.
UnhighlightKey(condition, arg)
This places the key in question in the unhighlighted state.
Arguments are as above.
ToggleKey(condition, arg)
This makes the key be highlighted if it is unhighlighted, or
unhighlighted if it is highlighted. Arguments are as above.
SimulateKeyPress(condition, arg)
This action makes a KeyPress event corresponding to the key be
synthesized on the focus window. Arguments are as above.
SimulateKeyRelease(condition, arg)
This action makes a KeyRelease event corresponding to the key be
synthesized on the focus window. Arguments are as above.
TrackKey(condition, arg)
This makes the key in question begin being ``tracked'', which
means that moving the mouse off of it will simulate a button-
release action, and then will simulate a button-press action on
the key that the mouse has moved on to. This action may only be
invoked from a ButtonPress or ButtonRelease event.
UntrackKey(condition, arg)
This makes the key in question no longer be ``tracked.''
DescribeKey(condition, arg)
This action causes the key and its bindings to be displayed in
the ``Info'' section at the top of the window, if it is not
already described there.
The default actions for the Keyboard widget are:
<Motion>: DescribeKey(mouse,unlessTracking) \n\
\
<KeyDown>: HighlightKey() \
DescribeKey(unlessMod) \
DescribeKey(displayed) \
SimulateKeyPress() \n\
\
<KeyUp>: UnhighlightKey() \
10/89 Page 7
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
DescribeKey(displayed) \
SimulateKeyRelease() \n\
\
<Btn1Down>: HighlightKey(unlessMod) \
ToggleKey(ifMod) \
TrackKey(unlessMod) \
SimulateKeyPress(ifHighlighted) \
SimulateKeyRelease(unlessHighlighted) \n\
\
<Btn1Up>: UntrackKey(highlighted) \
SimulateKeyRelease(highlighted,unlessMod) \
UnhighlightKey(highlighted,unlessMod) \n\
\
<Btn3Down>: XawPositionSimpleMenu(keyMenu) \
MenuPopup(keyMenu) \n
If you don't want a key to be described each time the mouse moves over
it, you can remove the <Motion> action. In that case, you should
probably add DescribeKey() to the <Btn1Down> and <KeyDown> actions.
If you want the key under the mouse to be described even while the mouse
is moving with a button down, then remove the unlessTracking parameter
from the DescribeKey action bound to <Motion>.
If you don't want the modifier keys to toggle, then change the Button1
actions to
xkeycaps*Keyboard.actions: #override \
<Btn1Down>: HighlightKey() \
TrackKey(unlessmod) \
SimulateKeyPress() \n\
<Btn1Up>: UntrackKey(highlighted) \
SimulateKeyRelease(highlighted) \
UnhighlightKey(highlighted) \n
Remember that these actions exist on the Keyboard widget, not on the Key
widgets. If you add actions to the Key widgets, things will malfunction.
KEYSYMS AND KEYCODES
The following description is from the X Protocol document, and is
reprinted here for your convenience:
A list of KeySyms is associated with each KeyCode. If that list
(ignoring trailing NoSymbol entries) is a single KeySym ``K'', then
the list is treated as if it were the list ``K NoSymbol K
NoSymbol''. If the list (ignoring trailing NoSymbol entries) is a
pair of KeySyms ``K1 K2'', then the list is treated as if it were
the list ``K1 K2 K1 K2''. If the list (ignoring trailing NoSymbol
entries) is a triple of KeySyms ``K1 K2 K3'', then the list is
treated as if it were the list ``K1 K2 K3 NoSymbol''.
Page 8 10/89
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
The first four elements of the list are split into two groups of
KeySyms. Group 1 contains the first and second KeySyms, Group 2
contains third and fourth KeySyms. Within each group, if the
second element of the group is NoSymbol, then the group should be
treated as if the second element were the same as the first
element, except when the first element is an alphabetic KeySym
``K'' for which both lowercase and uppercase forms are defined. In
that case, the group should be treated as if the first element were
the lowercase form of ``K'' and the second element were the
uppercase form of ``K''.
The standard rules for obtaining a KeySym from a KeyPress event
make use of only the Group 1 and Group 2 KeySyms; no interpretation
of other KeySyms in the list is given here. (That is, the last
four KeySyms are unused.)
Which group to use is determined by modifier state. Switching
between groups is controlled by the KeySym named Mode_switch.
By attaching that KeySym to some KeyCode and attaching that KeyCode
to any one of the modifiers Mod1 through Mod5. This modifier is
called the ``group modifier''. For any KeyCode, Group 1 is used
when the group modifier is off, and Group 2 is used when the group
modifier is on.
Within a group, which KeySym to use is also determined by modifier
state. The first KeySym is used when the Shift and Lock modifiers
are off. The second KeySym is used when the Shift modifier is on,
or when the Lock modifier is on and the second KeySym is uppercase
alphabetic, or when the Lock modifier is on and is interpreted as
ShiftLock. Otherwise, when the Lock modifier is on and is
interpreted as CapsLock, the state of the Shift modifier is applied
first to select a KeySym, but if that KeySym is lowercase
alphabetic, then the corresponding uppercase KeySym is used
instead.
THE MODIFIER MAPPING
The following description is from the InterClient Communications
Conventions Manual:
X11 supports 8 modifier bits, of which 3 are pre-assigned to
Shift, Lock and Control. Each modifier bit is controlled by the
state of a set of keys, and these sets are specified in a table
accessed by GetModifierMapping() and SetModifierMapping().
A client needing to use one of the pre-assigned modifiers should
assume that the modifier table has been set up correctly to control
these modifiers. The Lock modifier should be interpreted as Caps
Lock or Shift Lock according as the keycodes in its controlling set
include XK_Caps_Lock or XK_Shift_Lock.
10/89 Page 9
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
Clients should determine the meaning of a modifier bit from the
keysyms being used to control it.
A client needing to use an extra modifier, for example Meta,
should:
Scan the existing modifier mappings. If it finds a modifier
that contains a keycode whose set of keysyms includes
XK_Meta_L or XK_Meta_R, it should use that modifier bit.
If there is no existing modifier controlled by XK_Meta_L or
XK_Meta_R, it should select an unused modifier bit (one with
an empty controlling set) and:
If there is a keycode with XL_Meta_L in its set of
keysyms, add that keycode to the set for the chosen
modifier, then
if there is a keycode with XL_Meta_R in its set of
keysyms, add that keycode to the set for the chosen
modifier, then
if the controlling set is still empty, interact with
the user to select one or more keys to be Meta.
If there are no unused modifier bits, ask the user to take
corrective action.
This means that the Mod1 modifier does not necessarily mean Meta,
although some applications (such as twm and emacs) assume that. Any of
the five unassigned modifier bits could mean Meta; what matters is that a
modifier bit is generated by a keycode which is bound to the keysym
Meta_L or Meta-R.
Therefore, if you want to make a ``meta'' key, the best way is to make
the keycode in question generate both a Meta keysym, and a modifier bit.
ENVIRONMENT
DISPLAY to get the default host and display number.
XENVIRONMENT
to get the name of a resource file that overrides the global
resources stored in the RESOURCE_MANAGER property.
SEE ALSO
X(1), xmodmap(1)
BUGS
Because this program has default colors that aren't "black" and "white",
Page 10 10/89
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
the -rv command-line option doesn't work. But the incantation
% xkeycaps -fg white -bg black -bd white
will do what you want on a monochrome screen.
There is no way to be sure what keyboard is being used; this means it
will often not default to the correct one, and if the user makes changes
to the keymap while displaying a keyboard which is not the right one,
very bad things can happen.
If you depress more than a dozen keys at a time, many X servers get
confused, and don't transmit enough KeyRelease events; the result of this
is that the xkeycaps keys will get ``stuck'' until they are pressed
again. (Don't go like that.)
The AutoRepeat flag is useless, because all X servers I've seen ignore
it.
The Type at Window command doesn't seem to work on the WreckStation
version of XTerm. I assume some variation of the normal XTerm's Allow
SendEvents command is necessary.
If the popup menu is always greyed out, it's probably because you're
running the xswarm program or something like it. (Don't go like that.)
There doesn't seem to be any way to notice key-transitions when we don't
have the keyboard focus. I would like this program to track the state of
the keyboard even when the user isn't focusing on it.
The output should be written to a file instead of to standard-output; but
the Athena widget set doesn't seem to come with a file-requestor widget,
and I don't want to write one.
It needs to know about more keyboard types.
L-shaped keys aren't drawn accurately. We should use the Shape extension
for that.
In addition to displaying the ASCII version of the given character, it
should display the corresponding character in the character set (Latin2,
Kana, Greek, etc.) This would require having fonts for all of those
character sets, though, and as far as I can tell, they don't all come
standard.
COPYRIGHT
Copyright 1991, Jamie Zawinski. Permission to use, copy, modify,
distribute, and sell this software and its documentation for any purpose
is hereby granted without fee, provided that the above copyright notice
appear in all copies and that both that copyright notice and this
permission notice appear in supporting documentation. No representations
10/89 Page 11
XKeyCaps(1) X Version 11(9-jan-91) XKeyCaps(1)
are made about the suitability of this software for any purpose. It is
provided "as is" without express or implied warranty.
AUTHOR
Jamie Zawinski <jwz@lucid.com>, 10-nov-91. Please let me know if you
find any bugs or make any improvements.
The Dell PC keyboard definition was contributed by Dell Computer
Corporation. <info@dell.com>
The IBM RS/6000 keyboard definition was contributed by Tom McConnell
<tmcconne@sedona.intel.com>.
The NCD-N102 and NCD-N102-Swedish/Finnish keyboard definitions were
contributed by Pekka Nikander <pnr@innopoli.ajk.tele.fi>.
The HP 720 keyboard definition was contributed by Dave Brooks
<dbrooks@inel.gov>.
The HP PC keyboard definition was contributed by Markus Stumpf
<stumpf@informatik.tu-muenchen.de>.
The Atari TT keyboard definition was contributed by Mats Wichmann
<mats@alruna.com>.
The SCO ODT 110 keyboard definition was contributed by Steven W. Orr
<steveo@world.std.com>.
The DEC LK401 keyboard definition was contributed by Tom Ivar Helbekkmo
<tih@barsoom.nhh.no>.
Page 12 10/89