12.7 Keyboard Encoding
A
KeyCode represents a physical (or logical) key.
KeyCodes lie in the inclusive range [8,255].
A KeyCode value carries no intrinsic information,
although server implementors may attempt to encode geometry
(for example, matrix) information in some fashion so that it can
be interpreted in a server-dependent fashion.
The mapping between keys and KeyCodes cannot be changed.
A KeySym is an encoding of a symbol on the cap of a key.
The set of defined KeySyms includes the ISO Latin character sets (1-4),
Katakana, Arabic, Cyrillic, Greek, Technical,
Special, Publishing, APL, Hebrew, Thai, Korean
and a miscellany of keys found
on keyboards (Return, Help, Tab, and so on).
To the extent possible, these sets are derived from international
standards.
In areas where no standards exist,
some of these sets are derived from Digital Equipment Corporation standards.
The list of defined symbols can be found in
X11/keysymdef.h.
Unfortunately, some C preprocessors have
limits on the number of defined symbols.
If you must use KeySyms not
in the Latin 1-4, Greek, and miscellaneous classes,
you may have to define a symbol for those sets.
Most applications usually only include
X11/keysym.h,
which defines symbols for ISO Latin 1-4, Greek, and miscellaneous.
A list of KeySyms is associated with each KeyCode.
The list is intended to convey the set of symbols on the corresponding key.
If the 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''.
When an explicit ``void'' element is desired in the list,
the value
VoidSymbol
can be used.
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 the 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.
Which group to use is determined by the 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.
The
Lock
modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
is attached to some KeyCode and that KeyCode is attached to the
Lock
modifier. The
Lock
modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock
is attached to some KeyCode and that KeyCode is attached to the
Lock
modifier. If the
Lock
modifier could be interpreted as both
CapsLock and ShiftLock, the CapsLock interpretation is used.
The operation of keypad keys is controlled by the KeySym named XK_Num_Lock,
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
numlock modifier. The standard KeySyms with the prefix ``XK_KP_''
in their
name are called keypad KeySyms; these are KeySyms with numeric value in
the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition,
vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF
are also keypad KeySyms.
Within a group, the choice of KeySym is determined by applying the first
rule that is satisfied from the following list:
-
The numlock modifier is on and the second KeySym is a keypad KeySym. In
this case, if the
Shift
modifier is on, or if the
Lock
modifier is on and
is interpreted as ShiftLock, then the first KeySym is used, otherwise the
second KeySym is used.
-
The
Shift
and
Lock
modifiers are both off. In this case, the first
KeySym is used.
-
The
Shift
modifier is off, and the
Lock
modifier is on and is
interpreted as CapsLock. In this case, the first KeySym is used, but if
that KeySym is lowercase alphabetic, then the corresponding uppercase
KeySym is used instead.
-
The
Shift
modifier is on, and the
Lock
modifier is on and is interpreted
as CapsLock. In this case, the second KeySym is used, but if that KeySym
is lowercase alphabetic, then the corresponding uppercase KeySym is used
instead.
-
The
Shift
modifier is on, or the
Lock
modifier is on and is interpreted
as ShiftLock, or both. In this case, the second KeySym is used.
No spatial geometry of the symbols on the key is defined by
their order in the KeySym list,
although a geometry might be defined on a
server-specific basis.
The X server does not use the mapping between KeyCodes and KeySyms.
Rather, it merely stores it for reading and writing by clients.
To obtain the legal KeyCodes for a display, use
XDisplayKeycodes().
To obtain the symbols for the specified KeyCodes, use
XGetKeyboardMapping().
To change the keyboard mapping, use
XChangeKeyboardMapping().
The next six functions make use of the
XModifierKeymap
data structure, which contains:
typedef struct {
int max_keypermod; /* This server's max number of keys per modifier */
KeyCode *modifiermap; /* An 8 by max_keypermod array of the modifiers */
} XModifierKeymap;
To create an
XModifierKeymap()
structure, use
XNewModifiermap().
To add a new entry to an
XModifierKeymap()
structure, use
XInsertModifiermapEntry().
To delete an entry from an
XModifierKeymap()
structure, use
XDeleteModifiermapEntry().
To destroy an
XModifierKeymap
structure, use
XFreeModifiermap().
To set the KeyCodes to be used as modifiers, use
XSetModifierMapping().
To obtain the KeyCodes used as modifiers, use
XGetModifierMapping().
Christophe Tronche, [email protected]
