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:
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().