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