XSetModifierMapping()XSetModifierMapping()Name
XSetModifierMapping – set keycodes to be used as modifiers (Shift, Con‐
trol, etc.).
Synopsis
int XSetModifierMapping(display, mod_map)
Display *display;
XModifierKeymap *mod_map;
Arguments
display Specifies a connection to an X server; returned from XOpenDis‐
play().
mod_map Specifies the XModifierKeymap() structure containing the
desired modifier key codes.
Returns
MappingSuccess on success; MappingFailed or MappingBusy on failure.
DescriptionXSetModifierMapping() 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 cre‐
ated using XNewModifierMap or XGetModifierMapping(). The max_keypermod
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 con‐
stants 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 defi‐
nition (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, cer‐
tain 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 status.
If the new keycodes specified for a modifier differ from those cur‐
rently 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 AlsoXChangeKeyboardMapping(), XDeleteModifiermapEntry(), XDeleteModi‐
fiermapEntry(), XFreeModifiermap(), XGetKeyboardMapping(), XGetModi‐
fierMapping(), XInsertModifiermapEntry(), XInsertModifiermapEntry(),
XKeycodeToKeysym(), XKeysymToKeycode(), XKeysymToString(), XLookup‐
Keysym(), XLookupString(), XNewModifiermap(), XQueryKeymap(), XRebind‐
Keysym(), XRefreshKeyboardMapping(), XStringToKeysym().
Xlib - Keyboard XSetModifierMapping()
