specs/XKB/ch21.xml

   1 <chapter id='Attaching_Xkb_Actions_to_X_Input_Extension_Devices'>
   2 <title>Attaching Xkb Actions to X Input Extension Devices</title>
   3
   4 <para>
   5 The X input extension allows an X server to support multiple keyboards, as well
   6 as other input devices, in addition to the core X keyboard and pointer. The
   7 input extension categorizes devices by grouping them into classes. Keyboards
   8 and other input devices with keys are classified as KeyClass devices by the
   9 input extension. Other types of devices supported by the input extension
  10 include, but are not limited to: mice, tablets, touchscreens, barcode readers,
  11 button boxes, trackballs, identifier devices, data gloves, and eye trackers.
  12 Xkb provides additional control over all X input extension devices, whether
  13 they are <emphasis>KeyClass</emphasis>
  14  devices or not, as well as the core keyboard and pointer.
  15 </para>
  16
  17
  18 <para>
  19 If an X server implements support for both the input extension and Xkb, the
  20 server implementor determines whether interaction between Xkb and the input
  21 extension is allowed. Implementors are free to restrict the effects of Xkb to
  22 only the core X keyboard device or allow interaction between Xkb and the input
  23 extension.
  24 </para>
  25
  26
  27 <para>
  28 Several types of interaction between Xkb and the input extension are defined by
  29 Xkb. Some or all may be allowed by the X server implementation.
  30 </para>
  31
  32
  33 <para>
  34 Regardless of whether the server allows interaction between Xkb and the input
  35 extension, the following access is provided:
  36 </para>
  37
  38 <itemizedlist>
  39 <listitem>
  40   <para>
  41 Xkb functionality for the core X keyboard device and its mapping is accessed
  42 via the functions described in the other chapters of this specification.
  43   </para>
  44 </listitem>
  45 <listitem>
  46   <para>
  47 Xkb functionality for the core X pointer device is accessed via the
  48 XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter.
  49   </para>
  50 </listitem>
  51 </itemizedlist>
  52
  53 <para>
  54 If all types of interaction are allowed between Xkb and the input extension,
  55 the following additional access is provided:
  56 </para>
  57
  58 <itemizedlist>
  59 <listitem>
  60   <para>
  61 If allowed, Xkb functionality for additional <emphasis>
  62 KeyClass</emphasis>
  63  devices supported by the input extension is accessed via those same functions.
  64   </para>
  65 </listitem>
  66 <listitem>
  67   <para>
  68 If allowed, Xkb functionality for non-<emphasis>
  69 KeyClass</emphasis>
  70  devices supported by the input extension is also accessed via the
  71 XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter.
  72   </para>
  73 </listitem>
  74 </itemizedlist>
  75
  76 <para>
  77 Each device has an X Input Extension device ID. Each device may have several
  78 classes of feedback. For example, there are two types of feedbacks that can
  79 generate bells: bell feedback and keyboard feedback (<emphasis>
  80 BellFeedbackClass</emphasis>
  81  and <emphasis>
  82 KbdFeedbackClass</emphasis>
  83 ). A device can have more than one feedback of each type; the feedback ID
  84 identifies the particular feedback within its class.
  85 </para>
  86
  87
  88 <para>
  89 A keyboard feedback has:
  90 </para>
  91
  92 <itemizedlist>
  93 <listitem>
  94   <para>
  95 Auto-repeat status (global and per key)
  96   </para>
  97 </listitem>
  98 <listitem>
  99   <para>
 100 32 LEDs
 101   </para>
 102 </listitem>
 103 <listitem>
 104   <para>
 105 A bell
 106   </para>
 107 </listitem>
 108 </itemizedlist>
 109
 110 <para>
 111 An indicator feedback has:
 112 </para>
 113
 114 <itemizedlist>
 115 <listitem>
 116   <para>
 117 Up to 32 LEDs
 118   </para>
 119 </listitem>
 120 </itemizedlist>
 121
 122 <para>
 123 If the input extension is present and the server allows interaction between the
 124 input extension and Xkb, then the core keyboard, the core keyboard indicators,
 125 and the core keyboard bells may each be addressed using an appropriate device
 126 spec, class, and ID. The constant <emphasis>
 127 XkbXIDfltID</emphasis>
 128  may be used as the device ID to specify the core keyboard indicators for the
 129 core indicator feedback. The particular device ID corresponding to the core
 130 keyboard feedback and the core indicator feedback may be obtained by calling
 131 <emphasis>
 132 XkbGetDeviceInfo</emphasis>
 133  and specifying <emphasis>
 134 XkbUseCoreKbd</emphasis>
 135  as the <emphasis>
 136 device_spec</emphasis>
 137 ; the values will be returned in <emphasis>
 138 dflt_kbd_id</emphasis>
 139  and <emphasis>
 140 dflt_led_id</emphasis>
 141 .
 142 </para>
 143
 144
 145 <para>
 146 If the server does not allow Xkb access to input extension <emphasis>
 147 KeyClass</emphasis>
 148  devices, attempts to use Xkb requests with those devices fail with a
 149 Bad<emphasis>
 150 Keyboard</emphasis>
 151  error. Attempts to access non-<emphasis>
 152 KeyClass</emphasis>
 153  input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail
 154 silently if Xkb access to those devices is not supported by the X server.
 155 </para>
 156
 157 <sect1 id='XkbDeviceInfoRec'>
 158 <title>XkbDeviceInfoRec</title>
 159
 160 <para>
 161 Information about X Input Extension devices is transferred between a client
 162 program and the Xkb extension in an <emphasis>
 163 XkbDeviceInfoRec</emphasis>
 164  structure:
 165 </para>
 166
 167 <para><programlisting>
 168 typedef struct {
 169       char *          name;          /* name for device */
 170       Atom            type;          /* name for class of devices */
 171       unsigned short  device_spec;   /* device of interest */
 172       Bool            has_own_state; /* <emphasis> True</emphasis> =&gt;this
 173                                         device has its own state */
 174       unsigned short  supported;     /* bits indicating supported capabilities */
 175       unsigned short  unsupported;   /* bits indicating unsupported capabilities */
 176       unsigned short  num_btns;      /* number of entries in <emphasis> btn_acts</emphasis> */
 177       XkbAction *     btn_acts;      /* button actions */
 178       unsigned short  sz_leds;       /* total number of entries in LEDs vector */
 179       unsigned short  num_leds;      /* number of valid entries in LEDs vector */
 180       unsigned short  dflt_kbd_fb;   /* input extension ID of default (core kbd) indicator */
 181       unsigned short  dflt_led_fb;   /* input extension ID of default indicator feedback */
 182       XkbDeviceLedInfoPtr  leds;     /* LED descriptions */
 183 } <emphasis>XkbDeviceInfoRec</emphasis>, *XkbDeviceInfoPtr;
 184 </programlisting></para>
 185
 186 <para><programlisting>
 187 typedef struct {
 188       unsigned short   led_class;         /* class for this LED device*/
 189       unsigned short   led_id;            /* ID for this LED device */
 190       unsigned int     phys_indicators;   /* bits for which LEDs physically
 191                                              present */
 192       unsigned int     maps_present;      /* bits for which LEDs have maps in
 193                                              <emphasis>maps</emphasis> */
 194       unsigned int     names_present;     /* bits for which LEDs are in
 195                                              <emphasis> names</emphasis> */
 196       unsigned int     state;            /* 1 bit =&gt; corresponding LED is on */
 197       Atom             names[XkbNumIndicators];  /* names for LEDs */
 198       XkbIndicatorMapRec  maps;          /* indicator maps for each LED */
 199 } <emphasis>XkbDeviceLedInfoRec</emphasis>, *XkbDeviceLedInfoPtr;
 200 </programlisting></para>
 201
 202 <para>
 203 The <emphasis>
 204 type</emphasis>
 205  field is a registered symbolic name for a class of devices (for example,
 206 "TABLET"). If a device is a keyboard (that is, is a member of <emphasis>
 207 KeyClass</emphasis>
 208 ), it has its own state, and <emphasis>
 209 has_own_state</emphasis>
 210  is <emphasis>
 211 True</emphasis>
 212 . If <emphasis>
 213 has_own_state</emphasis>
 214  is <emphasis>
 215 False</emphasis>
 216 , the state of the core keyboard is used. The <emphasis>
 217 supported</emphasis>
 218  and <emphasis>
 219 unsupported</emphasis>
 220  fields are masks where each bit indicates a capability. The meaning of the
 221 mask bits is listed in Table 21.1, together with the fields in the <emphasis>
 222 XkbDeviceInfoRec</emphasis>
 223  structure that are associated with the capability represented by each bit. The
 224 same bits are used to indicate the specific information desired in many of the
 225 functions described subsequently in this section.
 226 </para>
 227
 228 <table frame='topbot'>
 229 <title>XkbDeviceInfoRec Mask Bits</title>
 230 <?dbfo keep-together="always" ?>
 231 <tgroup cols='4' align='left' colsep='0' rowsep='0'>
 232 <colspec colname='c1' colwidth='2.9*'/>
 233 <colspec colname='c2' colwidth='2.0*'/>
 234 <colspec colname='c3' colwidth='0.9*'/>
 235 <colspec colname='c4' colwidth='2.0*'/>
 236 <thead>
 237   <row rowsep='1'>
 238     <entry>Name</entry>
 239     <entry>XkbDeviceInfoRec Fields Effected</entry>
 240     <entry>Value</entry>
 241     <entry>Capability If Set</entry>
 242   </row>
 243 </thead>
 244 <tbody>
 245   <row>
 246     <entry>XkbXI_KeyboardsMask</entry>
 247     <entry></entry>
 248     <entry>(1L &lt;&lt; 0)</entry>
 249     <entry>
 250 Clients can use all Xkb requests and events with
 251 <emphasis>KeyClass</emphasis>
 252 devices supported by the input device extension.
 253     </entry>
 254   </row>
 255   <row>
 256     <entry>XkbXI_ButtonActionsMask</entry>
 257     <entry>
 258 <para>num_btns</para>
 259 <para>btn_acts</para>
 260     </entry>
 261     <entry>(1L &lt;&lt;1)</entry>
 262     <entry>
 263 Clients can assign key actions to buttons on non-<emphasis>
 264 KeyClass</emphasis>
 265 input extension devices.
 266     </entry>
 267   </row>
 268   <row>
 269     <entry>XkbXI_IndicatorNamesMask</entry>
 270     <entry>leds-&gt;names</entry>
 271     <entry>(1L &lt;&lt;2)</entry>
 272     <entry>
 273 Clients can assign names to indicators on non-<emphasis>
 274 KeyClass</emphasis>
 275  input extension devices.
 276     </entry>
 277   </row>
 278   <row>
 279     <entry>XkbXI_IndicatorMapsMask</entry>
 280     <entry>leds-&gt;maps</entry>
 281     <entry>(1L &lt;&lt;3)</entry>
 282     <entry>
 283 Clients can assign indicator maps to indicators on non-<emphasis>
 284 KeyClass</emphasis>
 285  input extension devices.
 286     </entry>
 287   </row>
 288   <row>
 289     <entry>XkbXI_IndicatorStateMask</entry>
 290     <entry>leds-&gt;state</entry>
 291     <entry>(1L &lt;&lt;4)</entry>
 292     <entry>
 293 Clients can request the status of indicators on non-<emphasis>
 294 KeyClass</emphasis>
 295  input extension devices.
 296     </entry>
 297   </row>
 298   <row>
 299     <entry>XkbXI_IndicatorsMask</entry>
 300     <entry>
 301 <para>sz_leds</para>
 302 <para>num_leds</para>
 303 <para>leds-&gt;*</para>
 304     </entry>
 305     <entry>(0x1c)</entry>
 306     <entry>
 307 <para>XkbXI_IndicatorNames&#xAD;Mask |</para>
 308 <para>XkbXI_IndicatorMaps&#xAD;Mask |</para>
 309 <para>XkbXI_IndicatorState&#xAD;Mask</para>
 310     </entry>
 311   </row>
 312   <row>
 313     <entry>XkbXI_UnsupportedFeaturesMask</entry>
 314     <entry>unsupported</entry>
 315     <entry>(1L &lt;&lt;15)</entry>
 316     <entry></entry>
 317   </row>
 318   <row>
 319     <entry>XkbXI_AllDeviceFeaturesMask</entry>
 320     <entry>Those selected by Value column masks</entry>
 321     <entry>(0x1e)</entry>
 322     <entry>
 323 <para>XkbXI_Indicators&#xAD;Mask | </para>
 324 <para>XkbSI_ButtonActions&#xAD;Mask</para>
 325     </entry>
 326   </row>
 327   <row>
 328     <entry>XkbXI_AllFeaturesMask</entry>
 329     <entry>Those selected by Value column masks</entry>
 330     <entry>(0x1f)</entry>
 331     <entry>
 332 <para>XkbSI_AllDevice&#xAD;FeaturesMask |</para>
 333 <para>XkbSI_Keyboards&#xAD;Mask</para>
 334     </entry>
 335   </row>
 336   <row>
 337     <entry>XkbXI_AllDetailsMask</entry>
 338     <entry>Those selected by Value column masks</entry>
 339     <entry>(0x801f)</entry>
 340     <entry>
 341 <para>XkbXI_AllFeatures&#xAD;Mask | </para>
 342 <para>XkbXI_Unsupported&#xAD;FeaturesMask</para>
 343     </entry>
 344   </row>
 345 </tbody>
 346 </tgroup>
 347 </table>
 348
 349 <para>
 350 The <emphasis>
 351 name</emphasis>
 352 , <emphasis>
 353 type</emphasis>
 354 , <emphasis>
 355 has_own_state</emphasis>
 356 , <emphasis>
 357 supported</emphasis>
 358 , and <emphasis>
 359 unsupported</emphasis>
 360  fields are always filled in when a valid reply is returned from the server
 361 involving an <emphasis>
 362 XkbDeviceInfoRec</emphasis>
 363 . All of the other fields are modified only if the particular function asks for
 364 them.
 365 </para>
 366
 367 </sect1>
 368 <sect1 id='Querying_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices'>
 369 <title>Querying Xkb Features for Non-KeyClass Input Extension Devices</title>
 370
 371 <para>
 372 To determine whether the X server allows Xkb access to particular capabilities
 373 of input devices other than the core X keyboard, or to determine the status of
 374 indicator maps, indicator names or button actions on a non-<emphasis>
 375 KeyClass</emphasis>
 376  extension device, use XkbGetDeviceInfo.
 377 </para>
 378
 379 <informaltable frame='none'>
 380 <?dbfo keep-together="always" ?>
 381 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 382 <colspec colname='c1' colwidth='1.0*'/>
 383 <tbody>
 384   <row>
 385     <entry role='functiondecl'>
 386 XkbDeviceInfoPtr <emphasis>
 387 XkbGetDeviceInfo</emphasis>
 388 (<emphasis>
 389 dpy</emphasis>
 390 , which, device_spec, ind_class, ind_id)
 391     </entry>
 392   </row>
 393   <row>
 394     <entry role='functionargdecl'>
 395 Display *            <emphasis>
 396 dpy</emphasis>
 397 ;            /* connection to X server */
 398     </entry>
 399   </row>
 400   <row>
 401     <entry role='functionargdecl'>
 402 unsigned int            which;            /* mask indicating information to
 403 return */
 404     </entry>
 405   </row>
 406   <row>
 407     <entry role='functionargdecl'>
 408 unsigned int            <emphasis>
 409 device_spec</emphasis>
 410 ;            /* device ID, or <emphasis>
 411 XkbUseCoreKbd</emphasis>
 412  */
 413     </entry>
 414   </row>
 415   <row>
 416     <entry role='functionargdecl'>
 417 unsigned int            <emphasis>
 418 ind_class</emphasis>
 419 ;            /* feedback class for indicator requests */
 420     </entry>
 421   </row>
 422   <row>
 423     <entry role='functionargdecl'>
 424 unsigned int            <emphasis>
 425 ind_id</emphasis>
 426 ;            /* feedback ID for indicator requests */
 427     </entry>
 428 </row>
 429 </tbody>
 430 </tgroup>
 431 </informaltable>
 432
 433 <para>
 434 <emphasis>
 435 XkbGetDeviceInfo</emphasis>
 436  returns information about the input device specified by <emphasis>
 437 device_spec</emphasis>
 438 . Unlike the <emphasis>
 439 device_spec</emphasis>
 440  parameter of most Xkb functions, <emphasis>
 441 device_spec</emphasis>
 442  does not need to be a keyboard device. It must, however, indicate either the
 443 core keyboard or a valid X Input Extension device.
 444 </para>
 445
 446
 447 <para>
 448 The <emphasis>
 449 which </emphasis>
 450 parameter<emphasis>
 451  </emphasis>
 452 is a mask specifying optional information to be returned. It is an inclusive OR
 453 of one or more of the values from Table 21.1 and causes the returned <emphasis>
 454 XkbDeviceInfoRec</emphasis>
 455  to contain values for the corresponding fields specified in the table.
 456 </para>
 457
 458
 459 <para>
 460 The <emphasis>
 461 XkbDeviceInfoRec</emphasis>
 462  returned by <emphasis>
 463 XkbGetDeviceInfo</emphasis>
 464  always has values for <emphasis>
 465 name</emphasis>
 466  (may be a null string, ""), <emphasis>
 467 type</emphasis>
 468 , <emphasis>
 469 supported</emphasis>
 470 , <emphasis>
 471 unsupported</emphasis>
 472 , <emphasis>
 473 has_own_state</emphasis>
 474 , <emphasis>
 475 dflt_kbd_fd</emphasis>
 476 , and <emphasis>
 477 dflt_kbd_fb</emphasis>
 478 . Other fields are filled in as specified by <emphasis>
 479 which</emphasis>
 480 .
 481 </para>
 482
 483
 484 <para>
 485 Upon return, the <emphasis>
 486 supported</emphasis>
 487  field will be set to the inclusive OR of zero or more bits from Table 21.1;
 488 each bit set indicates an optional Xkb extension device feature supported by
 489 the server implementation, and a client may modify the associated behavior.
 490 </para>
 491
 492
 493 <para>
 494 If the <emphasis>
 495 XkbButtonActionsMask</emphasis>
 496  bit is set in <emphasis>
 497 which</emphasis>
 498 , the <emphasis>
 499 XkbDeviceInfoRec</emphasis>
 500  returned will have the button actions (<emphasis>
 501 btn_acts</emphasis>
 502  field) filled in for all buttons.
 503 </para>
 504
 505
 506 <para>
 507 If <emphasis>
 508 which</emphasis>
 509  includes one of the bits in XkbXI_IndicatorsMask, the feedback class of the
 510 indicators must be specified in ind_class, and the feedback ID of the
 511 indicators must be specified in ind_id. If the request does not include any of
 512 the bits in XkbXI_IndicatorsMask, the ind_class and ind_id parameters are
 513 ignored. The class and ID can be obtained via the input device extension
 514 XListInputDevices request.
 515 </para>
 516
 517
 518 <para>
 519 If any of the <emphasis>
 520 XkbXI_IndicatorsMask</emphasis>
 521  bits are set in <emphasis>
 522 which</emphasis>
 523 , the <emphasis>
 524 XkbDeviceInfoRec</emphasis>
 525  returned will have filled in the portions of the <emphasis>
 526 leds</emphasis>
 527  structure corresponding to the indicator feedback identified by <emphasis>
 528 ind_class</emphasis>
 529  and <emphasis>
 530 ind_id</emphasis>
 531 . The <emphasis>
 532 leds</emphasis>
 533  vector of the <emphasis>
 534 XkbDeviceInfoRec</emphasis>
 535  is allocated if necessary and <emphasis>
 536 sz_leds</emphasis>
 537  and <emphasis>
 538 num_leds</emphasis>
 539  filled in. The <emphasis>
 540 led_class</emphasis>
 541 , <emphasis>
 542 led_id</emphasis>
 543  and <emphasis>
 544 phys_indicators</emphasis>
 545  fields of the <emphasis>
 546 leds</emphasis>
 547  entry corresponding to <emphasis>
 548 ind_class</emphasis>
 549  and <emphasis>
 550 ind_id</emphasis>
 551  are always filled in. If <emphasis>
 552 which</emphasis>
 553  contains <emphasis>
 554 XkbXI_IndicatorNamesMask</emphasis>
 555 , the <emphasis>
 556 names_present</emphasis>
 557  and <emphasis>
 558 names</emphasis>
 559  fields of the <emphasis>
 560 leds</emphasis>
 561  structure corresponding to <emphasis>
 562 ind_class</emphasis>
 563  and <emphasis>
 564 ind_id</emphasis>
 565  are returned.<emphasis>
 566  </emphasis>
 567 If <emphasis>
 568 which</emphasis>
 569  contains <emphasis>
 570 XkbXI_IndicatorStateMask</emphasis>
 571 <emphasis>
 572 ,</emphasis>
 573  the corresponding <emphasis>
 574 state</emphasis>
 575  field is updated. If <emphasis>
 576 which</emphasis>
 577  contains <emphasis>
 578 XkbXI_IndicatorMapsMask</emphasis>
 579 , the <emphasis>
 580 maps_present</emphasis>
 581  and <emphasis>
 582 maps</emphasis>
 583  fields are updated.
 584 </para>
 585
 586
 587 <para>
 588 Xkb provides convenience functions to request subsets of the information
 589 available via <emphasis>
 590 XkbGetDeviceInfo</emphasis>
 591 . These convenience functions mirror some of the mask bits. The functions all
 592 take an <emphasis>
 593 XkbDeviceInfoPtr</emphasis>
 594  as an input argument and operate on the X Input Extension device specified by
 595 the <emphasis>
 596 device_spec</emphasis>
 597  field of the structure. Only the parts of the structure indicated in the
 598 function description are updated. The <emphasis>
 599 XkbDeviceInfo</emphasis>
 600 Rec structure used in the function call can be obtained by calling
 601 XkbGetDeviceInfo or can be allocated by calling XkbAllocDeviceInfo (see section
 602 21.3).
 603 </para>
 604
 605
 606 <para>
 607 These convenience functions are described as follows.
 608 </para>
 609
 610
 611 <para>
 612 To query the button actions associated with an X Input Extension device, use
 613 XkbGetDeviceButtonActions.
 614 </para>
 615
 616
 617 <informaltable frame='none'>
 618 <?dbfo keep-together="always" ?>
 619 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 620 <colspec colname='c1' colwidth='1.0*'/>
 621 <tbody>
 622   <row>
 623     <entry role='functiondecl'>
 624 Status <emphasis>
 625 XkbGetDeviceButtonActions</emphasis>
 626 (<emphasis>
 627 dpy, device_info, all_buttons, first_button, num_buttons</emphasis>
 628 )
 629     </entry>
 630   </row>
 631   <row>
 632     <entry role='functionargdecl'>
 633 Display *            <emphasis>
 634 dpy</emphasis>
 635 ;            /* connection to X server */
 636     </entry>
 637   </row>
 638   <row>
 639     <entry role='functionargdecl'>
 640 XkbDeviceInfoPtr            device_info;            /* structure to update with
 641 results */
 642     </entry>
 643   </row>
 644   <row>
 645     <entry role='functionargdecl'>
 646 Bool            <emphasis>
 647 all_buttons</emphasis>
 648 ;            /* <emphasis>
 649 True</emphasis>
 650  =&gt; get information for all buttons */
 651     </entry>
 652   </row>
 653   <row>
 654     <entry role='functionargdecl'>
 655 unsigned int            first_button;            /* number of first button for
 656 which info is desired */
 657     </entry>
 658   </row>
 659   <row>
 660     <entry role='functionargdecl'>
 661 unsigned int            num_buttons;            /* number of buttons for which
 662 info is desired */
 663     </entry>
 664 </row>
 665 </tbody>
 666 </tgroup>
 667 </informaltable>
 668
 669 <para>
 670 <emphasis>
 671 XkbGetDeviceButtonActions</emphasis>
 672  queries the server for the desired button information for the device indicated
 673 by the <emphasis>
 674 device_spec</emphasis>
 675  field of <emphasis>
 676 device_info</emphasis>
 677  and waits for a reply. If successful,<emphasis>
 678  XkbGetDeviceButtonActions</emphasis>
 679  backfills the button actions (<emphasis>
 680 btn_acts</emphasis>
 681  field of <emphasis>
 682 device_info</emphasis>
 683 ) for only the requested buttons, updates the <emphasis>
 684 name</emphasis>
 685 , <emphasis>
 686 type</emphasis>
 687 , <emphasis>
 688 supported</emphasis>
 689 , and <emphasis>
 690 unsupported</emphasis>
 691  fields, and returns <emphasis>
 692 Success</emphasis>
 693 .
 694 </para>
 695
 696
 697 <para>
 698 <emphasis>
 699 all_buttons</emphasis>
 700 , <emphasis>
 701 first_button</emphasis>
 702  and <emphasis>
 703 num_buttons</emphasis>
 704  specify the device buttons for which actions should be returned. Setting
 705 <emphasis>
 706 all_buttons</emphasis>
 707  to <emphasis>
 708 True</emphasis>
 709  requests actions for all device buttons; if <emphasis>
 710 all_buttons</emphasis>
 711  is <emphasis>
 712 False</emphasis>
 713 , <emphasis>
 714 first_button</emphasis>
 715  and <emphasis>
 716 num_buttons</emphasis>
 717  specify a range of buttons for which actions are requested.
 718 </para>
 719
 720
 721 <para>
 722 If a compatible version of Xkb is not available in the server or the Xkb
 723 extension has not been properly initialized, XkbGetDeviceButtonActions returns
 724 <emphasis>
 725 BadAccess</emphasis>
 726 . If allocation errors occur, a <emphasis>
 727 BadAlloc</emphasis>
 728  status is returned. If the specified device (<emphasis>
 729 device_info</emphasis>
 730 -&gt;<emphasis>
 731 device_spec</emphasis>
 732 ) is invalid, a BadKeyboard status is returned. If the device has no buttons, a
 733 Bad<emphasis>
 734 Match</emphasis>
 735  status is returned. If <emphasis>
 736 first_button</emphasis>
 737  and <emphasis>
 738 num_buttons</emphasis>
 739  specify illegal buttons, a Bad<emphasis>
 740 Value</emphasis>
 741  status is returned.
 742 </para>
 743
 744
 745 <para>
 746 To query the indicator names, maps, and state associated with an LED feedback
 747 of an input extension device, use XkbGetDeviceLedInfo.
 748 </para>
 749
 750
 751 <informaltable frame='none'>
 752 <?dbfo keep-together="always" ?>
 753 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 754 <colspec colname='c1' colwidth='1.0*'/>
 755 <tbody>
 756   <row>
 757     <entry role='functiondecl'>
 758 Status <emphasis>
 759 XkbGetDeviceLedInfo</emphasis>
 760 (<emphasis>
 761 dpy, device_i</emphasis>
 762 nfo, led_class, led_id, which)
 763     </entry>
 764   </row>
 765   <row>
 766     <entry role='functionargdecl'>
 767 Display *            <emphasis>
 768 dpy</emphasis>
 769 ;            /* connection to X server */
 770     </entry>
 771   </row>
 772   <row>
 773     <entry role='functionargdecl'>
 774 XkbDeviceInfoPtr            device_info;            /* structure to update with
 775 results */
 776     </entry>
 777   </row>
 778   <row>
 779     <entry role='functionargdecl'>
 780 unsigned int            <emphasis>
 781 led_class</emphasis>
 782 ;            /* LED feedback class assigned by input extension */
 783     </entry>
 784   </row>
 785   <row>
 786     <entry role='functionargdecl'>
 787 unsigned int            led_id;            /* LED feedback ID assigned by input
 788 extension */
 789     </entry>
 790   </row>
 791   <row>
 792     <entry role='functionargdecl'>
 793 unsigned int            which;            /* mask indicating desired
 794 information */
 795     </entry>
 796 </row>
 797 </tbody>
 798 </tgroup>
 799 </informaltable>
 800
 801 <para>
 802 <emphasis>
 803 XkbGetDeviceLedInfo</emphasis>
 804  queries the server for the desired LED information for the feedback specified
 805 by <emphasis>
 806 led_class</emphasis>
 807  and <emphasis>
 808 led_id</emphasis>
 809  for the X input extension device indicated by <emphasis>
 810 device_spec</emphasis>
 811 -&gt;<emphasis>
 812 device_info</emphasis>
 813  and waits for a reply. If successful, <emphasis>
 814 XkbGetDeviceLedInfo</emphasis>
 815  backfills the relevant fields of <emphasis>
 816 device_info</emphasis>
 817  as determined by <emphasis>
 818 which</emphasis>
 819  with the results and returns <emphasis>
 820 Success</emphasis>
 821 . Valid values for <emphasis>
 822 which</emphasis>
 823  are the inclusive OR of any of <emphasis>
 824 XkbXI_IndicatorNamesMask</emphasis>
 825 , <emphasis>
 826 XkbXI_IndicatorMapsMask</emphasis>
 827 , and <emphasis>
 828 XkbXI_IndicatorStateMask</emphasis>
 829 .
 830 </para>
 831
 832
 833 <para>
 834 The fields of <emphasis>
 835 device_info</emphasis>
 836  that are filled in when this request succeeds are <emphasis>
 837 name, type, supported</emphasis>
 838 , and <emphasis>
 839 unsupported</emphasis>
 840 , and portions of the <emphasis>
 841 leds</emphasis>
 842  structure corresponding to <emphasis>
 843 led_class</emphasis>
 844  and <emphasis>
 845 led_id</emphasis>
 846  as indicated by the bits set in <emphasis>
 847 which</emphasis>
 848 . The <emphasis>
 849 device_info-&gt;leds</emphasis>
 850  vector is allocated if necessary and <emphasis>
 851 sz_leds</emphasis>
 852  and <emphasis>
 853 num_leds</emphasis>
 854  filled in. The <emphasis>
 855 led_class</emphasis>
 856 , <emphasis>
 857 led_id</emphasis>
 858  and <emphasis>
 859 phys_indicators</emphasis>
 860  fields of the <emphasis>
 861 device_info</emphasis>
 862 -&gt;<emphasis>
 863 leds</emphasis>
 864  entry corresponding to <emphasis>
 865 led_class</emphasis>
 866  and <emphasis>
 867 led_id</emphasis>
 868  are always filled in.
 869 </para>
 870
 871
 872 <para>
 873 If <emphasis>
 874 which</emphasis>
 875  contains <emphasis>
 876 XkbXI_IndicatorNamesMask</emphasis>
 877 , the <emphasis>
 878 names_present</emphasis>
 879  and <emphasis>
 880 names</emphasis>
 881  fields of the <emphasis>
 882 device_info</emphasis>
 883 -&gt;<emphasis>
 884 leds</emphasis>
 885  structure corresponding to <emphasis>
 886 led_class</emphasis>
 887  and <emphasis>
 888 led_id</emphasis>
 889  are updated, if <emphasis>
 890 which</emphasis>
 891  contains <emphasis>
 892 XkbXI_IndicatorStateMask</emphasis>
 893 <emphasis>
 894 ,</emphasis>
 895  the corresponding <emphasis>
 896 state</emphasis>
 897  field is updated, and if <emphasis>
 898 which</emphasis>
 899  contains <emphasis>
 900 XkbXI_IndicatorMapsMask</emphasis>
 901 , the <emphasis>
 902 maps_present</emphasis>
 903  and <emphasis>
 904 maps</emphasis>
 905  fields are updated.
 906 </para>
 907
 908
 909 <para>
 910 If a compatible version of Xkb is not available in the server or the Xkb
 911 extension has not been properly initialized, <emphasis>
 912 XkbGetDeviceLedInfo</emphasis>
 913  returns <emphasis>
 914 BadAccess</emphasis>
 915 . If allocation errors occur, a BadAlloc status is returned. If the device has
 916 no indicators, a BadMatch error is returned. If <emphasis>
 917 ledClass</emphasis>
 918  or <emphasis>
 919 ledID</emphasis>
 920  have illegal values, a Bad<emphasis>
 921 Value</emphasis>
 922  error is returned. If they have legal values but do not specify a feedback
 923 that contains LEDs and is associated with the specified device, a Bad<emphasis>
 924 Match</emphasis>
 925  error is returned.
 926 </para>
 927
 928
 929 </sect1>
 930 <sect1 id='Allocating_Initializing_and_Freeing_the_XkbDeviceInfoRecStructure'>
 931 <title>Allocating, Initializing, and Freeing the XkbDeviceInfoRec
 932 Structure</title>
 933
 934 <para>
 935 To obtain an <emphasis>
 936 XkbDeviceInfoRec</emphasis>
 937  structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo.
 938 </para>
 939
 940 <informaltable frame='none'>
 941 <?dbfo keep-together="always" ?>
 942 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 943 <colspec colname='c1' colwidth='1.0*'/>
 944 <tbody>
 945   <row>
 946     <entry role='functiondecl'>
 947 XkbDeviceInfoPtr <emphasis>
 948 XkbAllocDeviceInfo</emphasis>
 949 (device_spec, n_buttons, sz_leds)
 950     </entry>
 951   </row>
 952   <row>
 953     <entry role='functionargdecl'>
 954 unsigned int            device_spec;            /* device ID with which
 955 structure will be used */
 956     </entry>
 957   </row>
 958   <row>
 959     <entry role='functionargdecl'>
 960 unsigned int            <emphasis>
 961 n_buttons</emphasis>
 962 ;            /* number of button actions to allocate space for*/
 963     </entry>
 964   </row>
 965   <row>
 966     <entry role='functionargdecl'>
 967 unsigned int            <emphasis>
 968 sz_leds</emphasis>
 969 ;            /* number of LED feedbacks to allocate space for */
 970     </entry>
 971 </row>
 972 </tbody>
 973 </tgroup>
 974 </informaltable>
 975
 976 <para>
 977 <emphasis>
 978 XkbAllocDeviceInfo</emphasis>
 979  allocates space for an <emphasis>
 980 XkbDeviceInfoRec</emphasis>
 981  structure and initializes that structure’s <emphasis>
 982 device_spec</emphasis>
 983  field with the device ID specified by device_spec. If <emphasis>
 984 n_buttons</emphasis>
 985  is nonzero, <emphasis>
 986 n_buttons</emphasis>
 987  <emphasis>
 988 XkbActions</emphasis>
 989  are linked into the <emphasis>
 990 XkbDeviceInfoRec</emphasis>
 991  structure and initialized to zero. If sz_leds is nonzero, <emphasis>
 992 sz_leds</emphasis>
 993  <emphasis>
 994 XkbDeviceLedInfoRec</emphasis>
 995  structures are also allocated and linked into the <emphasis>
 996 XkbDeviceInfoRec</emphasis>
 997  structure. If you request <emphasis>
 998 XkbDeviceLedInfoRec</emphasis>
 999  structures be allocated using this request, you must initialize them
1000 explicitly.
1001 </para>
1002
1003
1004 <para>
1005 To obtain an <emphasis>
1006 XkbDeviceLedInfoRec</emphasis>
1007  structure, use XkbAllocDeviceLedInfo.
1008 </para>
1009
1010
1011 <informaltable frame='none'>
1012 <?dbfo keep-together="always" ?>
1013 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1014 <colspec colname='c1' colwidth='1.0*'/>
1015 <tbody>
1016   <row>
1017     <entry role='functiondecl'>
1018 Status <emphasis>
1019 XkbAllocDeviceLedInfo</emphasis>
1020 (devi, num_needed)
1021     </entry>
1022   </row>
1023   <row>
1024     <entry role='functionargdecl'>
1025 XkbDeviceInfoPtr            <emphasis>
1026 device_info</emphasis>
1027 ;            /* structure in which to allocate LED space */
1028     </entry>
1029   </row>
1030   <row>
1031     <entry role='functionargdecl'>
1032 int            <emphasis>
1033 num_needed</emphasis>
1034 ;            /* number of indicators to allocate space for */
1035     </entry>
1036 </row>
1037 </tbody>
1038 </tgroup>
1039 </informaltable>
1040
1041 <para>
1042 <emphasis>
1043 XkbAllocDeviceLedInfo</emphasis>
1044  allocates space for an <emphasis>
1045 XkbDeviceLedInfoRec</emphasis>
1046  and places it in <emphasis>
1047 device_info</emphasis>
1048 . If num_needed is nonzero, <emphasis>
1049 num_needed</emphasis>
1050  <emphasis>
1051 XkbIndicatorMapRec</emphasis>
1052  structures are also allocated and linked into the <emphasis>
1053 XkbDeviceLedInfoRec</emphasis>
1054  structure. If you request <emphasis>
1055 XkbIndicatorMapRec</emphasis>
1056  structures be allocated using this request, you must initialize them
1057 explicitly. All other fields are initialized to zero.
1058 </para>
1059
1060
1061 <para>
1062 To initialize an <emphasis>
1063 XkbDeviceLedInfoRec</emphasis>
1064  structure, use XkbAddDeviceLedInfo.
1065 </para>
1066
1067
1068 <informaltable frame='none'>
1069 <?dbfo keep-together="always" ?>
1070 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1071 <colspec colname='c1' colwidth='1.0*'/>
1072 <tbody>
1073   <row>
1074     <entry role='functiondecl'>
1075 XkbDeviceLedInfoPtr <emphasis>
1076 XkbAddDeviceLedInfo</emphasis>
1077 (device_info, led_class, led_id)
1078     </entry>
1079   </row>
1080   <row>
1081     <entry role='functionargdecl'>
1082 XkbDeviceInfoPtr            device_info;            /* structure in which to
1083 add LED info */
1084     </entry>
1085   </row>
1086   <row>
1087     <entry role='functionargdecl'>
1088 unsigned int            <emphasis>
1089 led_class</emphasis>
1090 ;            /* input extension class for LED device of interest */
1091     </entry>
1092   </row>
1093   <row>
1094     <entry role='functionargdecl'>
1095 unsigned int            <emphasis>
1096 led_id</emphasis>
1097 ;            /* input extension ID for LED device of interest */
1098     </entry>
1099 </row>
1100 </tbody>
1101 </tgroup>
1102 </informaltable>
1103
1104 <para>
1105 <emphasis>
1106 XkbAddDeviceLedInfo</emphasis>
1107  first checks to see whether an entry matching <emphasis>
1108 led_class</emphasis>
1109  and <emphasis>
1110 led_id</emphasis>
1111  already exists in the <emphasis>
1112 device_info-&gt;leds</emphasis>
1113  array. If it finds a matching entry, it returns a pointer to that entry.
1114 Otherwise, it checks to be sure there is at least one empty entry in <emphasis>
1115 device_info</emphasis>
1116 -&gt;<emphasis>
1117 leds</emphasis>
1118  and extends it if there is not enough room. It then increments <emphasis>
1119 device_info</emphasis>
1120 -&gt;<emphasis>
1121 num_leds</emphasis>
1122  and fills in the next available entry in <emphasis>
1123 device_info</emphasis>
1124 -&gt;<emphasis>
1125 leds</emphasis>
1126  with <emphasis>
1127 led_class</emphasis>
1128  and <emphasis>
1129 led_id</emphasis>
1130 .
1131 </para>
1132
1133
1134 <para>
1135 If successful, <emphasis>
1136 XkbAddDeviceLedInfo</emphasis>
1137  returns a pointer to the <emphasis>
1138 XkbDeviceLedInfoRec</emphasis>
1139  structure that was initialized. If unable to allocate sufficient storage, or
1140 if <emphasis>
1141 device_info</emphasis>
1142  points to an invalid <emphasis>
1143 XkbDeviceInfoRec</emphasis>
1144  structure, or if <emphasis>
1145 led_class</emphasis>
1146  or <emphasis>
1147 led_id</emphasis>
1148  are inappropriate, <emphasis>
1149 XkbAddDeviceLedInfo</emphasis>
1150  returns <emphasis>
1151 NULL</emphasis>
1152 .
1153 </para>
1154
1155
1156 <para>
1157 To allocate additional space for button actions in an <emphasis>
1158 XkbDeviceInfoRec</emphasis>
1159  structure, use XkbResizeDeviceButtonActions.
1160 </para>
1161
1162
1163 <informaltable frame='none'>
1164 <?dbfo keep-together="always" ?>
1165 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1166 <colspec colname='c1' colwidth='1.0*'/>
1167 <tbody>
1168   <row>
1169     <entry role='functiondecl'>
1170 Status <emphasis>
1171 XkbResizeDeviceButtonActions</emphasis>
1172 (device_info, new_total)
1173     </entry>
1174   </row>
1175   <row>
1176     <entry role='functionargdecl'>
1177 XkbDeviceInfoPtr            device_info;            /* structure in which to
1178 allocate button actions */
1179     </entry>
1180   </row>
1181   <row>
1182     <entry role='functionargdecl'>
1183 unsigned int            <emphasis>
1184 new_total</emphasis>
1185 ;            /* new total number of button actions needed */
1186     </entry>
1187 </row>
1188 </tbody>
1189 </tgroup>
1190 </informaltable>
1191
1192 <para>
1193 <emphasis>
1194 XkbResizeDeviceButton</emphasis>
1195  reallocates space, if necessary, to make sure there is room for a total of
1196 <emphasis>
1197 new_total</emphasis>
1198  button actions in the <emphasis>
1199 device_info</emphasis>
1200  structure. Any new entries allocated are zeroed. If successful, <emphasis>
1201 XkbResizeDeviceButton</emphasis>
1202  returns Success. If new_total is zero, all button actions are deleted,
1203 <emphasis>
1204 device_info</emphasis>
1205 -&gt;<emphasis>
1206 num_btns</emphasis>
1207  is set to zero, and <emphasis>
1208 device_info</emphasis>
1209 -&gt;<emphasis>
1210 btn_acts</emphasis>
1211  is set to <emphasis>
1212 NULL</emphasis>
1213 . If device_info is invalid or new_total is greater than 255, BadValue is
1214 returned. If a memory allocation failure occurs, a <emphasis>
1215 BadAlloc</emphasis>
1216  is returned.
1217 </para>
1218
1219
1220 <para>
1221 To free an <emphasis>
1222 XkbDeviceInfoRec</emphasis>
1223  structure, use XkbFreeDeviceInfo.
1224 </para>
1225
1226
1227 <informaltable frame='none'>
1228 <?dbfo keep-together="always" ?>
1229 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1230 <colspec colname='c1' colwidth='1.0*'/>
1231 <tbody>
1232   <row>
1233     <entry role='functiondecl'>
1234 void <emphasis>
1235 XkbFreeDeviceInfo</emphasis>
1236 (device_info, which, free_all)
1237     </entry>
1238   </row>
1239   <row>
1240     <entry role='functionargdecl'>
1241 XkbDeviceInfoPtr            device_info;            /* pointer to <emphasis>
1242 XkbDeviceInfoRec</emphasis>
1243  in which to free items */
1244     </entry>
1245   </row>
1246   <row>
1247     <entry role='functionargdecl'>
1248 unsigned int            <emphasis>
1249 which</emphasis>
1250 ;            /* mask of components of <emphasis>
1251 device_info</emphasis>
1252  to free */
1253     </entry>
1254   </row>
1255   <row>
1256     <entry role='functionargdecl'>
1257 Bool            <emphasis>
1258 free_all</emphasis>
1259 ;            /* <emphasis>
1260 True</emphasis>
1261  =&gt; free everything, including device_info */
1262     </entry>
1263 </row>
1264 </tbody>
1265 </tgroup>
1266 </informaltable>
1267
1268 <para>
1269 If free_all is <emphasis>
1270 True</emphasis>
1271 , the <emphasis>
1272 XkbFreeDeviceInfo</emphasis>
1273  frees all components of <emphasis>
1274 device_info</emphasis>
1275  and the <emphasis>
1276 XkbDeviceInfoRec</emphasis>
1277  structure pointed to by <emphasis>
1278 device_info</emphasis>
1279  itself. If free_all is <emphasis>
1280 False</emphasis>
1281 , the value of which determines which subcomponents are freed. <emphasis>
1282 which </emphasis>
1283 is an inclusive OR of one or more of the values from Table 21.1. If which
1284 contains XkbXI_ButtonActionsMask, all button actions associated with <emphasis>
1285 device_info</emphasis>
1286  are freed, <emphasis>
1287 device_info</emphasis>
1288 -&gt;<emphasis>
1289 btn_acts</emphasis>
1290  is set to <emphasis>
1291 NULL</emphasis>
1292 , and <emphasis>
1293 device_info</emphasis>
1294 -&gt;<emphasis>
1295 num_btns</emphasis>
1296  is set to zero. If which contains all bits in XkbXI_IndicatorsMask, all
1297 <emphasis>
1298 XkbDeviceLedInfoRec</emphasis>
1299  structures associated with <emphasis>
1300 device_info</emphasis>
1301  are freed, <emphasis>
1302 device_info</emphasis>
1303 -&gt;<emphasis>
1304 leds</emphasis>
1305  is set to <emphasis>
1306 NULL</emphasis>
1307 , and <emphasis>
1308 device_info</emphasis>
1309 -&gt;<emphasis>
1310 sz_leds</emphasis>
1311  and <emphasis>
1312 device_info</emphasis>
1313 -&gt;<emphasis>
1314 num_leds</emphasis>
1315  are set to zero. If which contains XkbXI_IndicatorMapsMask, all indicator maps
1316 associated with <emphasis>
1317 device_info</emphasis>
1318  are cleared, but the number of LEDs and the leds structures themselves are
1319 preserved. If which contains XkbXI_IndicatorNamesMask, all indicator names
1320 associated with device_info are cleared, but the number of LEDs and the leds
1321 structures themselves are preserved. If which contains
1322 XkbXI_IndicatorStateMask, the indicator state associated with the <emphasis>
1323 device_info</emphasis>
1324  leds are set to zeros but the number of LEDs and the leds structures
1325 themselves are preserved.
1326 </para>
1327
1328
1329 </sect1>
1330 <sect1 id='Setting_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices'>
1331 <title>Setting Xkb Features for Non-KeyClass Input Extension Devices</title>
1332
1333 <para>
1334 The Xkb extension allows clients to assign any key action to either core
1335 pointer or input extension device buttons. This makes it possible to control
1336 the keyboard or generate keyboard key events from extension devices or from the
1337 core pointer.
1338 </para>
1339
1340
1341 <para>
1342 Key actions assigned to core X pointer buttons or input extension device
1343 buttons cause key events to be generated as if they had originated from the
1344 core X keyboard.
1345 </para>
1346
1347
1348 <para>
1349 Xkb implementations are required to support key actions for the buttons of the
1350 core pointer device, but support for actions on extension devices is optional.
1351 Implementations that do not support button actions for extension devices must
1352 not set the <emphasis>
1353 XkbXI_ButtonActionsMask</emphasis>
1354  bit in the <emphasis>
1355 supported</emphasis>
1356  field of an <emphasis>
1357 XkbDeviceInfoRec</emphasis>
1358  structure.
1359 </para>
1360
1361
1362 <para>
1363 If a client attempts to modify valid characteristics of a device using an
1364 implementation that does not support modification of those characteristics, no
1365 protocol error is generated. Instead, the server reports a failure for the
1366 request; it also sends an <emphasis>
1367 XkbExtensionDeviceNotify</emphasis>
1368  event to the client that issued the request if the client has selected to
1369 receive these events.
1370 </para>
1371
1372
1373 <para>
1374 To change characteristics of an X Input Extension device in the server, first
1375 modify a local copy of the device structure and then use either <emphasis>
1376 XkbSetDeviceInfo,</emphasis>
1377  or, to save network traffic, use an <emphasis>
1378 XkbDeviceChangesRec</emphasis>
1379  structure (see section 21.6) and call <emphasis>
1380 XkbChangeDeviceInfo</emphasis>
1381  to download the changes to the server.
1382 </para>
1383
1384
1385 <para>
1386 To modify some or all of the characteristics of an X Input Extension device,
1387 use XkbSetDeviceInfo.
1388 </para>
1389
1390 <informaltable frame='none'>
1391 <?dbfo keep-together="always" ?>
1392 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1393 <colspec colname='c1' colwidth='1.0*'/>
1394 <tbody>
1395   <row>
1396     <entry role='functiondecl'>
1397 Bool <emphasis>
1398 XkbSetDeviceInfo</emphasis>
1399 (<emphasis>
1400 dpy</emphasis>
1401 , which, device_info)
1402     </entry>
1403   </row>
1404   <row>
1405     <entry role='functionargdecl'>
1406 Display *            <emphasis>
1407 dpy</emphasis>
1408 ;            /* connection to X server */
1409     </entry>
1410   </row>
1411   <row>
1412     <entry role='functionargdecl'>
1413 unsigned int            <emphasis>
1414 which</emphasis>
1415 ;            /* mask indicating characteristics to modify */
1416     </entry>
1417   </row>
1418   <row>
1419     <entry role='functionargdecl'>
1420 XkbDeviceInfoPtr            device_info;            /* structure defining the
1421 device and modifications */
1422     </entry>
1423 </row>
1424 </tbody>
1425 </tgroup>
1426 </informaltable>
1427
1428 <para>
1429 <emphasis>
1430 XkbSetDeviceInfo</emphasis>
1431  sends a request to the server to modify the characteristics of the device
1432 specified in the <emphasis>
1433 device_info</emphasis>
1434  structure. The particular characteristics modified are identified by the bits
1435 set in <emphasis>
1436 which</emphasis>
1437  and take their values from the relevant fields in <emphasis>
1438 device_info</emphasis>
1439  (see Table 21.1). <emphasis>
1440 XkbSetDeviceInfo</emphasis>
1441  returns <emphasis>
1442 True</emphasis>
1443  if the request was successfully sent to the server. If the X server
1444 implementation does not allow interaction between the X input extension and the
1445 Xkb Extension, the function does nothing and returns <emphasis>
1446 False</emphasis>
1447 .
1448 </para>
1449
1450
1451 <para>
1452 The <emphasis>
1453 which</emphasis>
1454  parameter specifies which aspects of the device should be changed and is a
1455 bitmask composed of an inclusive OR or one or more of the following bits:
1456 <emphasis>
1457 XkbXI_ButtonActionsMask</emphasis>
1458 , <emphasis>
1459 XkbXI_IndicatorNamesMask</emphasis>
1460 , <emphasis>
1461 XkbXI_IndicatorMapsMask</emphasis>
1462 . If the features requested to be manipulated in <emphasis>
1463 which</emphasis>
1464  are valid for the device, but the server does not support assignment of one or
1465 more of them, that particular portion of the request is ignored.
1466 </para>
1467
1468
1469 <para>
1470 If the device specified in <emphasis>
1471 device_info</emphasis>
1472 -&gt;<emphasis>
1473 device_spec</emphasis>
1474  does not contain buttons and a request affecting buttons is made, or the
1475 device does not contain indicators and a request affecting indicators is made,
1476 a <emphasis>
1477 BadMatch</emphasis>
1478  protocol error results.
1479 </para>
1480
1481
1482 <para>
1483 If the <emphasis>
1484 XkbXI_ButtonActionsMask</emphasis>
1485  bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb
1486 extension allows applications to assign key actions to buttons on input
1487 extension devices other than the core keyboard device. If the <emphasis>
1488 XkbXI_ButtonActionsMask</emphasis>
1489  is set in <emphasis>
1490 which</emphasis>
1491 , the actions for all buttons specified in device_info are set to the <emphasis>
1492 XkbAction</emphasis>
1493 s specified in <emphasis>
1494 device_info</emphasis>
1495 -&gt;<emphasis>
1496 btn_acts</emphasis>
1497 . If the number of buttons requested to be updated is not valid for the device,
1498 <emphasis>
1499 XkbSetDeviceInfo</emphasis>
1500  returns <emphasis>
1501 False</emphasis>
1502  and a <emphasis>
1503 BadValue</emphasis>
1504  protocol error results.
1505 </para>
1506
1507
1508 <para>
1509 If the <emphasis>
1510 XkbXI_IndicatorMaps</emphasis>
1511  and / or <emphasis>
1512 XkbXI_IndicatorNamesMask</emphasis>
1513  bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb
1514 extension allows applications to assign maps and / or names to the indicators
1515 of nonkeyboard extension devices. If supported, maps and / or names can be
1516 assigned to all extension device indicators, whether they are part of a
1517 keyboard feedback or part of an indicator feedback.
1518 </para>
1519
1520
1521 <para>
1522 If the <emphasis>
1523 XkbXI_IndicatorMapsMask</emphasis>
1524  and / or <emphasis>
1525 XkbXI_IndicatorNamesMask</emphasis>
1526  flag is set in <emphasis>
1527 which</emphasis>
1528 , the indicator maps and / or names for all <emphasis>
1529 device_info</emphasis>
1530 -&gt;<emphasis>
1531 num_leds</emphasis>
1532  indicator devices specified in <emphasis>
1533 device_info</emphasis>
1534 -&gt;<emphasis>
1535 leds</emphasis>
1536  are set to the maps and / or names specified in <emphasis>
1537 device_info</emphasis>
1538 -&gt;<emphasis>
1539 leds</emphasis>
1540 . <emphasis>
1541 device_info</emphasis>
1542 -&gt;<emphasis>
1543 leds</emphasis>
1544 -&gt;<emphasis>
1545 led_class</emphasis>
1546  and <emphasis>
1547 led_id</emphasis>
1548  specify the input extension class and device ID for each indicator device to
1549 modify; if they have invalid values, a <emphasis>
1550 BadValue</emphasis>
1551  protocol error results and <emphasis>
1552 XkbSetDeviceInfo</emphasis>
1553  returns <emphasis>
1554 False</emphasis>
1555 . If they have legal values but do not specify a keyboard or indicator class
1556 feedback for the device in question, a <emphasis>
1557 BadMatch</emphasis>
1558  error results. If any of the values in <emphasis>
1559 device_info</emphasis>
1560 -&gt;<emphasis>
1561 leds</emphasis>
1562 <emphasis>
1563 -&gt;</emphasis>
1564 <emphasis>
1565 names</emphasis>
1566  are not a valid Atom or <emphasis>
1567 None</emphasis>
1568 , a <emphasis>
1569 BadAtom</emphasis>
1570  protocol error results.
1571 </para>
1572
1573
1574 <para>
1575 Xkb provides convenience functions to modify subsets of the information
1576 accessible via <emphasis>
1577 XkbSetDeviceInfo</emphasis>
1578 . Only the parts of the structure indicated in the function description are
1579 modified. These convenience functions are described as follows.
1580 </para>
1581
1582
1583 <para>
1584 To change only the button actions for an input extension device, use
1585 XkbSetDeviceButtonActions.
1586 </para>
1587
1588
1589 <informaltable frame='none'>
1590 <?dbfo keep-together="always" ?>
1591 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1592 <colspec colname='c1' colwidth='1.0*'/>
1593 <tbody>
1594   <row>
1595     <entry role='functiondecl'>
1596 Bool <emphasis>
1597 XkbSetDeviceButtonActions</emphasis>
1598 (<emphasis>
1599 dpy</emphasis>
1600 , device, first_button, num_buttons, actions)
1601     </entry>
1602   </row>
1603   <row>
1604     <entry role='functionargdecl'>
1605 Display *            <emphasis>
1606 dpy</emphasis>
1607 ;            /* connection to X server */
1608     </entry>
1609   </row>
1610   <row>
1611     <entry role='functionargdecl'>
1612 XkbDeviceInfoPtr            device_info;            /* structure defining the
1613 device and modifications */
1614     </entry>
1615   </row>
1616   <row>
1617     <entry role='functionargdecl'>
1618 unsigned int            first_button;            /* number of first button to
1619 update, 0 relative */
1620     </entry>
1621   </row>
1622   <row>
1623     <entry role='functionargdecl'>
1624 unsigned int            num_buttons;            /* number of buttons to update
1625 */
1626     </entry>
1627 </row>
1628 </tbody>
1629 </tgroup>
1630 </informaltable>
1631
1632 <para>
1633 <emphasis>
1634 XkbSetDeviceButtonActions</emphasis>
1635  assigns actions to the buttons of the device specified in
1636 device_info-&gt;<emphasis>
1637 device_spec</emphasis>
1638 . Actions are assigned to <emphasis>
1639 num_buttons</emphasis>
1640  buttons beginning with <emphasis>
1641 first_button</emphasis>
1642  and are taken from the actions specified in <emphasis>
1643 device_info</emphasis>
1644 -&gt;<emphasis>
1645 btn_acts</emphasis>
1646 .
1647 </para>
1648
1649
1650 <para>
1651 If the server does not support assignment of Xkb actions to extension device
1652 buttons, <emphasis>
1653 XkbSetDeviceButtonActions</emphasis>
1654  has no effect and returns <emphasis>
1655 False</emphasis>
1656 . If the device has no buttons or if <emphasis>
1657 first_button</emphasis>
1658  or <emphasis>
1659 num_buttons</emphasis>
1660  specify buttons outside of the valid range as determined by <emphasis>
1661 device_info</emphasis>
1662 -&gt;<emphasis>
1663 num_btns</emphasis>
1664 , the function has no effect and returns <emphasis>
1665 False</emphasis>
1666 . Otherwise, <emphasis>
1667 XkbSetDeviceButtonActions</emphasis>
1668  sends a request to the server to change the actions for the specified buttons
1669 and returns <emphasis>
1670 True</emphasis>
1671 .
1672 </para>
1673
1674
1675 <para>
1676 If the actual request sent to the server involved illegal button numbers, a
1677 <emphasis>
1678 BadValue</emphasis>
1679  protocol error is generated. If an invalid device identifier is specified in
1680 device_info-&gt;<emphasis>
1681 device_spec</emphasis>
1682 , a BadKeyboard protocol error results. If the actual device specified in
1683 <emphasis>
1684 device_info</emphasis>
1685 -&gt;<emphasis>
1686 device_spec</emphasis>
1687  does not contain buttons and a request affecting buttons is made, a <emphasis>
1688 BadMatch</emphasis>
1689  protocol error is generated.
1690 </para>
1691
1692
1693 </sect1>
1694 <sect1 id='XkbExtensionDeviceNotify_Event'>
1695 <title>XkbExtensionDeviceNotify Event</title>
1696
1697 <para>
1698 The Xkb extension generates <emphasis>
1699 XkbExtensionDeviceNotify</emphasis>
1700  events when the status of an input extension device changes or when an attempt
1701 is made to use an Xkb feature that is not supported by a particular device.
1702 </para>
1703
1704 <note><para>Events indicating an attempt to use an unsupported feature are
1705 delivered only to the client requesting the event.</para></note>
1706
1707 <para>
1708 To track changes to the status of input extension devices or attempts to use
1709 unsupported features of a device, select to receive <emphasis>
1710 XkbExtensionDeviceNotify</emphasis>
1711  events by calling either <emphasis>
1712 XkbSelectEvents</emphasis>
1713  or <emphasis>
1714 XkbSelectEventDetails</emphasis>
1715  (see section 4.3).
1716 </para>
1717
1718
1719 <para>
1720 To receive <emphasis>
1721 XkbExtensionDeviceNotify</emphasis>
1722  events under all possible conditions, call <emphasis>
1723 XkbSelectEvents</emphasis>
1724  and pass <emphasis>
1725 XkbExtensionDeviceNotifyMask</emphasis>
1726  in both <emphasis>
1727 bits_to_change</emphasis>
1728  and <emphasis>
1729 values_for_bits</emphasis>
1730 .
1731 </para>
1732
1733
1734 <para>
1735 The <emphasis>
1736 XkbExtensionDeviceNotify</emphasis>
1737  event has no event details. However, you can call <emphasis>
1738 XkbSelectEventDetails</emphasis>
1739  using <emphasis>
1740 XkbExtensionDeviceNotify</emphasis>
1741  as the <emphasis>
1742 event_type</emphasis>
1743  and specifying <emphasis>
1744 XkbAllExtensionDeviceMask</emphasis>
1745  in <emphasis>
1746 bits_to_change</emphasis>
1747  and <emphasis>
1748 values_for_bits.</emphasis>
1749  This has the same effect as a call to <emphasis>
1750 XkbSelectEvents</emphasis>
1751 .
1752 </para>
1753
1754
1755 <para>
1756 The structure for <emphasis>
1757 XkbExtensionDeviceNotify</emphasis>
1758  events is:
1759 </para>
1760
1761 <para><programlisting>
1762 typedef struct {
1763       int      type;           /* Xkb extension base event code */
1764       unsigned long  serial;   /* X server serial number for event */
1765       Bool     send_event;     /* <emphasis>True</emphasis>
1766                                   =&gt; synthetically generated*/
1767       Display *      display;  /* server connection where event generated */
1768       Time     time;           /* server time when event generated */
1769       int      xkb_type;  /* <emphasis>XkbExtensionDeviceNotifyEvent</emphasis> */
1770       int      device;         /* Xkb device ID, will not be
1771                                   <emphasis>XkbUseCoreKbd</emphasis> */
1772       unsigned int   reason;   /* reason for the event */
1773       unsigned int   supported;  /* mask of supported features */
1774       unsigned int   unsupported;  /* unsupported features this client
1775                                       attempted to use */
1776       int      first_btn;      /* first button that changed */
1777       int      num_btns;       /* number of buttons that changed */
1778       unsigned int   leds_defined;  /* indicators with names or maps */
1779       unsigned int       led_state; /* current state of the indicators */
1780       int       led_class;          /* feedback class for LED changes */
1781       int       led_id;             /* feedback ID for LED changes */
1782 } <emphasis>XkbExtensionDeviceNotifyEvent</emphasis>;
1783 </programlisting></para>
1784
1785 <para>
1786 The <emphasis>
1787 XkbExtensionDeviceNotify</emphasis>
1788  event has fields enabling it to report changes in the state (on/off) of all of
1789 the buttons for a device, but only for one LED feedback associated with a
1790 device. You will get multiple events when more than one LED feedback changes
1791 state or configuration.
1792 </para>
1793
1794
1795 </sect1>
1796 <sect1 id='Tracking_Changes_to_Extension_Devices'>
1797 <title>Tracking Changes to Extension Devices</title>
1798
1799 <para>
1800 Changes to an Xkb extension device may be tracked by listening to <emphasis>
1801 XkbDeviceExtensionNotify</emphasis>
1802  events and accumulating the changes in an <emphasis>
1803 XkbDeviceChangesRec</emphasis>
1804  structure. The changes noted in the structure may then be used in subsequent
1805 operations to update either a server configuration or a local copy of an Xkb
1806 extension device configuration. The changes structure is defined as follows:
1807 </para>
1808
1809 <para><programlisting>
1810 typedef struct _XkbDeviceChanges {
1811       unsigned int    changed;   /* bits indicating what has changed */
1812       unsigned short  first_btn; /* number of first button which changed,
1813                                     if any */
1814       unsigned short  num_btns;  /* number of buttons that have changed */
1815       XkbDeviceLedChangesRec leds;
1816 } <emphasis>XkbDeviceChangesRec</emphasis>,*XkbDeviceChangesPtr;
1817 </programlisting></para>
1818
1819 <para><programlisting>
1820 typedef struct _XkbDeviceLedChanges {
1821       unsigned short  led_class; /* class of this indicator feedback bundle */
1822       unsigned short  led_id;    /* ID of this indicator feedback bundle */
1823       unsigned int    names;     /* bits indicating which names have changed */
1824       unsigned int    maps;      /* bits indicating which maps have changed */
1825       struct _XkbDeviceLedChanges *next; /* link to indicator change record
1826                                             for next set */
1827 } <emphasis>XkbDeviceLedChangesRec</emphasis>,*XkbDeviceLedChangesPtr;
1828 </programlisting></para>
1829
1830 <para>
1831 A local description of the configuration and state of a device may be kept in
1832 an <emphasis>
1833 XkbDeviceInfoRec</emphasis>
1834  structure. The actual state or configuration of the device may change because
1835 of XkbSetDeviceInfo and XkbSetButtonActions requests made by clients or by user
1836 interaction with the device. The X server sends an XkbExtensionDeviceNotify
1837 event to all interested clients when the state of any buttons or indicators or
1838 the configuration of the buttons or indicators on the core keyboard or any
1839 input extension device changes. The event reports the state of indicators for a
1840 single indicator feedback, and the state of up to 128 buttons. If more than 128
1841 buttons or more than one indicator feedback are changed, the additional buttons
1842 and indicator feedbacks are reported in subsequent events. Xkb provides
1843 functions with which you can track changes to input extension devices by noting
1844 the changes that were made and then requesting the changed information from the
1845 server.
1846 </para>
1847
1848
1849 <para>
1850 To note device changes reported in an <emphasis>
1851 XkbExtensionDeviceNotify</emphasis>
1852  event, use XkbNoteDeviceChanges.
1853 </para>
1854
1855 <informaltable frame='none'>
1856 <?dbfo keep-together="always" ?>
1857 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1858 <colspec colname='c1' colwidth='1.0*'/>
1859 <tbody>
1860   <row>
1861     <entry role='functiondecl'>
1862 void <emphasis>
1863 XkbNoteDeviceChanges</emphasis>
1864  (<emphasis>
1865 old, new, wanted</emphasis>
1866 )
1867     </entry>
1868   </row>
1869   <row>
1870     <entry role='functionargdecl'>
1871 XkbDeviceChangesPtr                        <emphasis>
1872 old</emphasis>
1873 ;            /* structure tracking state changes */
1874     </entry>
1875   </row>
1876   <row>
1877     <entry role='functionargdecl'>
1878 XkbExtensionDeviceNotifyEvent             *            <emphasis>
1879 new</emphasis>
1880 ;            /* event indicating state changes */
1881     </entry>
1882   </row>
1883   <row>
1884     <entry role='functionargdecl'>
1885 unsigned int                        <emphasis>
1886 wanted</emphasis>
1887 ;            /* mask indicating changes to note */
1888     </entry>
1889 </row>
1890 </tbody>
1891 </tgroup>
1892 </informaltable>
1893
1894 <para>
1895 The wanted field specifies the changes that should be noted in <emphasis>
1896 old</emphasis>
1897 , and is composed of the bitwise inclusive OR of one or more of the masks from
1898 Table 21.1<emphasis>
1899 .</emphasis>
1900  The <emphasis>
1901 reason</emphasis>
1902  field of the event in <emphasis>
1903 new</emphasis>
1904  indicates the types of changes the event is reporting. <emphasis>
1905 XkbNoteDeviceChanges</emphasis>
1906  updates the <emphasis>
1907 XkbDeviceChangesRec</emphasis>
1908  specified by <emphasis>
1909 old</emphasis>
1910  with the changes that are both specified in <emphasis>
1911 wanted</emphasis>
1912  and contained in <emphasis>
1913 new</emphasis>
1914 -&gt;<emphasis>
1915 reason</emphasis>
1916 .
1917 </para>
1918
1919
1920 <para>
1921 To update a local copy of the state and configuration of an X input extension
1922 device with the changes previously noted in an <emphasis>
1923 XkbDeviceChangesRec</emphasis>
1924  structure, use XkbGetDeviceInfoChanges.
1925 </para>
1926
1927
1928 <para>
1929 To query the changes that have occurred in the button actions or indicator
1930 names and indicator maps associated with an input extension device, use
1931 XkbGetDeviceInfoChanges.
1932 </para>
1933
1934
1935 <informaltable frame='none'>
1936 <?dbfo keep-together="always" ?>
1937 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1938 <colspec colname='c1' colwidth='1.0*'/>
1939 <tbody>
1940   <row>
1941     <entry role='functiondecl'>
1942 Status <emphasis>
1943 XkbGetDeviceInfoChanges</emphasis>
1944 (<emphasis>
1945 dpy</emphasis>
1946 , <emphasis>
1947 device_info</emphasis>
1948 , changes)
1949     </entry>
1950   </row>
1951   <row>
1952     <entry role='functionargdecl'>
1953 Display *            <emphasis>
1954 dpy</emphasis>
1955 ;            /* connection to X server */
1956     </entry>
1957   </row>
1958   <row>
1959     <entry role='functionargdecl'>
1960 XkbDeviceInfoPtr            device_info;            /* structure to update with
1961 results */
1962     </entry>
1963   </row>
1964   <row>
1965     <entry role='functionargdecl'>
1966 XkbDeviceChangesPtr            <emphasis>
1967 changes</emphasis>
1968 ;            /* contains notes of changes that have occurred */
1969     </entry>
1970 </row>
1971 </tbody>
1972 </tgroup>
1973 </informaltable>
1974
1975 <para>
1976 The changes-&gt;changed field indicates which attributes of the device
1977 specified in <emphasis>
1978 changes</emphasis>
1979 -&gt;<emphasis>
1980 device</emphasis>
1981  have changed. The parameters describing the changes are contained in the other
1982 fields of <emphasis>
1983 changes</emphasis>
1984 . <emphasis>
1985 XkbGetDeviceInfoChanges</emphasis>
1986  uses that information to call XkbGetDeviceInfo to obtain the current status of
1987 those attributes that have changed. It then updates the local description of
1988 the device in <emphasis>
1989 device_info</emphasis>
1990  with the new information.
1991 </para>
1992
1993
1994 <para>
1995 To update the server’s description of a device with the changes noted in an
1996 XkbDeviceChangesRec, use XkbChangeDeviceInfo.
1997 </para>
1998
1999
2000 <informaltable frame='none'>
2001 <?dbfo keep-together="always" ?>
2002 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2003 <colspec colname='c1' colwidth='1.0*'/>
2004 <tbody>
2005   <row>
2006     <entry role='functiondecl'>
2007 Bool <emphasis>
2008 XkbChangeDeviceInfo</emphasis>
2009  (<emphasis>
2010 dpy, device_info, changes</emphasis>
2011 )
2012     </entry>
2013   </row>
2014   <row>
2015     <entry role='functionargdecl'>
2016 Display *            <emphasis>
2017 dpy</emphasis>
2018 ;            /* connection to X server */
2019     </entry>
2020   </row>
2021   <row>
2022     <entry role='functionargdecl'>
2023 XkbDeviceInfoPtr            <emphasis>
2024 device_info</emphasis>
2025 ;            /* local copy of device state and configuration */
2026     </entry>
2027   </row>
2028   <row>
2029     <entry role='functionargdecl'>
2030 XkbDeviceChangesPtr            <emphasis>
2031 changes</emphasis>
2032 ;            /* note specifying changes in <emphasis>
2033 device_info</emphasis>
2034  */
2035     </entry>
2036 </row>
2037 </tbody>
2038 </tgroup>
2039 </informaltable>
2040
2041 <para>
2042 <emphasis>
2043 XkbChangeDeviceInfo</emphasis>
2044  updates the server’s description of the device specified in <emphasis>
2045 device_info</emphasis>
2046 -&gt;<emphasis>
2047 device_spec</emphasis>
2048  with the changes specified in <emphasis>
2049 changes</emphasis>
2050  and contained in <emphasis>
2051 device_info</emphasis>
2052 . The update is made by an XkbSetDeviceInfo request.
2053 </para>
2054
2055 </sect1>
2056 </chapter>