XSetModifierMapping() XSetModifierMapping()
Name
XSetModifierMapping - set keycodes to be used as modifiers (Shift, Control, etc.).
Synopsis
int XSetModifierMapping(display, mod_map)
Display *display;
XModifierKeymap *mod_map;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay().
mod_map Specifies the XModifierKeymap() structure containing the desired modifier key codes.
Returns
MappingSuccess on success; MappingFailed or MappingBusy on failure.
Description
XSetModifierMapping() is one of two ways to specify the keycodes of the keys that are to be used as modifiers (like Shift, Control, etc.).
XSetModifierMapping() specifies all the keycodes for all the modifiers at once. The other, easier, way is to use perhaps multiple calls to
XInsertModifiermapEntry() and XDeleteModifiermapEntry(), which add or delete a single keycode for a single modifier key. XSetModifierMap-
ping() does the work in a single call, but you need to manually set up the XModifierKeymap() structure pointed to by mod_map. This manual
set-up involves knowing how the XModifierKeymap() structure is defined and organized, as described in the next three paragraphs.
The XModifierKeymap() structure for the mod_map argument should be created using XNewModifierMap or XGetModifierMapping(). The max_keyper-
mod element of the structure specifies the maximum number of keycodes that can be mapped to each modifier. You define this number but
there may be an upper limit on a particular server.
The modifiermap element of the structure is an array of keycodes. There are eight by max_keypermod keycodes in this array: eight because
there are eight modifiers, and max_keypermod because that is the number of keycodes that must be reserved for each modifier.
The eight modifiers are represented by the constants ShiftMapIndex, LockMapIndex, ControlMapIndex, Mod1MapIndex, Mod2MapIndex, Mod3MapIn-
dex, Mod4MapIndex, and Mod5MapIndex. These are not actually used as arguments, but they are convenient for referring to each row in the
modifiermap structure while filling it. The definitions of these constants are shown in the "Structures" section below.
Now you can interpret the modifiermap array. For each modifier in a given modifiermap, the keycodes which correspond are from modi-
fiermap[index * max_keypermod] to modifiermap[((index + 1) * max_keyspermod) -1] where index is the appropriate modifier index definition
(ShiftMapIndex, LockMapIndex, etc.). You must set the mod_map array up properly before calling XSetModifierMapping(). Now you know why
XInsertModifiermapEntry and XDeleteModifiermapEntry() were created!
Zero keycodes are ignored. No keycode may appear twice anywhere in the map (otherwise, a BadValue error is generated). In addition, all
of the non-zero keycodes must be in the range specified by min_keycode and max_keycode in the Display structure (otherwise a BadValue error
occurs).
A server can impose restrictions on how modifiers can be changed. For example, certain keys may not generate up transitions in hardware,
certain keys may always auto-repeat and therefore be unsuitable for use as modifiers, or multiple modifier keys may not be supported. If a
restriction is violated, then the status reply is MappingFailed, and none of the modifiers are changed.
XSetModifierMapping() can also return MappingSuccess or MappingBusy. The server generates a MappingNotify event on a MappingSuccess sta-
tus. If the new keycodes specified for a modifier differ from those currently defined and any (current or new) keys for that modifier are
in the down state, then the status reply is MappingBusy, and none of the modifiers are changed.
A value of zero for modifiermap indicates that no keys are valid as any modifier.
Structures
typedef struct {
int max_keypermod; /* server's max # of keys per modifier */
KeyCode *modifiermap; /* an 8 by max_keypermod array */
} XModifierKeymap;
/* Modifier name symbols. Used to build a SetModifierMapping request or
to read a GetModifierMapping request. */
#define ShiftMapIndex 0
#define LockMapIndex 1
#define ControlMapIndex 2
#define Mod1MapIndex 3
#define Mod2MapIndex 4
#define Mod3MapIndex 5
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Errors
BadAlloc
BadValue Keycode appears twice in the map.
Keycode < display->min_keycode or
keycode > display->max_keycode.
See Also
XChangeKeyboardMapping(), XDeleteModifiermapEntry(), XDeleteModifiermapEntry(), XFreeModifiermap(), XGetKeyboardMapping(), XGetModifierMap-
ping(), XInsertModifiermapEntry(), XInsertModifiermapEntry(), XKeycodeToKeysym(), XKeysymToKeycode(), XKeysymToString(), XLookupKeysym(),
XLookupString(), XNewModifiermap(), XQueryKeymap(), XRebindKeysym(), XRefreshKeyboardMapping(), XStringToKeysym().
Xlib - Keyboard XSetModifierMapping()