man/XIQueryDevice.man

   1 '\" t
   2 .\"     Title: xiquerydevice
   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: 12/22/2011
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "XIQUERYDEVICE" "libmansuffix" "12/22/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 XIQueryDevice, XIFreeDeviceInfo \- get information about devices\&.
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput2\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 XIDeviceInfo* XIQueryDevice( Display *display,
  40                              int deviceid,
  41                              int *ndevices_return);
  42 .fi
  43 .sp
  44 .nf
  45 XIFreeDeviceInfo( XIDeviceInfo *info);
  46 .fi
  47 .sp
  48 .nf
  49 deviceid
  50        Specifies the device to query or XIAllDevices or
  51        XIAllMasterDevices\&.
  52 .fi
  53 .sp
  54 .nf
  55 display
  56        Specifies the connection to the X server\&.
  57 .fi
  58 .sp
  59 .nf
  60 ndevices_return
  61        Returns the number of devices returned\&.
  62 .fi
  63 .sp
  64 .nf
  65 info
  66        A list of device XIDeviceInfo structs to be freed\&.
  67 .fi
  68 .SH "DESCRIPTION"
  69 .sp
  70 .if n \{\
  71 .RS 4
  72 .\}
  73 .nf
  74 The XIQueryDevice returns information about one or more input
  75 devices\&. If the deviceid specifies a device, ndevices_return is
  76 1 and the returned information describes only the requested
  77 device\&. If deviceid is XIAllDevices or XIAllMasterDevices,
  78 ndevices_return is the number of devices or master devices,
  79 respectively, and the returned information represents all
  80 devices or all master devices, respectively\&.
  81 .fi
  82 .if n \{\
  83 .RE
  84 .\}
  85 .sp
  86 .if n \{\
  87 .RS 4
  88 .\}
  89 .nf
  90 To free the XIDeviceInfo array returned by XIQueryDevice, use
  91 XIFreeDeviceInfo\&.
  92 .fi
  93 .if n \{\
  94 .RE
  95 .\}
  96 .sp
  97 .if n \{\
  98 .RS 4
  99 .\}
 100 .nf
 101 For each input device requested, the XIQueryDevice returns an
 102 XIDeviceInfo structure\&. Each structure contains information
 103 about the capabilities of one input device available to the
 104 server\&.
 105 .fi
 106 .if n \{\
 107 .RE
 108 .\}
 109 .sp
 110 .if n \{\
 111 .RS 4
 112 .\}
 113 .nf
 114 typedef struct
 115 {
 116     int                 deviceid;
 117     char                *name;
 118     int                 use;
 119     int                 attachment;
 120     Bool                enabled;
 121     int                 num_classes;
 122     XIAnyClassInfo      **classes;
 123 } XIDeviceInfo;
 124 .fi
 125 .if n \{\
 126 .RE
 127 .\}
 128 .sp
 129 .if n \{\
 130 .RS 4
 131 .\}
 132 .nf
 133 The deviceid is the numeric unique id of the device\&. A deviceid
 134 is unique for the life\-time of a device but a server may re\-use
 135 the id once a device has been removed\&.
 136 .fi
 137 .if n \{\
 138 .RE
 139 .\}
 140 .sp
 141 .if n \{\
 142 .RS 4
 143 .\}
 144 .nf
 145 The name points to a null\-terminated string specifying the
 146 identifier of the device\&.
 147 .fi
 148 .if n \{\
 149 .RE
 150 .\}
 151 .sp
 152 .if n \{\
 153 .RS 4
 154 .\}
 155 .nf
 156 The use and attachment fields specify the type of the device
 157 and the current attachment or pairing\&.
 158 \- If use is XIMasterPointer, the device is a master pointer and
 159   attachment specifies the deviceid of the paired master
 160   keyboard\&.
 161 \- If use is XIMasterKeyboard, the device is a master keyboard,
 162   and the attachment field specifies the paired master pointer\&.
 163 \- If use is XISlavePointer, the device is a slave device and
 164   currently attached to the master pointer specified in
 165   attachement\&.
 166 \- If use is XISlaveKeyboard, the device is a slave device an
 167   currently attached to the master keyboard specified in
 168   attachment\&.
 169 \- If use is XIFloatingSlave, the device is a slave device
 170   currently not attached to any master device\&. The value of the
 171   attachment field for floating slave devices is undefined\&.
 172 .fi
 173 .if n \{\
 174 .RE
 175 .\}
 176 .sp
 177 .if n \{\
 178 .RS 4
 179 .\}
 180 .nf
 181 The enabled field specifies if the device is currently enabled
 182 and can send events\&. Disabled devices will not send events\&.
 183 .fi
 184 .if n \{\
 185 .RE
 186 .\}
 187 .sp
 188 .if n \{\
 189 .RS 4
 190 .\}
 191 .nf
 192 The num_classes field specifies the number of input classes
 193 pointed to by classes\&. The first two fields of all input
 194 classes are identical\&.
 195 .fi
 196 .if n \{\
 197 .RE
 198 .\}
 199 .sp
 200 .if n \{\
 201 .RS 4
 202 .\}
 203 .nf
 204 typedef struct
 205 {
 206     int         type;
 207     int         sourceid;
 208 } XIAnyClassInfo;
 209 .fi
 210 .if n \{\
 211 .RE
 212 .\}
 213 .sp
 214 .if n \{\
 215 .RS 4
 216 .\}
 217 .nf
 218 The type field specifies the type of the input class\&.
 219 Currently, the following types are defined:
 220     XIKeyClass, XIButtonClass, XIValuatorClass, XIScrollClass,
 221     XITouchClass
 222 .fi
 223 .if n \{\
 224 .RE
 225 .\}
 226 .sp
 227 .if n \{\
 228 .RS 4
 229 .\}
 230 .nf
 231 In the future, additional types may be added\&. Clients are
 232 required to ignore unknown input classes\&.
 233 .fi
 234 .if n \{\
 235 .RE
 236 .\}
 237 .sp
 238 .if n \{\
 239 .RS 4
 240 .\}
 241 .nf
 242 The sourceid is the deviceid this class originated from\&. For
 243 master devices, the sourceid is typically the id of the slave
 244 device currently sending events\&. For slave devices, the
 245 sourceid is typically the device\*(Aqs id\&.
 246 .fi
 247 .if n \{\
 248 .RE
 249 .\}
 250 .sp
 251 .if n \{\
 252 .RS 4
 253 .\}
 254 .nf
 255 A device may have zero or one XIButtonClass, denoting the
 256 device\*(Aqs capability to send button events\&.
 257 .fi
 258 .if n \{\
 259 .RE
 260 .\}
 261 .sp
 262 .if n \{\
 263 .RS 4
 264 .\}
 265 .nf
 266 typedef struct {
 267     int           mask_len;
 268     unsigned char *mask;
 269 } XIButtonState;
 270 .fi
 271 .if n \{\
 272 .RE
 273 .\}
 274 .sp
 275 .if n \{\
 276 .RS 4
 277 .\}
 278 .nf
 279 typedef struct
 280 {
 281     int         type;
 282     int         sourceid;
 283     int         num_buttons;
 284     Atom        *labels;
 285     XIButtonState state;
 286 } XIButtonClassInfo;
 287 .fi
 288 .if n \{\
 289 .RE
 290 .\}
 291 .sp
 292 .if n \{\
 293 .RS 4
 294 .\}
 295 .nf
 296 The num_buttons field specifies the number of buttons available
 297 on this device\&. A device that has an XIButtonClass must have at
 298 least one button\&.
 299 .fi
 300 .if n \{\
 301 .RE
 302 .\}
 303 .sp
 304 .if n \{\
 305 .RS 4
 306 .\}
 307 .nf
 308 labels is a list of num_buttons Atoms specifying the button
 309 labels for this device\&. If the label is not None, then the
 310 label specifies the type of button in physical device order
 311 (i\&.e\&. as the buttons are numbered on the physical input
 312 device)\&.
 313 .fi
 314 .if n \{\
 315 .RE
 316 .\}
 317 .sp
 318 .if n \{\
 319 .RS 4
 320 .\}
 321 .nf
 322 The state is the current button state as seen by clients (i\&.e\&.
 323 after button mapping is applied)\&. The mask_len field specifies
 324 the length of mask in bytes\&. For each button on the device, the
 325 respective bit in mask is set if the button is currently
 326 logically down\&.
 327 .fi
 328 .if n \{\
 329 .RE
 330 .\}
 331 .sp
 332 .if n \{\
 333 .RS 4
 334 .\}
 335 .nf
 336 A device may have zero or one XIKeyClass, denoting the device\*(Aqs
 337 capability to send key events\&.
 338 .fi
 339 .if n \{\
 340 .RE
 341 .\}
 342 .sp
 343 .if n \{\
 344 .RS 4
 345 .\}
 346 .nf
 347 typedef struct
 348 {
 349     int         type;
 350     int         sourceid;
 351     int         num_keycodes;
 352     int         *keycodes;
 353 } XIKeyClassInfo;
 354 .fi
 355 .if n \{\
 356 .RE
 357 .\}
 358 .sp
 359 .if n \{\
 360 .RS 4
 361 .\}
 362 .nf
 363 The num_keycodes field specifies the number of keycodes
 364 available on this device\&. A device that has an XIKeyClass must
 365 have at least one keycode\&.
 366 .fi
 367 .if n \{\
 368 .RE
 369 .\}
 370 .sp
 371 .if n \{\
 372 .RS 4
 373 .\}
 374 .nf
 375 keycodes is a list of num_keycodes keycodes the device may
 376 send\&.
 377 .fi
 378 .if n \{\
 379 .RE
 380 .\}
 381 .sp
 382 .if n \{\
 383 .RS 4
 384 .\}
 385 .nf
 386 A device may have zero or more XIValuatorClass, denoting the
 387 device\*(Aqs capability to send coordinates\&.
 388 .fi
 389 .if n \{\
 390 .RE
 391 .\}
 392 .sp
 393 .if n \{\
 394 .RS 4
 395 .\}
 396 .nf
 397 typedef struct
 398 {
 399     int         type;
 400     int         sourceid;
 401     int         number;
 402     Atom        label;
 403     double      min;
 404     double      max;
 405     double      value;
 406     int         resolution;
 407     int         mode;
 408 } XIValuatorClassInfo;
 409 .fi
 410 .if n \{\
 411 .RE
 412 .\}
 413 .sp
 414 .if n \{\
 415 .RS 4
 416 .\}
 417 .nf
 418 The number field specifies the number of the axis on the
 419 physical device\&.
 420 .fi
 421 .if n \{\
 422 .RE
 423 .\}
 424 .sp
 425 .if n \{\
 426 .RS 4
 427 .\}
 428 .nf
 429 If the label field is not None, the value of label is an Atom
 430 describing the axis\&.
 431 .fi
 432 .if n \{\
 433 .RE
 434 .\}
 435 .sp
 436 .if n \{\
 437 .RS 4
 438 .\}
 439 .nf
 440 min and max are the minimum and maximum values allowed on this
 441 axis\&. If both are zero, no minumum or maximum values are set on
 442 this device\&. value is the current value of this axis\&.
 443 .fi
 444 .if n \{\
 445 .RE
 446 .\}
 447 .sp
 448 .if n \{\
 449 .RS 4
 450 .\}
 451 .nf
 452 The resolution field specifies the resolution of the device in
 453 units/m\&.
 454 .fi
 455 .if n \{\
 456 .RE
 457 .\}
 458 .sp
 459 .if n \{\
 460 .RS 4
 461 .\}
 462 .nf
 463 The mode specifies the mode of this axis\&. If the mode is
 464 XIModeAbsolute this axis sends absolute coordinates\&. If the
 465 mode is XIModeRelative, this device sends relative coordinates\&.
 466 .fi
 467 .if n \{\
 468 .RE
 469 .\}
 470 .sp
 471 .if n \{\
 472 .RS 4
 473 .\}
 474 .nf
 475 typedef struct
 476 {
 477     int         type;
 478     int         sourceid;
 479     int         number;
 480     int         scroll_type;
 481     double      increment;
 482     int         flags;
 483 } XIScrollClassInfo;
 484 .fi
 485 .if n \{\
 486 .RE
 487 .\}
 488 .sp
 489 .if n \{\
 490 .RS 4
 491 .\}
 492 .nf
 493 This class describes scrolling capability on a valuator\&. For
 494 each XIScrollClassInfo, an XIValuatorClassInfo with the same
 495 number is present on the device\&.
 496 .fi
 497 .if n \{\
 498 .RE
 499 .\}
 500 .sp
 501 .if n \{\
 502 .RS 4
 503 .\}
 504 .nf
 505 The number field specifies the valuator number on the physical
 506 device that this scroll information applies to\&. See the
 507 respective XIValuatorClassInfo for detailed information on this
 508 valuator\&.
 509 .fi
 510 .if n \{\
 511 .RE
 512 .\}
 513 .sp
 514 .if n \{\
 515 .RS 4
 516 .\}
 517 .nf
 518 The scroll_type field specifies the type of scrolling, either
 519 XIScrollTypeVertical or XIScrollTypeHorizontal\&.
 520 .fi
 521 .if n \{\
 522 .RE
 523 .\}
 524 .sp
 525 .if n \{\
 526 .RS 4
 527 .\}
 528 .nf
 529 The increment specifies the value change considered one unit of
 530 scrolling down\&.
 531 .fi
 532 .if n \{\
 533 .RE
 534 .\}
 535 .sp
 536 .if n \{\
 537 .RS 4
 538 .\}
 539 .nf
 540 The flags field specifies flags that apply to this scrolling
 541 information:
 542 .fi
 543 .if n \{\
 544 .RE
 545 .\}
 546 .sp
 547 .if n \{\
 548 .RS 4
 549 .\}
 550 .nf
 551 If XIScrollFlagNoEmulation is set, the server will not
 552 emulate legacy button events for valuator changes on this
 553 valuator\&.
 554 .fi
 555 .if n \{\
 556 .RE
 557 .\}
 558 .sp
 559 .if n \{\
 560 .RS 4
 561 .\}
 562 .nf
 563 If XIScrollFlagPreferred is set, this axis is the
 564 preferred axis for this scroll type and will be used for
 565 the emulation of XI_Motion events when the driver submits
 566 legacy scroll button events\&.
 567 .fi
 568 .if n \{\
 569 .RE
 570 .\}
 571 .sp
 572 .if n \{\
 573 .RS 4
 574 .\}
 575 .nf
 576 typedef struct
 577 {
 578     int         type;
 579     int         sourceid;
 580     int         mode;
 581     int         num_touches;
 582 } XITouchClassInfo;
 583 .fi
 584 .if n \{\
 585 .RE
 586 .\}
 587 .sp
 588 .if n \{\
 589 .RS 4
 590 .\}
 591 .nf
 592 A device may have zero or one XITouchClassInfo, denoting
 593 multi\-touch capability on the device\&. A device with a XITouchClassInfo
 594 may send TouchBegin, TouchUpdate, TouchEnd and TouchOwnership events\&.
 595 .fi
 596 .if n \{\
 597 .RE
 598 .\}
 599 .sp
 600 .if n \{\
 601 .RS 4
 602 .\}
 603 .nf
 604 The mode field is either XIDirectTouch for direct\-input touch devices
 605 such as touchscreens or XIDependentTouch for indirect input devices such
 606 as touchpads\&. For XIDirectTouch devices, touch events are sent to window
 607 at the position the touch occured\&. For XIDependentTouch devices, touch
 608 events are sent to the window at the position of the device\*(Aqs sprite\&.
 609 .fi
 610 .if n \{\
 611 .RE
 612 .\}
 613 .sp
 614 .if n \{\
 615 .RS 4
 616 .\}
 617 .nf
 618 The num_touches field defines the maximum number of simultaneous touches
 619 the device supports\&. A num_touches of 0 means the maximum number of
 620 simultaneous touches is undefined or unspecified\&. This field should be
 621 used as a guide only, devices will lie about their capabilities\&.
 622 .fi
 623 .if n \{\
 624 .RE
 625 .\}
 626 .sp
 627 .if n \{\
 628 .RS 4
 629 .\}
 630 .nf
 631 A device with an XITouchClassInfo may still send pointer events\&. The
 632 valuators must be defined with the respective XIValuatorClass
 633 classes\&. A valuator may send both pointer and touch\-events\&.
 634 .fi
 635 .if n \{\
 636 .RE
 637 .\}
 638 .sp
 639 .if n \{\
 640 .RS 4
 641 .\}
 642 .nf
 643 XIQueryDevice can generate a BadDevice error\&.
 644 .fi
 645 .if n \{\
 646 .RE
 647 .\}
 648 .sp
 649 .if n \{\
 650 .RS 4
 651 .\}
 652 .nf
 653 XIFreeDeviceInfo frees the information returned by
 654 XIQueryDevice\&.
 655 .fi
 656 .if n \{\
 657 .RE
 658 .\}
 659 .SH "DIAGNOSTICS"
 660 .sp
 661 .if n \{\
 662 .RS 4
 663 .\}
 664 .nf
 665 BadDevice
 666        An invalid device was specified\&. The device does not
 667        exist or is not a pointer device\&.
 668 .fi
 669 .if n \{\
 670 .RE
 671 .\}