XSetModifie(3x) — HPUX 9.05

NAME

XSetModifierMapping − set keycodes to be used as modifiers (Shift, Control, etc.).

Synopsis

int XSetModifierMapping(display, mod_map)
Display *display;
XModifierKeymap *mod_map;

Arguments

displaySpecifies a connection to an X server; returned from XOpenDisplay().

mod_mapSpecifies the XModifierKeymap() structure containing the desired modifier key codes.

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. XSetModifierMapping() 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_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, Mod3MapIndex, 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 modifiermap[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 nonzero 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() returns MappingSuccess or MappingBusy. The server generates a MappingNotify event on a MappingSuccess status. 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 ShiftMapIndex0
#define LockMapIndex1
#define ControlMapIndex2
#define Mod1MapIndex3
#define Mod2MapIndex4
#define Mod3MapIndex5
#define Mod4MapIndex6
#define Mod5MapIndex7

Errors

BadAlloc

BadValueKeycode appears twice in the map. Keycode < display->min_keycode or
keycode > display->max_keycode.