1XIQUERYDEVICE(3) XIQUERYDEVICE(3)
2
6 XIQueryDevice, XIFreeDeviceInfo - get information about devices.
7
9 #include <X11/extensions/XInput2.h>
10 XIDeviceInfo* XIQueryDevice( Display *display,
12 int deviceid,
13 int *ndevices_return);
14 XIFreeDeviceInfo( XIDeviceInfo *info);
16 deviceid
18 Specifies the device to query or XIAllDevices or
19 XIAllMasterDevices.
20 display
22 Specifies the connection to the X server.
23 ndevices_return
25 Returns the number of devices returned.
26 info
28 A list of device XIDeviceInfo structs to be freed.
29
31 The XIQueryDevice returns information about one or more input
32 devices. If the deviceid specifies a device, ndevices_return is
33 1 and the returned information describes only the requested
34 device. If deviceid is XIAllDevices or XIAllMasterDevices,
35 ndevices_return is the number of devices or master devices,
36 respectively, and the returned information represents all
37 devices or all master devices, respectively.
38 To free the XIDeviceInfo array returned by XIQueryDevice, use
40 XIFreeDeviceInfo.
41 For each input device requested, the XIQueryDevice returns an
43 XIDeviceInfo structure. Each structure contains information
44 about the capabilities of one input device available to the
45 server.
46 typedef struct
48 {
49 int deviceid;
50 char *name;
51 int use;
52 int attachment;
53 Bool enabled;
54 int num_classes;
55 XIAnyClassInfo **classes;
56 } XIDeviceInfo;
57 The deviceid is the numeric unique id of the device. A deviceid
59 is unique for the life-time of a device but a server may re-use
60 the id once a device has been removed.
61 The name points to a null-terminated string specifying the
63 identifier of the device.
64 The use and attachment fields specify the type of the device
66 and the current attachment or pairing.
67 - If use is XIMasterPointer, the device is a master pointer and
68 attachment specifies the deviceid of the paired master
69 keyboard.
70 - If use is XIMasterKeyboard, the device is a master keyboard,
71 and the attachment field specifies the paired master pointer.
72 - If use is XISlavePointer, the device is a slave device and
73 currently attached to the master pointer specified in
74 attachment.
75 - If use is XISlaveKeyboard, the device is a slave device an
76 currently attached to the master keyboard specified in
77 attachment.
78 - If use is XIFloatingSlave, the device is a slave device
79 currently not attached to any master device. The value of the
80 attachment field for floating slave devices is undefined.
81 The enabled field specifies if the device is currently enabled
83 and can send events. Disabled devices will not send events.
84 The num_classes field specifies the number of input classes
86 pointed to by classes. The first two fields of all input
87 classes are identical.
88 typedef struct
90 {
91 int type;
92 int sourceid;
93 } XIAnyClassInfo;
94 The type field specifies the type of the input class.
96 Currently, the following types are defined:
97 XIKeyClass, XIButtonClass, XIValuatorClass, XIScrollClass,
98 XITouchClass, XIGestureClass.
99 In the future, additional types may be added. Clients are
101 required to ignore unknown input classes.
102 The sourceid is the deviceid this class originated from. For
104 master devices, the sourceid is typically the id of the slave
105 device currently sending events. For slave devices, the
106 sourceid is typically the device's id.
107 A device may have zero or one XIButtonClass, denoting the
109 device's capability to send button events.
110 typedef struct {
112 int mask_len;
113 unsigned char *mask;
114 } XIButtonState;
115 typedef struct
117 {
118 int type;
119 int sourceid;
120 int num_buttons;
121 Atom *labels;
122 XIButtonState state;
123 } XIButtonClassInfo;
124 The num_buttons field specifies the number of buttons available
126 on this device. A device that has an XIButtonClass must have at
127 least one button.
128 labels is a list of num_buttons Atoms specifying the button
130 labels for this device. If the label is not None, then the
131 label specifies the type of button in physical device order
132 (i.e. as the buttons are numbered on the physical input
133 device).
134 The state is the current button state as seen by clients (i.e.
136 after button mapping is applied). The mask_len field specifies
137 the length of mask in bytes. For each button on the device, the
138 respective bit in mask is set if the button is currently
139 logically down.
140 A device may have zero or one XIKeyClass, denoting the device's
142 capability to send key events.
143 typedef struct
145 {
146 int type;
147 int sourceid;
148 int num_keycodes;
149 int *keycodes;
150 } XIKeyClassInfo;
151 The num_keycodes field specifies the number of keycodes
153 available on this device. A device that has an XIKeyClass must
154 have at least one keycode.
155 keycodes is a list of num_keycodes keycodes the device may
157 send.
158 A device may have zero or more XIValuatorClass, denoting the
160 device's capability to send coordinates.
161 typedef struct
163 {
164 int type;
165 int sourceid;
166 int number;
167 Atom label;
168 double min;
169 double max;
170 double value;
171 int resolution;
172 int mode;
173 } XIValuatorClassInfo;
174 The number field specifies the number of the axis on the
176 physical device.
177 If the label field is not None, the value of label is an Atom
179 describing the axis.
180 min and max are the minimum and maximum values allowed on this
182 axis. If both are zero, no minimum or maximum values are set on
183 this device. value is the current value of this axis.
184 The resolution field specifies the resolution of the device in
186 units/m.
187 The mode specifies the mode of this axis. If the mode is
189 XIModeAbsolute this axis sends absolute coordinates. If the
190 mode is XIModeRelative, this device sends relative coordinates.
191 typedef struct
193 {
194 int type;
195 int sourceid;
196 int number;
197 int scroll_type;
198 double increment;
199 int flags;
200 } XIScrollClassInfo;
201 This class describes scrolling capability on a valuator. For
203 each XIScrollClassInfo, an XIValuatorClassInfo with the same
204 number is present on the device.
205 The number field specifies the valuator number on the physical
207 device that this scroll information applies to. See the
208 respective XIValuatorClassInfo for detailed information on this
209 valuator.
210 The scroll_type field specifies the type of scrolling, either
212 XIScrollTypeVertical or XIScrollTypeHorizontal.
213 The increment specifies the value change considered one unit of
215 scrolling down.
216 The flags field specifies flags that apply to this scrolling
218 information:
219 If XIScrollFlagNoEmulation is set, the server will not
221 emulate legacy button events for valuator changes on this
222 valuator.
223 If XIScrollFlagPreferred is set, this axis is the
225 preferred axis for this scroll type and will be used for
226 the emulation of XI_Motion events when the driver submits
227 legacy scroll button events.
228 typedef struct
230 {
231 int type;
232 int sourceid;
233 int mode;
234 int num_touches;
235 } XITouchClassInfo;
236 A device may have zero or one XITouchClassInfo, denoting
238 multi-touch capability on the device. A device with a XITouchClassInfo
239 may send TouchBegin, TouchUpdate, TouchEnd and TouchOwnership events.
240 The mode field is either XIDirectTouch for direct-input touch devices
242 such as touchscreens or XIDependentTouch for indirect input devices such
243 as touchpads. For XIDirectTouch devices, touch events are sent to window
244 at the position the touch occurred. For XIDependentTouch devices, touch
245 events are sent to the window at the position of the device's sprite.
246 The num_touches field defines the maximum number of simultaneous touches
248 the device supports. A num_touches of 0 means the maximum number of
249 simultaneous touches is undefined or unspecified. This field should be
250 used as a guide only, devices will lie about their capabilities.
251 A device with an XITouchClassInfo may still send pointer events. The
253 valuators must be defined with the respective XIValuatorClass
254 classes. A valuator may send both pointer and touch-events.
255 typedef struct
257 {
258 int type;
259 int sourceid;
260 int num_touches;
261 } XIGestureClassInfo;
262 A device may have zero or one XIGestureClassInfo, denoting
264 touchpad gesture capability on the device. A device with a XIGestureClassInfo
265 may send GestureSwipeBegin, GestureSwipeUpdate, GestureSwipeEnd,
266 GesturePinchBegin, GesturePinchUpdate, GesturePinchEnd.
267 The num_touches field defines the maximum number of simultaneous touches
269 the device supports. A num_touches of 0 means the maximum number of
270 simultaneous touches is undefined or unspecified. This field should be
271 used as a guide only, devices will lie about their capabilities.
272 XIQueryDevice can generate a BadDevice error.
274 XIFreeDeviceInfo frees the information returned by
276 XIQueryDevice.
277
279 BadDevice
280 An invalid device was specified. The device does not
281 exist or is not a pointer device.
282 05/04/2023 XIQUERYDEVICE(3)