1XLISTINPUTDEVICES(3)                                      XLISTINPUTDEVICES(3)
2
3
4

NAME

6       XListInputDevices, XFreeDeviceList - list available input devices
7

SYNOPSIS

9       #include <X11/extensions/XInput.h>
10
11       XDeviceInfo *XListInputDevices( Display *display,
12                                       int *ndevices_return);
13
14       int XFreeDeviceList( XDeviceInfo *list);
15
16       display
17              Specifies the connection to the X server.
18
19       ndevices_return
20              Specifies a pointer to a variable where the number of
21              available devices can be returned.
22
23       list
24              Specifies the list of devices to free. The
25              XFreeDeviceList function frees the list of available
26              extension input devices.
27

DESCRIPTION

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

RETURN VALUE

217           XListInputDevices returns a pointer to an array of XDeviceInfo
218           structs and sets ndevices_return to the number of elements in
219           that array. To free the XDeviceInfo array created by
220           XListInputDevices, use XFreeDeviceList.
221
222           On error, XListInputDevices returns NULL and ndevices_return is
223           left unmodified.
224
225
226
227                                  09/15/2021              XLISTINPUTDEVICES(3)
Impressum