 |
Index for
Section 1X |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dxkeycaps(1X)
NAME
dxkeycaps - Graphically display and edit the keyboard mapping
SYNOPSIS
dxkeycaps [-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 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 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 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:
-keyboard keyboard-name or -kbd keyboard-name
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)"
-mapfile mapfile-name
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.
-old
Available only with the newer, XKB-based dxkeycaps command. Specifies
the use of the older, xmodmap-based dxkeycaps command.
-gutterwidthnumber or -gwnumber
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 (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:
Displays the text printed on the physical key, and the keycode
generated by that key in hexadecimal, decimal, and octal.
KeySym:
Displays the set of Key symbols that this key currently generates.
Modifiers:
Displays the modifier bits that this key generates. If a key generates
modifiers, it is a chord-key like Shift or Control.
AutoRepeat:
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 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.
Keyboard
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.
Reset to Default
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.
Save
Appears only on the menu of the xmodmap-based dxkeycaps display.
Functions the same as Save in xmodmap format.
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
.X11Startup file:
xmodmap ~/.dxkeycaps
Save in XKB format
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
Exit
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:
Edit KeySyms of Key
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.)
Exchange Keys
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.
Duplicate Key
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.
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 and redraws the keyboard with the changed keycap reflecting its
new status.
Reset 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 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:
*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 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.
*Keyboard.Key.highlight (class Background)
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.
*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)
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 Keyboard widget:
HighlightKey(condition, arg)
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.
UnhighlightKey(condition, arg)
This action places the key in question in the unhighlighted state.
Arguments are as described for HighlightKey above.
ToggleKey(condition, arg)
This action makes the key be highlighted if it is unhighlighted, or
unhighlighted if it is highlighted. Arguments are as described for
HighlightKey above.
SimulateKeyPress(condition, arg)
This action makes a KeyPress event corresponding to the key be
synthesized on the focus window. Arguments are as described for
HighlightKey above.
SimulateKeyRelease(condition, arg)
This action makes a KeyRelease event corresponding to the key be
synthesized on the focus window. Arguments are as described for
HighlightKey above.
TrackKey(condition, arg)
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.
UntrackKey(condition, arg)
This action 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() \
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.
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 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.
MODIFIER MAPPING
The following description is from the InterClient Communications
Conventions 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
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.
1. 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.
2. If there is no existing modifier controlled by XK_Meta_L or XK_Meta_R,
a. it should select an unused modifier bit (one with an empty
controlling set) and,
b. 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
c. 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
d. if the controlling set is still empty, interact with the user to
select one or more keys to be Meta.
3. 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
DISPLAY
Use this environment variable to get the default host and display
number.
XENVIRONMENT
Use this environment variable to get the name of a resource file that
overrides the global resources stored in the RESOURCE_MANAGER property.
SEE ALSO
X(1X), xmodmap(1X)
|
Index for
Section 1X |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|