dxkeycaps(1X)dxkeycaps(1X)NAMEdxkeycaps - Graphically display and edit the keyboard mapping
SYNOPSISdxkeycaps [-flags ]
FLAGS
Run dxkeycaps with no command line options to edit the keyboard mapping
of the keyboard that is attached to your workstation.
The dxkeycaps command accepts all of the standard toolkit options. It
also accepts the following options: Specifies the type of keyboard to
display. There are many different types of computer keyboards, and to
function correctly dxkeycaps must know which one you are using. The
following keyboards are known: LK401 (American) LK401 (Svenska)
LK201 (American) LK401 (Vlaams)
LK201 (Dansk) LK421 LK201
(Deutsch) LK401 (Dansk) LK201 (Schweiz) LK401 (Deutsch)
LK201 (UK) LK401 (Schweiz) LK201 (Espanol) LK401 (British/Irish)
LK201 (Francais) LK401 (Espanol) LK201 (Canadien) LK401 (Fran‐
cais) LK201 (SuisseRomande) LK401 (Canadien) LK201 (Italiano)
LK401 (SuisseRomande) LK201 (Nederlands) LK401 (Italiano) LK201
(Norsk) LK401 (Nederlands) LK201 (Portugues) LK401 (Norsk)
LK201 (Suomi) LK401 (Portugues) LK201 (Svenska) LK401 (Suomi)
LK201 (Vlaams)
Case does not matter when specifying a keyboard name, but you
must quote keyboard names that contain spaces. For example:
% dxkeycaps-kbd "LK201 (American)" Specifies the number of pix‐
els of space to leave between each key.
DESCRIPTION
The dxkeycaps command displays a keyboard with keycaps drawn according
to the current server keymap. When you move the mouse over a key, the
command describes the key symbols and modifiers that the key generates.
Clicking MB1 on a key simulates pressing a key. Clicking MB3 on a key
brings up a menu of operations, including a command to change the key
symbol that the key generates.
This program is, in part, a graphical front-end to xmodmap.
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 (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:
Displays the text printed on the physical key, and the keycode gener‐
ated by that key in hex, decimal, and octal. Displays the set of Key
symbols that this key currently generates. Displays the modifier bits
that this key generates. If a key generates modifiers, it is a chord-
key like Shift or Control. States whether the X server claims that
this key autorepeats.
Commands Pull-Down Menu
The Commands pull-down menu in the upper left corner of the window con‐
tains the menu items Keyboard, Reset to Default, Save, and Exit: Brings
up a menu from which you can change which keyboard is displayed.
If you run dxkeycaps on a workstation with no command line argu‐
ments, you get a pullright menu for your system's keyboard. dxk‐
eycaps detects what type of keyboard you have on your system and
limits your choices. However, if, in the command line, you spec‐
ify a keyboard, (even if it's the one attached to the display),
or use the -all parameter, the Keyboard menu item will display a
two-level pullright, where the first level for an LK-style key‐
board is:
LK401>
LK201>
LK421 Selecting one of those produces the sub-menu of
international variants described above. An exception is the
LK421, which does not provide international support. If you
select LK421 from the first level menu, the LK421 keyboard is
displayed. This command restores the keyboard to its default
state as defined by the physical keycaps on the keyboard. If you
execute this command while displaying a keyboard that is not the
type of keyboard you are really using, your keymap will be in a
nonsensical state. There is no way for dxkeycaps to tell what
keyboard you are using. This command writes an xmodmap input
file representing the current state of the keyboard (including
all of your changes) to the standard output. The file is saved
in your home directory as ~/.dxkeycaps. 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. Exits the program.
You can arrange for these bindings to be installed each time you log in
by placing an xmodmap command in your .X11Startup file. For example:
xmodmap ~/.dxkeycaps If you place an xmodmap command in your
.X11Startup file, be sure that the file is loaded by the Session Man‐
ager, dxsession. See dxsession(1X) for information about Session Man‐
ager and the
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 your window manager does not
intercept control-left-button for its own purposes.)
Clicking MB3 on a key pops up a menu of commands for the given key.
They are: This pops up the ``Edit Key'' window, which allows you to
arbitrarily change which key symbols and modifiers this key generates.
On the left side of the window is the list of the key symbols
that this key currently generates. (A key may generate up to
eight key symbols; the interpretation of these key symbols is
described in the X protocol document, and is summarized here in
the KEYSYMS AND KEYCODES section.)
The second column is a multiple-choice list of the eight modi‐
fier 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 chang‐
ing the key symbol 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
key symbol in the KeySym column will install that key symbol in
the highlighted slot in the first column.
To select a key symbol 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 modi‐
fied.) 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. 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 key symbols and modifiers. This actu‐
ally changes the current keyboard mapping and redraws the key‐
board with the changed keycap reflecting its new status. The
key on which you brought up the menu will be made to generate no
keysyms and no modifiers. This actually changes the current key‐
board mapping and redraws the keyboard with the changed keycap
reflecting its new status. 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 and
redraws the keyboard with the changed keycap reflecting its new
status.
X DEFAULTS
The dxkeycaps command understands all of the core resource names and
classes as well as:
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. 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 pat‐
tern instead. The color to paint the keycap string. The color to
paint the keycode number. The color of the box around each key. The
font to use to draw the keycap string. The font to use to draw the
keycode number. The thickness of the box around each key. How many
pixels to leave between this key and its neighbors to the right and
bottom.
The class of each key widget is Key as indicated in the previous list.
The name of each key is the string(s) printed on its face. For exam‐
ple, if you wanted the Shift keys to have wider borders, you could
specify:
DXkeycaps*Keyboard.Shift.borderWidth: 2
ACTIONS
It is possible to rebind the actions that happen when you press or
release a key or mouse button. These actions are available on the Key‐
board widget: This places the key in question in the highlighted state.
If no argument is passed to this action, then the key is deter‐
mined 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 dis‐
played, 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, iftrack‐
ing, 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 high‐
lighted state. This places the key in question in the unhigh‐
lighted state. Arguments are as above. This makes the key be
highlighted if it is unhighlighted, or unhighlighted if it is
highlighted. Arguments are as above. This action makes a Key‐
Press event corresponding to the key be synthesized on the focus
window. Arguments are as above. This action makes a KeyRelease
event corresponding to the key be synthesized on the focus win‐
dow. Arguments are as above. 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 simu‐
late 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. This makes the key in question no longer
be ``tracked.'' 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() \
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 do not want a key to be described each time the mouse moves over
it, you can remove the <Motion> action. In that case, you should prob‐
ably 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 do not want the modifier keys to toggle, change the Button1
actions to the following:
DXkeycaps*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 mal‐
function.
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".
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 interpreta‐
tion 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 Key‐
Code to any one of the modifiers Mod1 through Mod5. This modi‐
fier 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 modi‐
fier 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 modi‐
fier 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.
MODIFIER MAPPING
The following description is from the InterClient Communications Con‐
ventions Manual:
X11 supports eight modifier bits, three of which are pre-
assigned to Shift, Lock and Control. Each modifier bit is con‐
trolled by the state of a set of keys, and these sets are speci‐
fied in a table accessed by GetModifierMapping() and SetModi‐
fierMapping().
A client needing to use one of the pre-assigned modifiers should
assume that the modifier table has been set up correctly to con‐
trol these modifiers. The Lock modifier should be interpreted
as Caps Lock or Shift Lock according as the keycodes in its con‐
trolling 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,
should:
Scan the existing modifier mappings. If it finds a modi‐
fier that contains a keycode whose set of keysyms
includes XK_Meta_L or XK_Meta_R, it should use that modi‐
fier 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 cho‐
sen modifier, then
if there is a keycode with XL_Meta_R in its set of
keysyms, add that keycode to the set for the cho‐
sen 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
Use this environment variable to get the default host and display num‐
ber. Use this environment variable to get the name of a resource file
that overrides the global resources stored in the RESOURCE_MANAGER
property.
RESTRICTIONS
Because this program has default colors that are not ``black and
white,'' the -rv command-line option does not work. But the following
incantation does what you want on a monochrome screen:
% dxkeycaps-fg white -bg black -bd white
RELATED INFORMATIONX(1X), xmodmap(1), dxsession(1X)dxkeycaps(1X)