dxkeycaps - Graphically display and edit the keyboard mapping
dxkeycaps [-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 application.
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 XKBbased
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 subset. 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 keyboards).
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, specify:
% dxkeycaps -kbd pcxal
To cause the system to display a keyboard based on
kernel and console environment information, just as
if you issued a dxkeycaps 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 mapfilename
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.
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 [Toc] [Back]
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: Displays the text printed on
the physical key, and the keycode generated by that key in
hexadecimal, 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 key autorepeats as defined by the X
server.
Commands Pull-Down Menu [Toc] [Back]
The Commands pull-down menu in the upper left corner of
the window contains 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 format.
Brings up a menu that allows you to change which keyboard
is displayed. 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 following
command in your file:
xmodmap ~/.dxkeycaps Appears only on the menu of
the XKB-based dxkeycaps display. This command
writes an xkb 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_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 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 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 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 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 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.
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 pattern
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
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 Keyboard widget: This action 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, 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 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 question 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 HighlightKey above. This action
makes a KeyRelease event corresponding to the key
be synthesized on the focus window. Arguments 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 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 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 malfunction.
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
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 following description is from the InterClient Communications
Conventions Manual:
X11 supports eight modifier bits, three of which are preassigned
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, 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.
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.
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 [Toc] [Back] Use this environment variable to get the default host and
display number. Use this environment variable to get the
name of a resource file that overrides the global
resources stored in the RESOURCE_MANAGER property.
X(1X), xmodmap(1X)
dxkeycaps(1X)
[ Back ] |
