Man page for apt-get xkeycaps Command
This tutorial shows the man page for man xkeycaps in linux.
Open terminal with 'su' access and type the command as shown below:
Result of the Command Execution shown below:
xkeycaps graphically display and edit the X keyboard mapping
xkeycaps [ toolkitoption ...] [ option ...]
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(1).
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 differ
ent computer keyboards in the world, and xkeycaps must know which
one you are using in order to function correctly. Case does not
matter when specifying a keyboard name.
If you're running on the console display of a Sun or HP, then xkey
caps will interrogate the attached keyboard hardware directly to
determine what keyboard you're using. But if you're running
remotely, or on another type of machine, then you must specify a
Lists the recognized values for the keyboard option.
gutterwidth number or gw number
Specifies the number of pixels of space to leave between each key.
Specifies the font to use to display the keycaps.
The following standard X Toolkit command line arguments are commonly
used with xkeycaps:
This option specifies the X server to contact.
This option specifies the preferred size and position of the win
This option specifies the color to use for the background of the
window. The default is light gray.
This option specifies the color to use for the foreground of the
window. The default is black.
This option specifies the width in pixels of the border surrounding
This option specifies a resource string to be used. This is espe
cially useful for setting resources that do not have separate com
mand line options.
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 (hexadeci
mal) 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
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
AutoRepeat: Whether the X server claims that this key autorepeats. I
say ``claims'' because the OpenWindows X server is the only
one I have encountered for which this information is accu
rate. The per key autorepeat flag seems to be almost uni
There are several buttons in the upper left corner of the window. They
Exits the program.
Pops up a dialog box from which you can change which keyboard is
displayed. The left column lists the known types of keyboards, and
the right column lists the known layouts (mappings) of those key
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 (for example, twm(1)) 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 accom
plish 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 key
board you are using except by taking your word for it, so don't
This command writes an xmodmap input file representing the current
state of the keyboard (including all of your changes) to a file in
your home directory. Note that this command DOES NOT write out the
default keymap for this keyboard type unless you have clicked on
Restore Default Map before.
The file will be called .xmodmap hostname, where hostname is the
name of the machine you're running on. It will warn you if the
file already exists.
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.
The idea is that in the appropriate startup script, you would add a
xmodmap /.xmodmap `uname n`
in the appropriate init file, so that those keyboard modifications
are made each time you log in. (If you're not sure where this com
mand should go, ask your system administrator, as that tends to
vary from site to site.)
Clicking left on a key simulates a KeyPress event. Releasing the but
ton 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
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.
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 changes the keyboard mapping immediately.
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 changes the keyboard mapping immedi
The key on which you brought up the menu will be made to generate
no keysyms and no modifiers. This changes the 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.
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 sec
tion 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 modi
The third and fourth column (the scrolling lists) are for changing
the keysym associated with the key. When you select a keysym posi
tion 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.)
KEYSYMS AND KEYCODES
To effectively edit your keyboard mapping, there are some terms you
need to be familiar with:
KeyCode This is a raw scan code that is read from the keyboard; each
physical key on the keyboard has a different number associ
ated with it; this mapping cannot be changed (but that's ok.)
Generally, every keyboard has its own set of KeyCodes, which
is why you will probably need to have a different keymap for
every system you use.
KeySym This is a symbol which can be generated by a single press of
one key on the keyboard: for example, all letters, numbers,
and punctuation are keysyms, and so are more abstract things
like ``shift'' and ``control''.
Each KeyCode (that is, key on the keyboard) is associated
with certain KeySyms. The KeySyms are what give the keys
their semantics (and makes the A key generate an A), not the
Usually keys are associated with one or two keysyms, which
correspond to the symbols generated when the key is pressed,
and when it is pressed while the shift key is held down.
There is a special case, which is that if the key contains
only one KeySym, and it is a letter, then the Shift key does
the obvious thing that one does to letters.
KeyCap Not to be confused with KeySyms, this refers to the text
which is printed on the physical keys: it is immutable
(unless you repaint your keyboard...)
Chord This term refers to a set of two or more keys held down
simultaneously (by analogy with piano keyboards.) All but
one of the keys will generally be Modifier Keys. Sometimes
Constellation is used to mean the same thing.
This is a key like shift or control, which is used to alter
the interpretation of other keys which are held down at the
same time. Generally, pressing a modifier key without also
pressing a non modifier key does nothing.
A key is a modifier key if it has a Modifier KeySym on it.
(More specifically, if the KeyCode of that key is associated
with a Modifier KeySym.)
A KeySym is a modifier keysym if it has a Modifier Bit asso
ciated with it. But, the rules are a little more complicated
than that. It's easier to describe by example:
For a key to behave as one expects a shift key to behave, the
keycode should have the Shift modifier bit set; and the key
should generate one of the keysyms Shift_L and Shift_R. If
either of these is not true, the key will not behave as a
Analogously, a control key must have the Control modifier
set, and use one of the keysyms Control_L or Control_R.
This implies that if you wanted to swap your shift and con
trol keys, it would not be enough to simply swap their modi
fier bits: you must swap their keysyms as well. If you only
swap the modifier bits, it might appear to work at first, but
other things would malfunction.
Keys like Meta (and Super, Hyper, etc.) are a bit more com
plicated (see below.)
Modifier bits are attributes which certain keysyms can have.
Some modifier bits have predefined semantics: Shift, Lock,
and Control. The remaining modifier bits (Mod1 through Mod5)
have semantics which are defined by the keys with which they
That is, the Control modifier means Control if it is attached
to Control_L or Control_R, and is illegal elsewhere.
But Mod1 means Meta if it is attached to Meta_L or Meta_R;
but it would mean Alt if it were attached to Alt_L or Alt_R;
or Hyper with Hyper_L or Hyper_R; and so on. (It could not,
however, be attached to Control_L, since the Control modifier
has already spoken for those keysyms.)
If you're thinking that this is all senselessly compli
cated... you're right.
X PROTOCOL DOCUMENT ON KEYMAPS
The following is a more precise technical explanation of how keymapping
works. This 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 NoSym
bol''. 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''.
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 sec
ond element of the group is NoSymbol, then the group should be
treated as if the second element were the same as the first ele
ment, 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 inter
preted as CapsLock, the state of the Shift modifier is applied
first to select a KeySym, but if that KeySym is lowercase alpha
betic, then the corresponding uppercase KeySym is used instead.
ICCCM ON THE MODIFIER MAPPING
The following is a more precise technical explanation of how modifier
keys are interpreted. This description is from the Inter Client Commu
nications Conventions Manual, and is reprinted here for your conve
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.
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,
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 cor
The above means that the Mod1 modifier does not necessarily mean Meta,
although some applications (such as twm and emacs 18) 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 right way is to make
the keycode in question generate both a Meta keysym, and some previ
ously unassigned modifier bit.
THE MODE_SWITCH KEYSYM
In case the above didn't make sense, what the Mode_switch keysym does
is, basically, act as an additional kind of shift key. If you have
four keysyms attached to the A key, then those four keysyms will be
accessed by the chords: A; Shift A, Mode_Switch A; and Mode_Switch
Shift A, respectively.
Like any Modifier Key, for Mode_switch to function, it must have a mod
ifier bit attached to it. So, select one of the bits Mod1 through Mod5
(whichever is unused) and attach that to the Mode_switch key.
THE MULTI_KEY KEYSYM
Not to be confused with Mode_switch, Multi_key allows the input of mul
tiple character sequences that represent a single character (keysym.)
A more traditional name for this keysym might have been Compose.
The Multi_key keysym is not a modifier keysym. That is, for it to
function properly, it should not have any modifier bits associated with
it. This is because it is not a ``chording'' key: you do not hold it
down along with other keys. Rather, you press Multi_key, then release
it, then press and release another key, and the two together yield a
For example, one traditional binding would be for Multi_key, followed
by single quote, followed by A to produce the Aacute keysym.
Not all vendors support the use of the Multi_key keysym; in particular,
Digital, Sun, and HP support it, but the X Consortium does not. (The
reason for this, I am told, is that ``Compose'' sequences are consid
ered obsolete; the party line is that you should be using Input Methods
to do this.)
Whether Multi_key works is a property of the Xt library (not the X
server) so it's possible that on a single system, Multi_key might work
with some applications and not others (depending on how those applica
tions were compiled and linked.)
If you use Lucid Emacs or XEmacs, then you can take advantage of
Multi_key sequences even if your version of Xt doesn't support it, by
loading the x compose library, which simulates the traditional Xt
behavior. For more info, read the commentary at the top of the file
"/usr/local/lib/xemacs */lisp/x11/x compose.el".
Dead keys work similarly Multi_key, but they are two keystroke commands
instead of three. For example, pressing the Dead_tilde key, releasing
it, then pressing the A key would generate the single keysym Atilde.
(They are called ``dead'' keys because they do not, by themselves,
insert characters, but instead modify the following character typed.
But HP likes to call them ``mute'' instead of ``dead,'' no doubt to
avoid frightening the children.)
Again, these are not supported by all versions of the Xt library (but
can be simulated by XEmacs.)
Also note that different vendors have different names for the dead
keysyms. For example: depending on your vendor, X server version, and
the phase of the moon, you might find that the name of ``dead tilde''
is Dead_Tilde, Dtilde, SunFA_Tilde, SunXK_FA_Tilde, DXK_tilde,
DXK_tilde_accent, hpmute_asciitilde, hpXK_mute_asciitilde, or even
XK_mute_asciitilde. It's a mess! You'll have to just try it and see
what works, if anything.
THINGS YOU CAN'T DO
People often ask if xkeycaps or xmodmap can be used to make one key
generate a sequence of characters. Unfortunately, no: you can't do
this sort of thing by manipulating the server's keymaps. The X key
board model just doesn't work that way.
The way to do such things is to set translation resources on particular
widgets. It has to be done on an application by application basis.
For example, here's how you would convince xterm(1) to insert the
string next when you hit F17: