man/XListInputDevices.man

   1 '\" t
   2 .\"     Title: xlistinputdevices
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 09/23/2011
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "XLISTINPUTDEVICES" "libmansuffix" "09/23/2011" "[FIXME: source]" "[FIXME: manual]"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 XListInputDevices, XFreeDeviceList \- list available input devices
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 XDeviceInfo *XListInputDevices( Display *display,
  40                                 int *ndevices_return);
  41 .fi
  42 .sp
  43 .nf
  44 int XFreeDeviceList( XDeviceInfo *list);
  45 .fi
  46 .sp
  47 .nf
  48 display
  49        Specifies the connection to the X server\&.
  50 .fi
  51 .sp
  52 .nf
  53 ndevices_return
  54        Specifies a pointer to a variable where the number of
  55        available devices canbe returned\&.
  56 .fi
  57 .sp
  58 .nf
  59 list
  60        Specifies the list of devices to free\&. The
  61        XFreeDeviceList functionfrees the list of available
  62        extension input devices\&.
  63 .fi
  64 .SH "DESCRIPTION"
  65 .sp
  66 .if n \{\
  67 .RS 4
  68 .\}
  69 .nf
  70 The XListInputDevices request lists the available input
  71 devices\&. This list includes the core keyboard and any physical
  72 input device currently accessible through the X server, and any
  73 input devices that are not currently accessible through the X
  74 server but could be accessed if requested\&.
  75 .fi
  76 .if n \{\
  77 .RE
  78 .\}
  79 .sp
  80 .if n \{\
  81 .RS 4
  82 .\}
  83 .nf
  84 A master pointer is a virtual pointer device that does not
  85 represent a physical device\&. It is visually represented through
  86 a cursor\&. A master keyboard is a virtual keyboard device that
  87 does not represent a physical device\&. It is virtually
  88 representd through a keyboard focus\&. A master pointer and a
  89 master keyboard are always paired (i\&.e\&. if shift is pressed on
  90 the master keyboard, a pointer click would be a shift\-click)\&.
  91 Multiple master pointer/keyboard pairs can exist\&.
  92 .fi
  93 .if n \{\
  94 .RE
  95 .\}
  96 .sp
  97 .if n \{\
  98 .RS 4
  99 .\}
 100 .nf
 101 X servers supporting the X Input Extension version 2,
 102 XListInputDevices only returns the first master pointer, the
 103 first master keyboard and all slave devices\&. Additional master
 104 devices are not listed\&.
 105 .fi
 106 .if n \{\
 107 .RE
 108 .\}
 109 .sp
 110 .if n \{\
 111 .RS 4
 112 .\}
 113 .nf
 114 Physical devices (so\-called slave devices) are attached to
 115 either a master pointer or a master keyboard, depending on
 116 their capabilities\&. If a slave device generates an event, the
 117 event is also generated by the respective master device\&.
 118 Multiple slave devices can be attached to a single master
 119 device\&.
 120 .fi
 121 .if n \{\
 122 .RE
 123 .\}
 124 .sp
 125 .if n \{\
 126 .RS 4
 127 .\}
 128 .nf
 129 Some server implementations may make all physical input devices
 130 available at the time the server is initialized\&. Others may
 131 wait until requested by a client to access an input device\&. In
 132 the latter case, it is possible that an input device will be
 133 listed as available at one time but not at another\&.
 134 .fi
 135 .if n \{\
 136 .RE
 137 .\}
 138 .sp
 139 .if n \{\
 140 .RS 4
 141 .\}
 142 .nf
 143 For each input device available to the server, the
 144 XListInputDevices request returns an XDeviceInfo structure\&.
 145 That structure contains a pointer to a list of structures, each
 146 of which contains information about one class of input
 147 supported by the device\&. The XDeviceInfo structure is defined
 148 as follows:
 149              typedef struct _XDeviceInfo {
 150              XID     id;
 151              Atom    type;
 152              char    *name;
 153              int         num_classes;
 154              int         use;
 155              XAnyClassPtr inputclassinfo;
 156              } XDeviceInfo;
 157 .fi
 158 .if n \{\
 159 .RE
 160 .\}
 161 .sp
 162 .if n \{\
 163 .RS 4
 164 .\}
 165 .nf
 166 The id is a number in the range 0\-128 that uniquely identifies
 167 the device\&. It is assigned to the device when it is initialized
 168 by the server\&.
 169 .fi
 170 .if n \{\
 171 .RE
 172 .\}
 173 .sp
 174 .if n \{\
 175 .RS 4
 176 .\}
 177 .nf
 178 The type field is of type Atom and indicates the nature of the
 179 device\&. The type will correspond to one of the following strings
 180 (defined in the header file XI\&.h):
 181 .fi
 182 .if n \{\
 183 .RE
 184 .\}
 185 .sp
 186 .if n \{\
 187 .RS 4
 188 .\}
 189 .nf
 190 XI_MOUSE XI_TABLET XI_KEYBOARD XI_TOUCHSCREEN XI_TOUCHPAD
 191 XI_BUTTONBOX XI_BARCODE XI_TRACKBALL XI_QUADRATURE XI_ID_MODULE
 192 XI_ONE_KNOB XI_NINE_KNOB XI_KNOB_BOX XI_SPACEBALL XI_DATAGLOVE
 193 XI_EYETRACKER XI_CURSORKEYS XI_FOOTMOUSE XI_JOYSTICK
 194 .fi
 195 .if n \{\
 196 .RE
 197 .\}
 198 .sp
 199 .if n \{\
 200 .RS 4
 201 .\}
 202 .nf
 203 These strings may be used in an XInternAtom request to return
 204 an atom that can be compared with the type field of the
 205 XDeviceInfo structure\&.
 206 .fi
 207 .if n \{\
 208 .RE
 209 .\}
 210 .sp
 211 .if n \{\
 212 .RS 4
 213 .\}
 214 .nf
 215 The name field contains a pointer to a null\-terminated string
 216 that serves as identifier of the device\&. This identifier may be
 217 user\-configured or automatically assigned by the server\&.
 218 .fi
 219 .if n \{\
 220 .RE
 221 .\}
 222 .sp
 223 .if n \{\
 224 .RS 4
 225 .\}
 226 .nf
 227 The num_classes field is a number in the range 0\-255 that
 228 specifies the number of input classes supported by the device
 229 for which information is returned by ListInputDevices\&. Some
 230 input classes, such as class Focus and class Proximity do not
 231 have any information to be returned by ListInputDevices\&.
 232 .fi
 233 .if n \{\
 234 .RE
 235 .\}
 236 .sp
 237 .if n \{\
 238 .RS 4
 239 .\}
 240 .nf
 241 All devices provide an AttachClass\&. This class specifies the
 242 master device a given slave device is attached to\&. For master
 243 devices, the class specifies the respective paired master
 244 device\&.
 245 .fi
 246 .if n \{\
 247 .RE
 248 .\}
 249 .sp
 250 .if n \{\
 251 .RS 4
 252 .\}
 253 .nf
 254 The use field specifies how the device is currently being used\&.
 255 If the value is IsXKeyboard, the device is a master keyboard\&.
 256 If the value is IsXPointer, the device is a master pointer\&. If
 257 the value is IsXExtensionPointer, the device is a slave
 258 pointer\&. If the value is IsXExtensionKeyboard, the device is a
 259 slave keyboard\&. If the value is IsXExtensionDevice, the device
 260 is available for use as an extension device\&.
 261 .fi
 262 .if n \{\
 263 .RE
 264 .\}
 265 .sp
 266 .if n \{\
 267 .RS 4
 268 .\}
 269 .nf
 270 The inputclassinfo field contains a pointer to the first
 271 input\-class specific data\&. The first two fields are common to
 272 all classes\&.
 273 .fi
 274 .if n \{\
 275 .RE
 276 .\}
 277 .sp
 278 .if n \{\
 279 .RS 4
 280 .\}
 281 .nf
 282 The class field is a number in the range 0\-255\&. It uniquely
 283 identifies the class of input for which information is
 284 returned\&. Currently defined classes are KeyClass, ButtonClass,
 285 and ValuatorClass\&.
 286 .fi
 287 .if n \{\
 288 .RE
 289 .\}
 290 .sp
 291 .if n \{\
 292 .RS 4
 293 .\}
 294 .nf
 295 The length field is a number in the range 0\- 255\&. It specifies
 296 the number of bytes of data that are contained in this input
 297 class\&. The length includes the class and length fields\&.
 298 .fi
 299 .if n \{\
 300 .RE
 301 .\}
 302 .sp
 303 .if n \{\
 304 .RS 4
 305 .\}
 306 .nf
 307 The XKeyInfo structure describes the characteristics of the
 308 keys on the device\&. It is defined as follows:
 309 .fi
 310 .if n \{\
 311 .RE
 312 .\}
 313 .sp
 314 .if n \{\
 315 .RS 4
 316 .\}
 317 .nf
 318 typedef struct _XKeyInfo {
 319 XID class;
 320 int length;
 321 unsigned short min_keycode;
 322 unsigned short max_keycode;
 323 unsigned short num_keys;
 324 } XKeyInfo;
 325 .fi
 326 .if n \{\
 327 .RE
 328 .\}
 329 .sp
 330 .if n \{\
 331 .RS 4
 332 .\}
 333 .nf
 334 min_keycode is of type KEYCODE\&. It specifies the minimum
 335 keycode that the device will report\&. The minimum keycode will
 336 not be smaller than 8\&.
 337 .fi
 338 .if n \{\
 339 .RE
 340 .\}
 341 .sp
 342 .if n \{\
 343 .RS 4
 344 .\}
 345 .nf
 346 max_keycode is of type KEYCODE\&. It specifies the maximum
 347 keycode that the device will report\&. The maximum keycode will
 348 not be larger than 255\&.
 349 .fi
 350 .if n \{\
 351 .RE
 352 .\}
 353 .sp
 354 .if n \{\
 355 .RS 4
 356 .\}
 357 .nf
 358 num_keys specifies the number of keys that the device has\&.
 359 .fi
 360 .if n \{\
 361 .RE
 362 .\}
 363 .sp
 364 .if n \{\
 365 .RS 4
 366 .\}
 367 .nf
 368 The XButtonInfo structure defines the characteristics of the
 369 buttons on the device\&. It is defined as follows:
 370 .fi
 371 .if n \{\
 372 .RE
 373 .\}
 374 .sp
 375 .if n \{\
 376 .RS 4
 377 .\}
 378 .nf
 379 typedef struct _XButtonInfo {
 380 XID class;
 381 int length;
 382 short num_buttons;
 383 } XButtonInfo;
 384 .fi
 385 .if n \{\
 386 .RE
 387 .\}
 388 .sp
 389 .if n \{\
 390 .RS 4
 391 .\}
 392 .nf
 393 num_buttons specifies the number of buttons that the device
 394 has\&.
 395 .fi
 396 .if n \{\
 397 .RE
 398 .\}
 399 .sp
 400 .if n \{\
 401 .RS 4
 402 .\}
 403 .nf
 404 The XValuatorInfo structure defines the characteristics of the
 405 valuators on the device\&. It is defined as follows:
 406 .fi
 407 .if n \{\
 408 .RE
 409 .\}
 410 .sp
 411 .if n \{\
 412 .RS 4
 413 .\}
 414 .nf
 415 typedef struct  _XValuatorInfo {
 416 XID class;
 417 int length;
 418 unsigned char num_axes;
 419 unsigned char mode;
 420 unsigned long motion_buffer;
 421 XAxisInfoPtr axes;
 422 } XValuatorInfo;
 423 .fi
 424 .if n \{\
 425 .RE
 426 .\}
 427 .sp
 428 .if n \{\
 429 .RS 4
 430 .\}
 431 .nf
 432 num_axes contains the number of axes the device supports\&.
 433 .fi
 434 .if n \{\
 435 .RE
 436 .\}
 437 .sp
 438 .if n \{\
 439 .RS 4
 440 .\}
 441 .nf
 442 mode is a constant that has one of the following values:
 443 Absolute or Relative\&. Some devices allow the mode to be changed
 444 dynamically via the SetDeviceMode request\&.
 445 .fi
 446 .if n \{\
 447 .RE
 448 .\}
 449 .sp
 450 .if n \{\
 451 .RS 4
 452 .\}
 453 .nf
 454 motion_buffer_size is a cardinal number that specifies the
 455 number of elements that can be contained in the motion history
 456 buffer for the device\&.
 457 .fi
 458 .if n \{\
 459 .RE
 460 .\}
 461 .sp
 462 .if n \{\
 463 .RS 4
 464 .\}
 465 .nf
 466 The axes field contains a pointer to an XAxisInfo structure\&.
 467 .fi
 468 .if n \{\
 469 .RE
 470 .\}
 471 .sp
 472 .if n \{\
 473 .RS 4
 474 .\}
 475 .nf
 476 The XAxisInfo structure is defined as follows:
 477 .fi
 478 .if n \{\
 479 .RE
 480 .\}
 481 .sp
 482 .if n \{\
 483 .RS 4
 484 .\}
 485 .nf
 486 typedef struct _XAxisInfo {
 487 int resolution;
 488 int min_value;
 489 int max_value;
 490 } XAxisInfo;
 491 .fi
 492 .if n \{\
 493 .RE
 494 .\}
 495 .sp
 496 .if n \{\
 497 .RS 4
 498 .\}
 499 .nf
 500 The resolution contains a number in counts/meter\&.
 501 .fi
 502 .if n \{\
 503 .RE
 504 .\}
 505 .sp
 506 .if n \{\
 507 .RS 4
 508 .\}
 509 .nf
 510 The min_val field contains a number that specifies the minimum
 511 value the device reports for this axis\&. For devices whose mode
 512 is Relative, the min_val field will contain 0\&.
 513 .fi
 514 .if n \{\
 515 .RE
 516 .\}
 517 .sp
 518 .if n \{\
 519 .RS 4
 520 .\}
 521 .nf
 522 The max_val field contains a number that specifies the maximum
 523 value the device reports for this axis\&. For devices whose mode
 524 is Relative, the max_val field will contain 0\&.
 525 .fi
 526 .if n \{\
 527 .RE
 528 .\}
 529 .sp
 530 .if n \{\
 531 .RS 4
 532 .\}
 533 .nf
 534 The XAttachInfo structure is defined as follows:
 535              typedef struct _XAttachInfo {
 536              int     attached;
 537              } XAttachInfo;
 538 .fi
 539 .if n \{\
 540 .RE
 541 .\}
 542 .sp
 543 .if n \{\
 544 .RS 4
 545 .\}
 546 .nf
 547 If the device is a slave device, attached specifies the device
 548 ID of the master device this device is attached to\&. If the
 549 device is not attached to a master device, attached is
 550 Floating\&. If the device is a master device, attached specifies
 551 the device ID of the master device this device is paired with\&.
 552 .fi
 553 .if n \{\
 554 .RE
 555 .\}
 556 .sp
 557 .if n \{\
 558 .RS 4
 559 .\}
 560 .nf
 561 To free the XDeviceInfo array created by XListInputDevices, use
 562 XFreeDeviceList\&.
 563 .fi
 564 .if n \{\
 565 .RE
 566 .\}