Controlling Device Encodings

Getting the Key Mapping of Extended Input Devices

To get the key mapping of an extended input device, use XGetDeviceKeyMapping.

KeySym *XGetDeviceKeyMapping(display, device, first_keycode,
keycode_count, keysyms_per_keycode_return)
      Display *display;
      XDevice *device;
      KeyCode  first_keycode;
      int      keycode_count;
      int     *keysyms_per_keycode_return;

For the specified device, the XGetDeviceKeyMapping function returns the symbols for the specified number of KeyCodes starting with first_keycode. The value specified in first_keycode must be greater than or equal to min_keycode as returned by XListInputDevices, or a BadValue error results. In addition, the following expression must be less than or equal to max_keycode as returned by XListInputDevices:

first_keycode + keycode_count - 1

If this is not the case, a BadValue error results. The number of elements in the KeySyms list is:

keycode_count * keysyms_per_keycode_return

KeySym number N, counting from zero, for KeyCode K has the following index in the list, counting from zero:

(K - first_code) * keysyms_per_code_return + N

The X server arbitrarily chooses the keysyms_per_keycode_return value to be large enough to report all requested symbols. A special KeySym value of NoSymbol is used to fill in unused elements for individual KeyCodes. To free the storage returned by XGetDeviceKeyMapping, use XFree.

If the specified device does not support input class keys, a BadMatch error results.

XGetDeviceKeyMapping can generate a BadDevice, BadMatch, or BadValue error.

Changing the Key Mapping of Extended Input Devices

To change the key mapping of an extended input device, use XChangeDeviceKeyMapping.

int XChangeDeviceKeyMapping(display, device, first_keycode,
keysyms_per_keycode, keysyms, keycode_count)
      Display *display;
      XDevice *device;
      int      first_keycode;
      int      keysyms_per_keycode;
      KeySym  *keysyms;
      int      keycode_count;

For the specified device, the XChangeDeviceKeyMapping function defines the symbols for the specified number of KeyCodes starting with first_keycode. The symbols for KeyCodes outside this range remain unchanged. The number of elements in keysyms must be:

num_codes * keysyms_per_keycode

The specified first_keycode must be greater than or equal to min_keycode returned by XListInputDevices, or a BadValue error results. In addition, the following expression must be less than or equal to max_keycode as returned by XListInputDevices, or a BadValue error results:

first_keycode + num_codes - 1

KeySym number N, counting from zero, for KeyCode K has the following index in keysyms, counting from zero:

(K - first_keycode) * keysyms_per_keycode + N

The specified keysyms_per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired symbols. A special KeySym value of NoSymbol should be used to fill in unused elements for individual KeyCodes. It is legal for NoSymbol to appear in nontrailing positions of the effective list for a KeyCode. XChangeDeviceKeyMapping generates a DeviceMappingNotify event that is sent to all clients that have selected that type of event.

There is no requirement that the X server interpret this mapping. It is merely stored for reading and writing by clients.

If the specified device does not support input class keys, a BadMatch error results.

XChangeDeviceKeyMapping can generate a BadDevice, BadMatch, BadAlloc, or BadValue error.

Getting the Modifier Mapping of Extended Input Devices

To get the modifier mapping of an extended input device, use XGetDeviceModifierMapping.

XModifierKeymap *XGetDeviceModifierMapping(display, device)
      Display *display;
      XDevice *device;

The XGetDeviceModifierMapping function returns a pointer to a newly created XModifierKeymap structure that contains the keys being used as modifiers. The structure should be freed after use by calling XFreeModifierMapping. If only zero values appear in the set for any modifier, that modifier is disabled.

XGetDeviceModifierMapping can generate BadDevice and BadMatch errors.

Setting the Modifier Mapping of Extended Input Devices

To change the modifier mapping of an extended input device, use XSetDeviceModifierMapping.

int XSetDeviceModifierMapping(display, device, modmap)
      Display          *display;
      XDevice          *device;
      XModifierKeymap  *modmap;

The XSetDeviceModifierMapping function specifies the KeyCodes of the keys (if any) that are to be used as modifiers for the specified device. If it succeeds, the X server generates a DeviceMappingNotify event, and XSetDeviceModifierMapping returns MappingSuccess. X permits at most eight modifier keys. If more than eight are specified in the XModifierKeymap structure, a BadLength error results.

The modmap member of the XModifierKeymap structure contains eight sets of max_keypermod KeyCodes, one for each modifier in the order Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5. Only nonzero KeyCodes have meaning in each set, and zero KeyCodes are ignored. In addition, all of the nonzero KeyCodes must be in the range specified by min_keycode and max_keycode as returned by XListInputDevices, or a BadValue error results. No KeyCode may appear twice in the entire map, or a BadValue error results.

An X server can impose restrictions on how modifiers can be changed. Such restrictions are needed, for example, if certain keys do not generate up transitions in hardware, if auto-repeat cannot be disabled on certain keys, or if multiple modifier keys are not supported. If such a restriction is violated, the status reply is MappingFailed, and none of the modifiers are changed. 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 logically down state, XSetDeviceModifierMapping returns MappingBusy, and none of the modifiers are changed.

XSetDeviceModifierMapping can generate BadLength, BadDevice, BadMatch, BadAlloc, and BadValue errors.

The XModifierKeymap structure contains:

typedef struct {
        int      max_keypermod;
        KeyCode *modifiermap;
} XModifierKeymap;

Querying the Device Button Mapping

To check the device button mapping, use XGetDeviceButtonMapping.

int XGetDeviceButtonMapping(display, device, map_return,
nmap)
      Display      *display;
      XDevice      *device;
      unsigned char map_return[];
      int           nmap;

The XGetDeviceButtonMapping function returns the current mapping of the specified device. Buttons are numbered starting from one. XGetDeviceButtonMapping returns the number of physical buttons actually on the device. The nominal mapping for a device is map[i]=i+1. The nmap argument specifies the length of the array where the device mapping is returned, and only the first nmap elements are returned in map_return.

XGetDeviceButtonMapping can generate BadDevice and BadMatch errors.

Changing the Device Button Mapping

To change the device button mapping, use XSetDeviceButtonMapping.

int XSetDeviceButtonMapping(display, device, map, nmap)
      Display      *display;
      XDevice      *device;
      unsigned char map[];
      int           nmap;

The XSetDeviceButtonMapping function sets the mapping of the specified device. If it succeeds, the X server generates a DeviceMappingNotify event, and XSetDeviceButtonMapping returns MappingSuccess. Element map[i] defines the logical button number for the physical button i+1. The length of the list must be the same as XGetDeviceButtonMapping would return, or a BadValue error results. A zero element disables a button, and elements are not restricted in value by the number of physical buttons. However, no two elements can have the same nonzero value, or a BadValue error results. If any of the buttons to be altered are logically in the down state, XSetDeviceButtonMapping returns MappingBusy, and the mapping is not changed.

XSetDeviceButtonMapping can generate BadDevice, BadMatch, and BadValue errors.