man/XListInputDevices.txt

   1 XLISTINPUTDEVICES(libmansuffix)
   2 ===============================
   3
   4 NAME
   5 ----
   6
   7    XListInputDevices, XFreeDeviceList - list available input
   8    devices
   9
  10 SYNOPSIS
  11 --------
  12
  13    #include <X11/extensions/XInput.h>
  14
  15    XDeviceInfo *XListInputDevices( Display *display,
  16                                    int *ndevices_return);
  17
  18    int XFreeDeviceList( XDeviceInfo *list);
  19
  20    display
  21           Specifies the connection to the X server.
  22
  23    ndevices_return
  24           Specifies a pointer to a variable where the number of
  25           available devices canbe returned.
  26
  27    list
  28           Specifies the list of devices to free. The
  29           XFreeDeviceList functionfrees the list of available
  30           extension input devices.
  31
  32 DESCRIPTION
  33 -----------
  34
  35    The XListInputDevices request lists the available input
  36    devices. This list includes the core keyboard and any physical
  37    input device currently accessible through the X server, and any
  38    input devices that are not currently accessible through the X
  39    server but could be accessed if requested.
  40
  41    A master pointer is a virtual pointer device that does not
  42    represent a physical device. It is visually represented through
  43    a cursor. A master keyboard is a virtual keyboard device that
  44    does not represent a physical device. It is virtually
  45    representd through a keyboard focus. A master pointer and a
  46    master keyboard are always paired (i.e. if shift is pressed on
  47    the master keyboard, a pointer click would be a shift-click).
  48    Multiple master pointer/keyboard pairs can exist.
  49
  50    X servers supporting the X Input Extension version 2,
  51    XListInputDevices only returns the first master pointer, the
  52    first master keyboard and all slave devices. Additional master
  53    devices are not listed.
  54
  55    Physical devices (so-called slave devices) are attached to
  56    either a master pointer or a master keyboard, depending on
  57    their capabilities. If a slave device generates an event, the
  58    event is also generated by the respective master device.
  59    Multiple slave devices can be attached to a single master
  60    device.
  61
  62    Some server implementations may make all physical input devices
  63    available at the time the server is initialized. Others may
  64    wait until requested by a client to access an input device. In
  65    the latter case, it is possible that an input device will be
  66    listed as available at one time but not at another.
  67
  68    For each input device available to the server, the
  69    XListInputDevices request returns an XDeviceInfo structure.
  70    That structure contains a pointer to a list of structures, each
  71    of which contains information about one class of input
  72    supported by the device. The XDeviceInfo structure is defined
  73    as follows:
  74                 typedef struct _XDeviceInfo {
  75                 XID     id;
  76                 Atom    type;
  77                 char    *name;
  78                 int         num_classes;
  79                 int         use;
  80                 XAnyClassPtr inputclassinfo;
  81                 } XDeviceInfo;
  82
  83    The id is a number in the range 0-128 that uniquely identifies
  84    the device. It is assigned to the device when it is initialized
  85    by the server.
  86
  87    The type field is of type Atom and indicates the nature of the
  88    device. The type will correspond to one of the following strings
  89    (defined in the header file XI.h):
  90
  91    XI_MOUSE XI_TABLET XI_KEYBOARD XI_TOUCHSCREEN XI_TOUCHPAD
  92    XI_BUTTONBOX XI_BARCODE XI_TRACKBALL XI_QUADRATURE XI_ID_MODULE
  93    XI_ONE_KNOB XI_NINE_KNOB XI_KNOB_BOX XI_SPACEBALL XI_DATAGLOVE
  94    XI_EYETRACKER XI_CURSORKEYS XI_FOOTMOUSE XI_JOYSTICK
  95
  96    These strings may be used in an XInternAtom request to return
  97    an atom that can be compared with the type field of the
  98    XDeviceInfo structure.
  99
 100    The name field contains a pointer to a null-terminated string
 101    that serves as identifier of the device. This identifier may be
 102    user-configured or automatically assigned by the server.
 103
 104    The num_classes field is a number in the range 0-255 that
 105    specifies the number of input classes supported by the device
 106    for which information is returned by ListInputDevices. Some
 107    input classes, such as class Focus and class Proximity do not
 108    have any information to be returned by ListInputDevices.
 109
 110    All devices provide an AttachClass. This class specifies the
 111    master device a given slave device is attached to. For master
 112    devices, the class specifies the respective paired master
 113    device.
 114
 115    The use field specifies how the device is currently being used.
 116    If the value is IsXKeyboard, the device is a master keyboard.
 117    If the value is IsXPointer, the device is a master pointer. If
 118    the value is IsXExtensionPointer, the device is a slave
 119    pointer. If the value is IsXExtensionKeyboard, the device is a
 120    slave keyboard. If the value is IsXExtensionDevice, the device
 121    is available for use as an extension device.
 122
 123    The inputclassinfo field contains a pointer to the first
 124    input-class specific data. The first two fields are common to
 125    all classes.
 126
 127    The class field is a number in the range 0-255. It uniquely
 128    identifies the class of input for which information is
 129    returned. Currently defined classes are KeyClass, ButtonClass,
 130    and ValuatorClass.
 131
 132    The length field is a number in the range 0- 255. It specifies
 133    the number of bytes of data that are contained in this input
 134    class. The length includes the class and length fields.
 135
 136    The XKeyInfo structure describes the characteristics of the
 137    keys on the device. It is defined as follows:
 138
 139                 typedef struct _XKeyInfo {
 140                 XID class;
 141                 int length;
 142                 unsigned short min_keycode;
 143                 unsigned short max_keycode;
 144                 unsigned short num_keys;
 145                 } XKeyInfo;
 146
 147
 148    min_keycode is of type KEYCODE. It specifies the minimum
 149    keycode that the device will report. The minimum keycode will
 150    not be smaller than 8.
 151
 152    max_keycode is of type KEYCODE. It specifies the maximum
 153    keycode that the device will report. The maximum keycode will
 154    not be larger than 255.
 155
 156    num_keys specifies the number of keys that the device has.
 157
 158    The XButtonInfo structure defines the characteristics of the
 159    buttons on the device. It is defined as follows:
 160
 161                 typedef struct _XButtonInfo {
 162                 XID class;
 163                 int length;
 164                 short num_buttons;
 165                 } XButtonInfo;
 166
 167    num_buttons specifies the number of buttons that the device
 168    has.
 169
 170    The XValuatorInfo structure defines the characteristics of the
 171    valuators on the device. It is defined as follows:
 172
 173                 typedef struct  _XValuatorInfo {
 174                 XID class;
 175                 int length;
 176                 unsigned char num_axes;
 177                 unsigned char mode;
 178                 unsigned long motion_buffer;
 179                 XAxisInfoPtr axes;
 180                 } XValuatorInfo;
 181
 182    num_axes contains the number of axes the device supports.
 183
 184    mode is a constant that has one of the following values:
 185    Absolute or Relative. Some devices allow the mode to be changed
 186    dynamically via the SetDeviceMode request.
 187
 188    motion_buffer_size is a cardinal number that specifies the
 189    number of elements that can be contained in the motion history
 190    buffer for the device.
 191
 192    The axes field contains a pointer to an XAxisInfo structure.
 193
 194    The XAxisInfo structure is defined as follows:
 195
 196                 typedef struct _XAxisInfo {
 197                 int resolution;
 198                 int min_value;
 199                 int max_value;
 200                 } XAxisInfo;
 201
 202    The resolution contains a number in counts/meter.
 203
 204    The min_val field contains a number that specifies the minimum
 205    value the device reports for this axis. For devices whose mode
 206    is Relative, the min_val field will contain 0.
 207
 208    The max_val field contains a number that specifies the maximum
 209    value the device reports for this axis. For devices whose mode
 210    is Relative, the max_val field will contain 0.
 211
 212    The XAttachInfo structure is defined as follows:
 213                 typedef struct _XAttachInfo {
 214                 int     attached;
 215                 } XAttachInfo;
 216
 217    If the device is a slave device, attached specifies the device
 218    ID of the master device this device is attached to. If the
 219    device is not attached to a master device, attached is
 220    Floating. If the device is a master device, attached specifies
 221    the device ID of the master device this device is paired with.
 222
 223    To free the XDeviceInfo array created by XListInputDevices, use
 224    XFreeDeviceList.