XGetDeviceKeyMapping(3)

NAME

       XGetDeviceKeyMapping,  XChangeDeviceKeyMapping - query or change device
       key mappings

SYNTAX

        int XChangeDeviceKeyMapping(Display  *display,  XDevice  *device,  int
       first_keycode,  int  keysyms_per_keycode,  KeySym  *keysyms,  int  key-
       code_count);

       KeySym *XGetDeviceKeyMapping(Display *display, XDevice *device, KeyCode
              first_keycode,    int   keycode_count,   int   *keysyms_per_key-
              code_return);

ARGUMENTS

       display     Specifies the connection to the X server.

       device      Specifies the device whose key mapping is to be queried  or
                   modified.

       first_keycode
                   Specifies the first KeyCode to be returned.

       keycode_count
                   Specifies  the  number  of KeyCodes to be returned or modi-
                   fied.

       keysyms_per_keycode
                   Specifies the number of KeySyms per KeyCode.

       keysyms_per_keycode_return
                   Specifies the address of a variable into which  the  number
                   of KeySyms per KeyCode will be returned.

       keysyms     Specifies the address of an array of KeySyms.

DESCRIPTION

       For  the specified device, the XGetDeviceKeyMapping request returns the
       symbols for the specified number of KeyCodes starting  with  first_key-
       code.   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  ele-
       ments 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 will result.

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

       For  the  specified device, the XChangeDeviceKeyMapping request 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_key-
       code  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.

DIAGNOSTICS

       BadDevice   An invalid device was specified.  The specified device does
                   not  exist or has not been opened by this client via XOpen-
                   InputDevice.  This error may also occur  if  the  specified
                   device is the X keyboard or X pointer device.

       BadMatch    This   error   may  occur  if  an  XGetDeviceKeyMapping  or
                   XChangeDeviceKeyMapping  request  was  made  specifying   a
                   device that has no keys.

       BadValue    Some  numeric  value  falls  outside  the  range  of values
                   accepted by the request.  Unless a specific range is speci-
                   fied  for  an argument, the full range defined by the argu-
                   ment's type is accepted.  Any argument defined as a set  of
                   alternatives can generate this error.

       BadAlloc    The  server  failed  to  allocate the requested resource or
                   server memory.

SEE ALSO

       XSetDeviceButtonMapping(3X11)
       XSetDeviceModifierMapping(3X11)
       Programming with Xlib

X Version 11                      libXi 1.0.2       XGetDeviceKeyMapping(3X11)