dxkeycaps(1X)dxkeycaps(1X)NAMEdxkeycaps - Graphically display and edit the keyboard mapping
SYNOPSISdxkeycaps [-options]
OPTIONS
Use the dxkeycaps command to display and edit the keyboard mapping of
the keyboard that is attached to your workstation.
Depending on the command line options you use, the dxkeycaps command
can invoke a newer XKB-based program or an older xmodmap-based program.
The older dxkeycaps program is, in part, a graphical front-end to
xmodmap; whereas, the new dxkeycaps program is an XKB-capable applica‐
tion. Except where noted, the XKB-based and xmodmap-based dxkeycaps
commands function the same. This reference page applies to both and
notes any difference between the XKB-based and xmodmap-based commands.
A dxkeycaps command with no options invokes the XKB-based dxkeycaps
program.
The xmodmap-based dxkeycaps program is installed with the BaseOS sub‐
set. You use dxkeycaps with the -old option to invoke it.
Both the XKB-based and the xmodmap-based dxkeycaps programs are built
with X Toolkit Intrinsics and accept all of the standard toolkit
options. See X(1X) for more information on the X Toolkit, XKB, and
xmodmap.
Except where noted, both dxkeycaps commands accept the following
options: Specifies the type of keyboard to display. There are many
different types of computer keyboards. To function correctly, dxkeycaps
must know which keyboard you are using. The known keyboard types are
defined in keymap files that reside in /usr/lib/X11/xkb/keymap/ (for
XKB format keyboards) or /usr/lib/X11/keymaps/ (for xmodmap format key‐
boards).
If the console's keyboard language parameter is set correctly, a
dxkeycaps command with no option selects the correct keyboard by
default. Likewise, a -keyboard option with no command line
parameters selects the correct keyboard by default. (To set the
console's keyboard language, use the set language command. See
the section on environment variables in your workstation user's
guide.)
To display a keyboard layout, the keyboard must be attached to
the machine that hosts the display.
To display the British/Irish keyboard layout, specify:
% dxkeycaps-kbd "pcxal (British/Irish)"
To display the default PCXAL (American) keyboard layout, spec‐
ify:
% dxkeycaps-kbd pcxal
To cause the system to display a keyboard based on kernel and
console environment information, just as if you issued a dxkey‐
caps command with no parameters, specify:
% dxkeycaps-kbd badkeyboardname
Case does not matter when you specify a keyboard name, but you
must quote keyboard names that contain spaces. For example:
% dxkeycaps-kbd "PCXAL-AE (United Kingdom)" Available only with
the newer, XKB-based dxkeycaps command. Specifies the use of a
specific keymap file. Use this option to specify a user-owned
keymap file or to load a different keymap file. The mapfile-
name parameter must include the full path. Available only with
the newer, XKB-based dxkeycaps command. Specifies the use of the
older, xmodmap-based dxkeycaps command. Available only with the
older, xmodmap-based dxkeycaps command. Specifies the space, in
pixels, 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.
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 hexadecimal, decimal, and octal. Displays the set
of Key symbols that this key currently generates. Displays the modi‐
fier bits that this key generates. If a key generates modifiers, it is
a chord-key like Shift or Control. States whether the key autorepeats
as defined by the X server.
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. If you
are running the XKB-based dxkeycaps command, the Save menu item is
replaced by the menu items Save in xmodmap format and Save in XKB for‐
mat. Brings up a menu that allows you to change which keyboard is dis‐
played. The display formats differently depending on whether you are
using the XKB-based or xmodmap-based dxkeycaps command. But in either
case, the display contains the known keyboard types for your system and
the keyboard language. 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, the display will not match the keyboard and may
contain unintelligible characters. There is no way for dxkeycaps to
tell what keyboard you are using. Appears only on the menu of the
xmodmap-based dxkeycaps display. Functions the same as Save in xmodmap
format. Appears only on the menu of the XKB-based dxkeycaps display.
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.
The command 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. To
install these key bindings each time you login, include the fol‐
lowing command in your file:
xmodmap ~/.dxkeycaps Appears only on the menu of the XKB-based
dxkeycaps display. This command writes an xkb input file repre‐
senting 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_xkb. To install these key bindings
each time you login, include the following command in your
~/.dt/sessions/sessionetc file:
xkbcomp -o $DISPLAY $HOME/.dxkeycaps_xkb Exits the program.
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: Launches the “Edit Key” window, which allows you to arbitrar‐
ily 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. Clicking on Abort closes the Edit
Key window without making any changes. Clicking on Ok closes the
Edit Key window and installs your changes (that is, the current
keyboard mapping is modified.) Launches a dialogue that asks
you 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. Prompts you to click on another key.
The key you click on becomes a copy of the key on which you
brought up the menu. That is, the two keys generate the same set
of key symbols and modifiers. This actually changes the current
keyboard mapping and redraws the keyboard with the changed key‐
cap 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 keyboard 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 derived from the server's vendor identification string.
dxkeycaps can distinguish between keyboard classes, and will not allow
displaying or editing the keyboard of one class on a workstation that
has the keyboard of a different class. The color to use to highlight a
key when it is depressed. If the highlight color is the same as the
background color of the key, the key 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. The number
of 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 example,
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 action 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 of ifmod.
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. This action places the key in ques‐
tion in the unhighlighted state. Arguments are as described for
HighlightKey above. This action makes the key be highlighted if
it is unhighlighted, or unhighlighted if it is highlighted.
Arguments are as described for HighlightKey above. This action
makes a KeyPress event corresponding to the key be synthesized
on the focus window. Arguments are as described for High‐
lightKey above. This action makes a KeyRelease event corre‐
sponding to the key be synthesized on the focus window. Argu‐
ments are as described for HighlightKey above. This action
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. This action 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 (ignor‐
ing 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 con‐
tains third and fourth KeySyms. Within each group, if the second ele‐
ment 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. Oth‐
erwise, 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.
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 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 mod‐
ifiers. 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, should
scan the existing modifier mappings. If it finds a modifier that con‐
tains 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 con‐
trolled 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.
These modifier mappings can indicate 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.
RESTRICTIONS
Because this program has default colors that are not “black and white,”
the -rv command-line option does not work. But the following command
line acts as expected on a monochrome screen:
% dxkeycaps-fg white -bg black -bd white
Low-resolution monitors can not display key descriptions.
ENVIRONMENT VARIABLES
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.
SEE ALSOX(1X), xmodmap(1X)dxkeycaps(1X)