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