1 2<chapter id='XKB_Protocol_Requests'> 3<title>XKB Protocol Requests</title> 4 5<para> 6This document uses the syntactic conventions and common types defined by the 7specification of the core X protocol with a number of additions, which are 8detailed below. 9</para> 10 11<sect1 id='Errors'> 12<title>Errors</title> 13 14<para> 15If a client attempts to use any other XKB request except <emphasis> 16XkbUseExtension</emphasis> 17 before the extension is properly initialized, XKB reports an <emphasis> 18Access</emphasis> 19 error and ignores the request. XKB is properly initialized once <emphasis> 20XkbUseExtension</emphasis> 21 reports that the client has asked for a supported or compatible version of the 22extension. 23</para> 24 25 26<sect2 id='Keyboard_Errors'> 27<title>Keyboard Errors</title> 28 29<para> 30In addition to all of the errors defined by the core protocol, the X Keyboard 31Extension defines a single error, <emphasis> 32Keyboard</emphasis> 33, which indicates that some request specified an illegal device identifier or 34an extension device that is not a member of an appropriate. Unless otherwise 35noted, any request with an argument of type KB_DEVICESPEC can cause <emphasis> 36Keyboard</emphasis> 37 errors if an illegal or inappropriate device is specified. 38</para> 39 40 41<para> 42When the extension reports a Keyboard error, the most significant byte of the 43<emphasis> 44resource_id</emphasis> 45 is a further refinement of the error cause, as defined in the table below. The 46least significant byte contains the device, class, or feedback id as indicated: 47</para> 48 49<informaltable frame='topbot'> 50<?dbfo keep-together="always" ?> 51<tgroup cols='4' align='left' colsep='0' rowsep='0'> 52<colspec colname='c1' colwidth='2.0*'/> 53<colspec colname='c2' colwidth='1.0*'/> 54<colspec colname='c3' colwidth='3.0*'/> 55<colspec colname='c4' colwidth='2.0*'/> 56<thead> 57 <row rowsep='1'> 58 <entry>high-order byte</entry> 59 <entry>value</entry> 60 <entry>meaning</entry> 61 <entry>low-order byte</entry> 62 </row> 63</thead> 64<tbody> 65 <row> 66 <entry>XkbErr_BadDevice</entry> 67 <entry>0xff</entry> 68 <entry>device not found</entry> 69 <entry>device id</entry> 70 </row> 71 <row> 72 <entry>XkbErr_BadClass</entry> 73 <entry>0xfe</entry> 74 <entry>device found, but is the wrong class</entry> 75 <entry>class id</entry> 76 </row> 77 <row> 78 <entry>XkbErr_BadId</entry> 79 <entry>0xfd</entry> 80 <entry>device found, class ok, but device does not have a feedback with the 81indicated id</entry> 82 <entry>feedback id</entry> 83 </row> 84</tbody> 85</tgroup> 86</informaltable> 87 88</sect2> 89<sect2 id='Side_Effects_of_Errors'> 90<title>Side-Effects of Errors</title> 91 92<para> 93With the exception of <emphasis> 94Alloc</emphasis> 95 or <emphasis> 96Implementation</emphasis> 97 errors, which might result in an inconsistent internal state, no XKB request 98that reports an error condition has any effect. Unless otherwise stated, 99requests which update some aspect of the keyboard description will not apply 100only part of a request — if part of a request fails, the whole thing is 101ignored. 102</para> 103 104 105</sect2> 106</sect1> 107<sect1 id='Common_Types'> 108<title>Common Types</title> 109 110<para> 111The following types are used in the request and event definitions in subsequent 112sections: 113</para> 114 115<informaltable frame='topbot'> 116<?dbfo keep-together="auto" ?> 117<tgroup cols='2' align='left' colsep='0' rowsep='0'> 118<colspec colname='c1' colwidth='1.0*'/> 119<colspec colname='c2' colwidth='2.0*'/> 120<thead> 121 <row rowsep='1'> 122 <entry>Name</entry> 123 <entry>Value</entry> 124 </row> 125</thead> 126<tbody> 127 <row> 128 <entry>LISTofITEMs</entry> 129 <entry> The type LISTofITEMs is special. It is similar to the 130LISTofVALUE defined by the core protocol, but the elements of a LISTofITEMs are 131not necessarily all the same size. The use of a BITMASK to indicate which 132members are present is optional for a LISTofITEMs — it is possible for the 133set of elements to be derived from one or more fields of the request.</entry> 134 </row> 135 <row> 136 <entry>KB_DEVICESPEC</entry> 137 <entry>8 bit unsigned integer, <emphasis> 138UseCoreKbd, or UseCorePtr</emphasis> 139</entry> 140 </row> 141 <row> 142 <entry>KB_LEDCLASSSPEC</entry> 143 <entry>{ <emphasis> 144KbdFeedbackClass</emphasis> 145, <emphasis> 146LedFeedbackClass</emphasis> 147, <emphasis> 148DfltXIClass</emphasis> 149, <emphasis> 150AllXIClasses</emphasis> 151, <emphasis> 152XINone</emphasis> 153 }</entry> 154 </row> 155 <row> 156 <entry>KB_BELLCLASSSPEC</entry> 157 <entry>{ <emphasis> 158KbdFeedbackClass</emphasis> 159, <emphasis> 160BellFeedbackClass</emphasis> 161, <emphasis> 162DfltXIClass</emphasis> 163, <emphasis> 164AllXIClasses</emphasis> 165 }</entry> 166 </row> 167 <row> 168 <entry>KB_IDSPEC</entry> 169 <entry>8 bit unsigned integer or <emphasis> 170DfltXIId</emphasis> 171</entry> 172 </row> 173 <row> 174 <entry>KB_VMODMASK</entry> 175 <entry> CARD16, each bit corresponds to a virtual modifier</entry> 176 </row> 177 <row> 178 <entry>KB_GROUPMASK</entry> 179 <entry>{ <emphasis> 180Group1</emphasis> 181, <emphasis> 182Group2</emphasis> 183, <emphasis> 184Group3</emphasis> 185, <emphasis> 186Group4</emphasis> 187 }</entry> 188 </row> 189 <row> 190 <entry>KB_GROUPSWRAP</entry> 191 <entry>{ <emphasis> 192WrapIntoRange</emphasis> 193, <emphasis> 194ClampIntoRange</emphasis> 195, <emphasis> 196RedirectIntoRange</emphasis> 197 }</entry> 198 </row> 199 <row> 200 <entry>KB_GROUPINFO</entry> 201 <entry>{ groupsWrap: KB_GROUPSWRAP 202redirectGroup: 1…4, 203numGroups: 1…4 }</entry> 204 </row> 205 <row> 206 <entry>KB_NKNDETAILSMASK</entry> 207 <entry>{ <emphasis> 208NKN_Keycodes</emphasis> 209, NKN_Geometry, <emphasis> 210NKN_DeviceID</emphasis> 211 }</entry> 212 </row> 213 <row> 214 <entry>KB_STATEMASK</entry> 215 <entry> KEYBUTMASK or KB_GROUPMASK</entry> 216 </row> 217 <row> 218 <entry>KB_STATEPARTMASK</entry> 219 <entry>{ <emphasis> 220ModifierState</emphasis> 221, <emphasis> 222ModifierBase</emphasis> 223, <emphasis> 224ModifierLatch</emphasis> 225, <emphasis> 226ModifierLock</emphasis> 227, <emphasis> 228GroupState</emphasis> 229, <emphasis> 230GroupBase</emphasis> 231, <emphasis> 232GroupLatch</emphasis> 233, <emphasis> 234GroupLock</emphasis> 235, <emphasis> 236CompatState</emphasis> 237, <emphasis> 238GrabMods</emphasis> 239, <emphasis> 240CompatGrabMods</emphasis> 241, <emphasis> 242LookupMods</emphasis> 243, <emphasis> 244CompatLookupMods</emphasis> 245, <emphasis> 246PointerButtons</emphasis> 247 }</entry> 248 </row> 249 <row> 250 <entry>KB_BOOLCTRLMASK</entry> 251 <entry>{ <emphasis> 252RepeatKeys</emphasis> 253, <emphasis> 254SlowKeys</emphasis> 255, <emphasis> 256BounceKeys</emphasis> 257, <emphasis> 258StickyKeys</emphasis> 259, <emphasis> 260MouseKeys</emphasis> 261, <emphasis> 262MouseKeysAccel</emphasis> 263, <emphasis> 264AccessXKeys</emphasis> 265, <emphasis> 266AccessXTimeout</emphasis> 267, <emphasis> 268AccessXFeedback</emphasis> 269, <emphasis> 270AudibleBell</emphasis> 271, <emphasis> 272Overlay1</emphasis> 273, <emphasis> 274Overlay2</emphasis> 275, <emphasis> 276IgnoreGroupLock</emphasis> 277 }</entry> 278 </row> 279 <row> 280 <entry>KB_CONTROLSMASK</entry> 281 <entry>{ <emphasis> 282GroupsWrap, InternalMods</emphasis> 283, <emphasis> 284IgnoreLockMods</emphasis> 285, <emphasis> 286PerKeyRepeat</emphasis> 287, <emphasis> 288ControlsEnabled</emphasis> 289 } or KB_BOOLCTRLMASK</entry> 290 </row> 291 <row> 292 <entry>KB_MAPPARTMASK</entry> 293 <entry>{ <emphasis> 294KeyTypes</emphasis> 295, <emphasis> 296KeySyms</emphasis> 297, <emphasis> 298ModifierMap</emphasis> 299, <emphasis> 300ExplicitComponents</emphasis> 301, <emphasis> 302KeyActions</emphasis> 303, <emphasis> 304KeyBehaviors</emphasis> 305, <emphasis> 306VirtualMods</emphasis> 307, <emphasis> 308VirtualModMap</emphasis> 309}</entry> 310 </row> 311 <row> 312 <entry>KB_CMDETAILMASK</entry> 313 <entry>{ <emphasis> 314SymInterp</emphasis> 315, <emphasis> 316GroupCompat</emphasis> 317 }</entry> 318 </row> 319 <row> 320 <entry>KB_NAMEDETAILMASK</entry> 321 <entry>{ <emphasis> 322KeycodesName</emphasis> 323, <emphasis> 324GeometryName</emphasis> 325, <emphasis> 326SymbolsName</emphasis> 327, 328 <emphasis> 329PhysSymbolsName</emphasis> 330, <emphasis> 331TypesName</emphasis> 332, <emphasis> 333CompatName</emphasis> 334, <emphasis> 335KeyTypeNames</emphasis> 336, <emphasis> 337KTLevelNames</emphasis> 338, <emphasis> 339IndicatorNames</emphasis> 340, <emphasis> 341KeyNames</emphasis> 342, <emphasis> 343KeyAliases</emphasis> 344, <emphasis> 345VirtualModNames</emphasis> 346, <emphasis> 347GroupNames</emphasis> 348, <emphasis> 349RGNames</emphasis> 350}</entry> 351 </row> 352 <row> 353 <entry>KB_AXNDETAILMASK</entry> 354 <entry>{ <emphasis> 355AXN_SKPress</emphasis> 356, <emphasis> 357AXN_SKAccept</emphasis> 358, <emphasis> 359AXN_SKReject</emphasis> 360, <emphasis> 361AXN_SKRelease, AXN_BKAccept, AXN_BKReject, AXN_AXKWarning </emphasis> 362}</entry> 363 </row> 364 <row> 365 <entry>KB_AXSKOPTSMASK</entry> 366 <entry>{ <emphasis> 367AX_TwoKeys</emphasis> 368, <emphasis> 369AX_LatchToLock</emphasis> 370 }</entry> 371 </row> 372 <row> 373 <entry>KB_AXFBOPTSMASK</entry> 374 <entry>{ <emphasis> 375AX_SKPressFB</emphasis> 376, <emphasis> 377AX_SKAcceptFB</emphasis> 378, <emphasis> 379AX_FeatureFB</emphasis> 380, <emphasis> 381AX_SlowWarnFB</emphasis> 382, <emphasis> 383AX_IndicatorFB</emphasis> 384, <emphasis> 385AX_StickyKeysFB</emphasis> 386, <emphasis> 387AX_SKReleaseFB</emphasis> 388,<emphasis> 389 AX_SKRejectFB</emphasis> 390, <emphasis> 391AX_BKRejectFB</emphasis> 392, <emphasis> 393AX_DumbBellFB</emphasis> 394 }</entry> 395 </row> 396 <row> 397 <entry>KB_AXOPTIONSMASK</entry> 398 <entry> KB_AXFBOPTSMASK or KB_AXSKOPTSMASK</entry> 399 </row> 400 <row> 401 <entry>KB_GBNDETAILMASK</entry> 402 <entry>{ <emphasis> 403GBN_Types</emphasis> 404, <emphasis> 405GBN_CompatMap</emphasis> 406, <emphasis> 407GBN_ClientSymbols</emphasis> 408, <emphasis> 409GBN_ServerSymbols</emphasis> 410, <emphasis> 411GBN_IndicatorMap</emphasis> 412, <emphasis> 413GBN_KeyNames</emphasis> 414, <emphasis> 415GBN_Geometry</emphasis> 416, <emphasis> 417GBN_OtherNames</emphasis> 418 }</entry> 419 </row> 420 <row> 421 <entry>KB_BELLDETAILMASK</entry> 422 <entry>{ <emphasis> 423XkbAllBellNotifyEvents</emphasis> 424 }</entry> 425 </row> 426 <row> 427 <entry>KB_MSGDETAILMASK</entry> 428 <entry>{ <emphasis> 429XkbAllActionMessages</emphasis> 430 }</entry> 431 </row> 432 <row> 433 <entry>KB_EVENTTYPE</entry> 434 <entry>{ <emphasis> 435XkbNewKeyboardNotify</emphasis> 436, <emphasis> 437XkbMapNotify</emphasis> 438, <emphasis> 439XkbStateNotify</emphasis> 440, <emphasis> 441XkbControlsNotify</emphasis> 442, <emphasis> 443XkbIndicatorStateNotify</emphasis> 444, <emphasis> 445XkbIndicatorMapNotify</emphasis> 446, <emphasis> 447XkbNamesNotify</emphasis> 448, <emphasis> 449XkbCompatMapNotify</emphasis> 450, <emphasis> 451XkbBellNotify</emphasis> 452, <emphasis> 453XkbActionMessage</emphasis> 454, <emphasis> 455XkbAccessXNotify</emphasis> 456, <emphasis> 457XkbExtensionDeviceNotify</emphasis> 458 }</entry> 459 </row> 460 <row> 461 <entry>KB_ACTION</entry> 462 <entry>[ type: CARD8 463data: LISTofCARD8 ]</entry> 464 </row> 465 <row> 466 <entry>KB_BEHAVIOR</entry> 467 <entry>[ type: CARD8, data: CARD 8 ]</entry> 468 </row> 469 <row> 470 <entry>KB_MODDEF</entry> 471 <entry>[ mask: KEYMASK, 472mods: KEYMASK, 473vmods: KB_VMODMASK ]</entry> 474 </row> 475 <row> 476 <entry>KB_KTMAPENTRY</entry> 477 <entry>[ active: BOOL, 478level: CARD8, 479mods: KB_MODDEF ]</entry> 480 </row> 481 <row> 482 <entry>KB_KTSETMAPENTRY</entry> 483 <entry>[ level: CARD8, 484mods: KB_MODDEF ]</entry> 485 </row> 486 <row> 487 <entry>KB_KEYTYPE</entry> 488 <entry>[ mods: KB_MODDEF, 489numLevels: CARD8, 490map: LISTofKB_KTMAPENTRY, 491preserve: LISTofKB_MODDEF ]</entry> 492 </row> 493 <row> 494 <entry>KB_SETKEYTYPE</entry> 495 <entry>[ realMods: KEYMASK, 496vmods: CARD16, 497numLevels: CARD8, 498map: LISTofKB_KTSETMAPENTRY, 499preserve: LISTofKB_MODDEF ]</entry> 500 </row> 501 <row> 502 <entry>KB_KEYSYMMAP</entry> 503 <entry>[ ktIndex: LISTofCARD8, width: CARD8 504 numGroups: 0…4, 505 groupsWrap: KB_GROUPSWRAP, 506 redirectGroup: 0…3, 507 syms: LISTofKEYSYM ]</entry> 508 </row> 509 <row> 510 <entry>KB_KEYVMODMAP</entry> 511 <entry>[ key: KEYCODE, vmods: CARD16 ]</entry> 512 </row> 513 <row> 514 <entry>KB_KEYMODMAP</entry> 515 <entry>[ key: KEYCODE, mods: KEYMASK ]</entry> 516 </row> 517 <row> 518 <entry>KB_EXPLICITMASK</entry> 519 <entry>{ <emphasis> 520ExplicitKeyType1</emphasis> 521, <emphasis> 522ExplicitKeyType2</emphasis> 523, <emphasis> 524ExplicitKeyType3</emphasis> 525, <emphasis> 526ExplicitKeyType4</emphasis> 527, <emphasis> 528ExplicitInterpret</emphasis> 529, <emphasis> 530ExplicitAutoRepeat</emphasis> 531, <emphasis> 532ExplicitBehavior</emphasis> 533, <emphasis> 534ExplicitVModMap</emphasis> 535 }</entry> 536 </row> 537 <row> 538 <entry>KB_INDICATORMASK</entry> 539 <entry> CARD32, each bit corresponds to an indicator</entry> 540 </row> 541 <row> 542 <entry>KB_IMFLAGS</entry> 543 <entry>{ <emphasis> 544IM_NoExplicit</emphasis> 545, <emphasis> 546IM_NoAutomatic</emphasis> 547, <emphasis> 548IM_LEDDrivesKB</emphasis> 549 }</entry> 550 </row> 551 <row> 552 <entry>KB_IMMODSWHICH</entry> 553 <entry>{ <emphasis> 554IM_UseNone</emphasis> 555, <emphasis> 556IM_UseBase</emphasis> 557, <emphasis> 558IM_UseLatched</emphasis> 559, <emphasis> 560IM_UseLocked</emphasis> 561, <emphasis> 562IM_UseEffective</emphasis> 563, <emphasis> 564IM_UseCompat</emphasis> 565 }</entry> 566 </row> 567 <row> 568 <entry>KB_IMGROUPSWHICH</entry> 569 <entry>{ <emphasis> 570IM_UseNone</emphasis> 571, <emphasis> 572IM_UseBase</emphasis> 573, <emphasis> 574IM_UseLatched</emphasis> 575, <emphasis> 576IM_UseLocked</emphasis> 577, <emphasis> 578IM_UseEffective</emphasis> 579 }</entry> 580 </row> 581 <row> 582 <entry>KB_INDICATORMAP</entry> 583 <entry>[ flags: CARD8, 584mods: KB_MODDEF, 585whichMods: 586groups: KB_GROUPMASK, 587whichGroups: 588ctrls: KB_BOOLCTRLMASK ]</entry> 589 </row> 590 <row> 591 <entry>KB_SYMINTERPMATCH</entry> 592 <entry>{ <emphasis> 593SI_NoneOf</emphasis> 594, <emphasis> 595SI_AnyOfOrNone</emphasis> 596, <emphasis> 597SI_AnyOf</emphasis> 598, <emphasis> 599SI_AllOf</emphasis> 600, <emphasis> 601SI_Exactly</emphasis> 602 }</entry> 603 </row> 604 <row> 605 <entry>KB_SYMINTERP</entry> 606 <entry>[ sym: KEYSYM, 607 mods; KEYMASK, 608 levelOneOnly: BOOL, 609 match: KB_SYMINTERPMATCH, 610 virtualMod: CARD8, 611 autoRepeat: BOOL, 612 lockingKey: BOOL ]</entry> 613 </row> 614 <row> 615 <entry>KB_PCFMASK</entry> 616 <entry>{ <emphasis> 617PCF_DetectableAutorepeat</emphasis> 618, <emphasis> 619PCF_GrabsUseXkbState</emphasis> 620, <emphasis> 621PCF_AutoResetControls</emphasis> 622, <emphasis> 623PCF_LookupStateWhenGrabbed</emphasis> 624, <emphasis> 625PCF_SendEventUsesXKBState</emphasis> 626 }</entry> 627 </row> 628 <row> 629 <entry>KB_LCFLAGSMASK</entry> 630 <entry>{ <emphasis> 631LC_Hidden</emphasis> 632, <emphasis> 633LC_Default</emphasis> 634, <emphasis> 635LC_Partial</emphasis> 636 }</entry> 637 </row> 638 <row> 639 <entry>KB_LCSYMFLAGSMASK</entry> 640 <entry>{ <emphasis> 641LC_AlphanumericKeys</emphasis> 642, <emphasis> 643LC_ModifierKeys</emphasis> 644, <emphasis> 645LC_KeypadKeys</emphasis> 646, <emphasis> 647LC_FunctionKeys</emphasis> 648, <emphasis> 649LC_AlternateGroup</emphasis> 650 }</entry> 651 </row> 652</tbody> 653</tgroup> 654</informaltable> 655 656<para> 657These types are used by the <emphasis> 658XkbGetGeometry</emphasis> 659 and <emphasis> 660XkbSetGeometry</emphasis> 661 requests: 662</para> 663 664<informaltable frame='topbot'> 665<?dbfo keep-together="auto" ?> 666<tgroup cols='2' align='left' colsep='0' rowsep='0'> 667<colspec colname='c1' colwidth='1.0*'/> 668<colspec colname='c2' colwidth='2.0*'/> 669<thead> 670 <row rowsep='1'> 671 <entry>Name</entry> 672 <entry>Value</entry> 673 </row> 674</thead> 675<tbody> 676 <row> 677 <entry>KB_PROPERTY</entry> 678 <entry>[ name, value: STRING8 ]</entry> 679 </row> 680 <row> 681 <entry>KB_POINT</entry> 682 <entry>[ x, y: CARD16 ]</entry> 683 </row> 684 <row> 685 <entry>KB_OUTLINE</entry> 686 <entry>[ cornerRadius: CARD8, points: LISTofKB_POINT ]</entry> 687 </row> 688 <row> 689 <entry>KB_SHAPE</entry> 690 <entry>[ name: ATOM, outlines: LISTofKB_OUTLINE 691 primaryNdx, approxNdx: CARD8 ]</entry> 692 </row> 693 <row> 694 <entry>KB_KEYNAME</entry> 695 <entry>[ name: LISTofCHAR ]</entry> 696 </row> 697 <row> 698 <entry>KB_KEYALIAS</entry> 699 <entry>[ real: LISTofCHAR, alias: LISTofCHAR ]</entry> 700 </row> 701 <row> 702 <entry>KB_KEY</entry> 703 <entry>[ name: KB_KEYNAME, gap: INT16, 704 shapeNdx, colorNdx: CARD8 ]</entry> 705 </row> 706 <row> 707 <entry>KB_ROW</entry> 708 <entry>[ top, left: INT16, vertical: BOOL, keys LISTofKB_KEY ]</entry> 709 </row> 710 <row> 711 <entry>KB_OVERLAYKEY</entry> 712 <entry>[ over, under: KB_KEYNAME ]</entry> 713 </row> 714 <row> 715 <entry>KB_OVERLAYROW</entry> 716 <entry>[ rowUnder: CARD8, keys: LISTofKB_OVERLAYKEY ]</entry> 717 </row> 718 <row> 719 <entry>KB_OVERLAY</entry> 720 <entry>[ sectionUnder: CARD8, 721rows: LISTofKB_OVERLAYROW ]</entry> 722 </row> 723 <row> 724 <entry>KB_SHAPEDOODAD</entry> 725 <entry>[ name: ATOM, priority: CARD8, top, left: INT16, 726 type: { SolidDoodad, OutlineDoodad }, 727 angle: INT16, width, height: CARD16 728 colorNdx, shapeNdx: CARD8 ]</entry> 729 </row> 730 <row> 731 <entry>KB_TEXTDOODAD</entry> 732 <entry>[ name: ATOM, priority: CARD8, top, left: INT16, 733 angle: INT16, width, height: CARD16, 734 colorNdx: CARD8, text: STRING8, font: STRING8 ]</entry> 735 </row> 736 <row> 737 <entry>KB_INDICATORDOODAD</entry> 738 <entry>[ name: ATOM, priority: CARD8, top, left: INT16, 739angle: INT16, 740shapeNdx, onColorNdx, offColorNdx: CARD8 ]</entry> 741 </row> 742 <row> 743 <entry>KB_LOGODOODAD</entry> 744 <entry>[ name: ATOM, priority: CARD8, top, left: INT16, 745 angle: INT16, colorNdx, shapeNdx: CARD8, 746 logoName: STRING8 ]</entry> 747 </row> 748 <row> 749 <entry>KB_DOODAD</entry> 750 <entry>KB_SHAPEDOODAD, or KB_TEXTDOODAD, or KB_INDICATORDOODAD, or 751KB_LOGODOODAD</entry> 752 </row> 753 <row> 754 <entry>KB_SECTION</entry> 755 <entry>[ name: ATOM, 756 top, left, angle: INT16, 757 width, height: CARD16, 758 priority: CARD8, 759 rows: LISTofKB_ROW, 760 doodads: LISTofKB_DOODAD, 761 overlays: LISTofKB_OVERLAY ]</entry> 762 </row> 763</tbody> 764</tgroup> 765</informaltable> 766 767<para> 768These types are used by <emphasis> 769XkbGetDeviceInfo</emphasis> 770 and <emphasis> 771XkbSetDeviceInfo</emphasis> 772: 773</para> 774 775<informaltable frame='topbot'> 776<?dbfo keep-together="always" ?> 777<tgroup cols='2' align='left' colsep='0' rowsep='0'> 778<colspec colname='c1' colwidth='1.0*'/> 779<colspec colname='c2' colwidth='2.0*'/> 780<thead> 781 <row rowsep='1'> 782 <entry>Name</entry> 783 <entry>Value</entry> 784 </row> 785</thead> 786<tbody> 787 <row> 788 <entry>KB_XIDEVFEATUREMASK</entry> 789 <entry>{ <emphasis> 790XI_ButtonActions</emphasis> 791, <emphasis> 792XI_IndicatorNames</emphasis> 793, <emphasis> 794XI_IndicatorMaps</emphasis> 795, <emphasis> 796XI_IndicatorState</emphasis> 797 }</entry> 798 </row> 799 <row> 800 <entry>KB_XIFEATUREMASK</entry> 801 <entry>{ KB_XIDEVFEATURES or <emphasis> 802XI_Keyboards</emphasis> 803</entry> 804 </row> 805 <row> 806 <entry>KB_XIDETAILMASK</entry> 807 <entry> { KB_XIFEATURES or <emphasis> 808XI_UnsupportedFeature</emphasis> 809 <emphasis> 810}</emphasis> 811</entry> 812 </row> 813 <row> 814 <entry>KB_DEVICELEDINFO</entry> 815 <entry>[ ledClass: KB_LEDCLASSSPEC, 816ledID: KB_IDSPEC, 817physIndicators: CARD32, 818state: CARD32, 819names: LISTofATOM, 820maps: LISTofKB_INDICATORMAP ]</entry> 821 </row> 822</tbody> 823</tgroup> 824</informaltable> 825 826</sect1> 827<sect1 id='Requests'> 828<title>Requests</title> 829 830<para> 831This section lists all of the requests supported by the X Keyboard Extension, 832separated into categories of related requests. 833</para> 834 835 836<sect2 id='Initializing_the_X_Keyboard_Extension'> 837<title>Initializing the X Keyboard Extension</title> 838 839 840<informaltable frame='none' tabstyle='proto'> 841<?dbfo keep-together="always" ?> 842<tgroup cols='1' align='left' colsep='0' rowsep='0'> 843<colspec colname='c1' colwidth='1.0*'/> 844 <thead> 845 <row> 846 <entry role='protoname'>XkbUseExtension</entry> 847 </row> 848 </thead> 849 <tbody> 850 <row> 851 <entry role='protoargs'>wantedMajor, wantedMinor: CARD16</entry> 852 </row> 853 <row> 854 <entry role='protoreply'> 855supported: BOOL 856 </entry> 857 </row> 858 <row> 859 <entry role='protoreply'> 860serverMajor, serverMinor: CARD16</entry> 861 </row> 862 </tbody> 863 </tgroup> 864</informaltable> 865 866<para> 867This request enables XKB extension capabilities for the client that issues the 868request; the <emphasis> 869wantedMajor</emphasis> 870 and <emphasis> 871wantedMinor</emphasis> 872 fields specify the extension version in use by the requesting client. The 873<emphasis> 874supported</emphasis> 875 field is <emphasis> 876True</emphasis> 877 if the server supports a compatible version, <emphasis> 878False</emphasis> 879 otherwise. The <emphasis> 880serverMajor</emphasis> 881 and <emphasis> 882serverMinor</emphasis> 883 fields return the actual version supported by the server. 884</para> 885 886 887<para> 888Until a client explicitly and successfully requests the XKB extension, an XKB 889capable server reports compatibility state in all core protocol events and 890requests. Once a client asks for XKB extension semantics by issuing this 891request, the server reports the extended XKB keyboard state in some core 892protocol events and requests, as described in the overview section of this 893specification. 894</para> 895 896 897<para> 898Clients should issue an <emphasis> 899XkbUseExtension</emphasis> 900 request before using any other extension requests. 901</para> 902 903 904</sect2> 905<sect2 id='Selecting_Events'> 906<title>Selecting Events</title> 907 908 909<informaltable frame='none' tabstyle='proto'> 910<?dbfo keep-together="always" ?> 911<tgroup cols='1' align='left' colsep='0' rowsep='0'> 912<colspec colname='c1' colwidth='1.0*'/> 913 <thead> 914 <row> 915 <entry role='protoname'>XkbSelectEvents</entry> 916 </row> 917 </thead> 918 <tbody> 919 <row> 920 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 921 </row> 922 <row> 923 <entry role='protoname'> 924affectWhich, clear, selectAll: KB_EVENTTYPE</entry> 925 </row> 926 <row> 927 <entry role='protoname'> 928affectMap, map: KB_MAPPARTMASK</entry> 929 </row> 930 <row> 931 <entry role='protoname'> 932details: LISTofITEMs</entry> 933 </row> 934 935 <row> 936 <entry role='protoerror'>Errors: <emphasis> 937Keyboard</emphasis> 938, <emphasis> 939Match</emphasis> 940, <emphasis> 941Value</emphasis> 942</entry> 943 </row> 944 945 </tbody> 946 </tgroup> 947</informaltable> 948 949<para> 950This request updates the event masks of the keyboard indicated by <emphasis> 951deviceSpec</emphasis> 952 for this client. If <emphasis> 953deviceSpec</emphasis> 954 specifies an illegal device, a <emphasis> 955Keyboard</emphasis> 956 error results. 957</para> 958 959 960<para> 961The <emphasis> 962affectMap</emphasis> 963 and <emphasis> 964map</emphasis> 965 fields specify changes to the event details mask for the <emphasis> 966XkbMapNotify</emphasis> 967 event. If any map components are set in <emphasis> 968map</emphasis> 969 but not in <emphasis> 970affectMap</emphasis> 971, a <emphasis> 972Match</emphasis> 973 error results. Otherwise, any map components that are set in <emphasis> 974affectMap</emphasis> 975 are set or cleared in the map notify details mask, depending on the value of 976the corresponding field in <emphasis> 977map</emphasis> 978. 979</para> 980 981 982<para> 983The <emphasis> 984affectWhich</emphasis> 985, <emphasis> 986clear</emphasis> 987, and <emphasis> 988selectAll</emphasis> 989 fields specify changes to any other event details masks. If any event types 990are set in both <emphasis> 991clear</emphasis> 992 and <emphasis> 993selectAll</emphasis> 994, a <emphasis> 995Match</emphasis> 996 error results; if any event types are specified in either <emphasis> 997clear</emphasis> 998 or <emphasis> 999selectAll</emphasis> 1000 but not in <emphasis> 1001affectWhich</emphasis> 1002, a <emphasis> 1003Match</emphasis> 1004 error results. Otherwise, the detail masks for any event types specified in 1005the <emphasis> 1006affectWhich</emphasis> 1007 field of this request are changed as follows: 1008</para> 1009 1010<itemizedlist> 1011<listitem> 1012 <para>If the event type is also set in <emphasis> 1013clear</emphasis> 1014, the detail mask for the corresponding event is set to <emphasis> 10150</emphasis> 1016 or <emphasis> 1017False</emphasis> 1018, as appropriate. 1019 </para> 1020</listitem> 1021<listitem> 1022 <para>If the event type is also set in <emphasis> 1023selectAll</emphasis> 1024, the detail mask for the corresponding event is set to include all legal 1025detail values for that type. 1026 </para> 1027</listitem> 1028<listitem> 1029 <para>If the event type is not set in either <emphasis> 1030clear</emphasis> 1031 or <emphasis> 1032selectAll</emphasis> 1033, the corresponding element of <emphasis> 1034details</emphasis> 1035 lists a set of explicit changes to the details mask for the event, as 1036described below. 1037 </para> 1038</listitem> 1039</itemizedlist> 1040 1041<para> 1042Each entry of the <emphasis> 1043details</emphasis> 1044 list specifies changes to the event details mask for a single type of event, 1045and consists of an <emphasis> 1046affects</emphasis> 1047 mask and a <emphasis> 1048values</emphasis> 1049 mask. All details that are specified in <emphasis> 1050affects</emphasis> 1051 are set to the corresponding value from <emphasis> 1052values</emphasis> 1053; if any details are listed in <emphasis> 1054values</emphasis> 1055 but not in <emphasis> 1056affects</emphasis> 1057, a <emphasis> 1058Match</emphasis> 1059 error results. 1060</para> 1061 1062 1063<para> 1064The details list contains entries only for those event types, if any, that are 1065listed in the <emphasis> 1066affectWhich</emphasis> 1067 mask and not in either <emphasis> 1068clear</emphasis> 1069 or <emphasis> 1070selectAll</emphasis> 1071. When present, the items of the <emphasis> 1072details</emphasis> 1073 list appear in the following order: 1074</para> 1075 1076<informaltable frame='none'> 1077<?dbfo keep-together="auto" ?> 1078<tgroup cols='3' align='left' colsep='0' rowsep='0'> 1079<colspec colname='c1' colwidth='1.0*'/> 1080<colspec colname='c2' colwidth='1.0*'/> 1081<colspec colname='c3' colwidth='1.0*'/> 1082<thead> 1083 <row rowsep='1'> 1084 <entry>Event Type</entry> 1085 <entry>Legal Details</entry> 1086 <entry>Type</entry> 1087 </row> 1088</thead> 1089<tbody> 1090 <row> 1091 <entry><emphasis> 1092XkbNewKeyboardNotify</emphasis> 1093</entry> 1094 <entry><emphasis> 1095KB_NKNDETAILSMASK</emphasis> 1096</entry> 1097 <entry><emphasis> 1098CARD16</emphasis> 1099</entry> 1100 </row> 1101 <row> 1102 <entry><emphasis> 1103XkbStateNotify</emphasis> 1104</entry> 1105 <entry><emphasis> 1106KB_STATEPARTMASK</emphasis> 1107</entry> 1108 <entry><emphasis> 1109CARD16</emphasis> 1110</entry> 1111 </row> 1112 <row> 1113 <entry><emphasis> 1114XkbControlsNotify</emphasis> 1115</entry> 1116 <entry><emphasis> 1117KB_CONTROLMASK</emphasis> 1118</entry> 1119 <entry><emphasis> 1120CARD32</emphasis> 1121</entry> 1122 </row> 1123 <row> 1124 <entry><emphasis> 1125XkbIndicatorMapNotify</emphasis> 1126</entry> 1127 <entry><emphasis> 1128KB_INDICATORMASK</emphasis> 1129</entry> 1130 <entry><emphasis> 1131CARD32</emphasis> 1132</entry> 1133 </row> 1134 <row> 1135 <entry><emphasis> 1136XkbIndicatorStateNotify</emphasis> 1137</entry> 1138 <entry><emphasis> 1139KB_INDICATORMASK</emphasis> 1140</entry> 1141 <entry><emphasis> 1142CARD32</emphasis> 1143</entry> 1144 </row> 1145 <row> 1146 <entry><emphasis> 1147XkbNamesNotify</emphasis> 1148</entry> 1149 <entry><emphasis> 1150KB_NAMEDETAILMASK</emphasis> 1151</entry> 1152 <entry><emphasis> 1153CARD16</emphasis> 1154</entry> 1155 </row> 1156 <row> 1157 <entry><emphasis> 1158XkbCompatMapNotify</emphasis> 1159</entry> 1160 <entry><emphasis> 1161KB_CMDETAILMASK</emphasis> 1162</entry> 1163 <entry><emphasis> 1164CARD8</emphasis> 1165</entry> 1166 </row> 1167 <row> 1168 <entry><emphasis> 1169XkbBellNotify</emphasis> 1170</entry> 1171 <entry><emphasis> 1172KB_BELLDETAILMASK</emphasis> 1173</entry> 1174 <entry><emphasis> 1175CARD8</emphasis> 1176</entry> 1177 </row> 1178 <row> 1179 <entry><emphasis> 1180XkbActionMessage</emphasis> 1181</entry> 1182 <entry><emphasis> 1183KB_MSGDETAILMASK</emphasis> 1184</entry> 1185 <entry><emphasis> 1186CARD8</emphasis> 1187</entry> 1188 </row> 1189 <row> 1190 <entry><emphasis> 1191XkbAccessXNotify</emphasis> 1192</entry> 1193 <entry><emphasis> 1194KB_AXNDETAILMASK</emphasis> 1195</entry> 1196 <entry><emphasis> 1197CARD16</emphasis> 1198</entry> 1199 </row> 1200 <row> 1201 <entry><emphasis> 1202XkbExtensionDeviceNotify</emphasis> 1203</entry> 1204 <entry><emphasis> 1205KB_XIDETAILMASK</emphasis> 1206</entry> 1207 <entry><emphasis> 1208CARD16</emphasis> 1209</entry> 1210 </row> 1211</tbody> 1212</tgroup> 1213</informaltable> 1214 1215<para> 1216Detail masks for event types that are not specified in <emphasis> 1217affectWhich</emphasis> 1218 are not changed. 1219</para> 1220 1221 1222<para> 1223If any components are specified in a client’s event masks, the X server sends 1224the client an appropriate event whenever any of those components change state. 1225Unless explicitly modified, all event detail masks are empty. <link linkend='Events'>Events</link> describes all XKB events 1226and the conditions under which the server generates them. 1227</para> 1228 1229 1230</sect2> 1231<sect2 id='Generating_Named_Keyboard_Bells'> 1232<title>Generating Named Keyboard Bells</title> 1233 1234 1235<informaltable frame='none' tabstyle='proto'> 1236<?dbfo keep-together="always" ?> 1237<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1238<colspec colname='c1' colwidth='1.0*'/> 1239 <thead> 1240 <row> 1241 <entry role='protoname'>XkbBell</entry> 1242 </row> 1243 </thead> 1244 <tbody> 1245 <row> 1246 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 1247 </row> 1248 <row> 1249 <entry role='protoname'> 1250bellClass: KB_BELLCLASSSPEC</entry> 1251 </row> 1252 <row> 1253 <entry role='protoname'> 1254bellID: KB_IDSPEC</entry> 1255 </row> 1256 <row> 1257 <entry role='protoname'> 1258percent: INT8</entry> 1259 </row> 1260 <row> 1261 <entry role='protoname'> 1262forceSound: BOOL</entry> 1263 </row> 1264 <row> 1265 <entry role='protoname'> 1266eventOnly: BOOL</entry> 1267 </row> 1268 <row> 1269 <entry role='protoname'> 1270pitch, duration: INT16</entry> 1271 </row> 1272 <row> 1273 <entry role='protoname'> 1274name: ATOM</entry> 1275 </row> 1276 <row> 1277 <entry role='protoname'> 1278window: WINDOW</entry> 1279 </row> 1280 1281 <row> 1282 <entry role='protoerror'>Errors: <emphasis> 1283Keyboard</emphasis> 1284, <emphasis> 1285Value</emphasis> 1286, <emphasis> 1287Match</emphasis> 1288</entry> 1289 </row> 1290 1291 </tbody> 1292 </tgroup> 1293</informaltable> 1294 1295<para> 1296This request generates audible bells and/or <emphasis> 1297XkbBellNotify</emphasis> 1298 events for the bell specified by the <emphasis> 1299bellClass</emphasis> 1300 and <emphasis> 1301bellID</emphasis> 1302 on the device specified by <emphasis> 1303deviceSpec</emphasis> 1304 at the specified <emphasis> 1305pitch</emphasis> 1306, <emphasis> 1307duration</emphasis> 1308 and volume (<emphasis> 1309percent</emphasis> 1310). If deviceSpec specifies a device that does not have a bell or keyboard 1311feedback, a <emphasis> 1312Keyboard</emphasis> 1313 error results. 1314</para> 1315 1316 1317<para> 1318If both <emphasis> 1319forceSound</emphasis> 1320 and <emphasis> 1321eventOnly</emphasis> 1322 are set, this request yields a <emphasis> 1323Match</emphasis> 1324 error. Otherwise, if <emphasis> 1325forceSound</emphasis> 1326 is <emphasis> 1327True</emphasis> 1328, this request always generates a sound and never generates an event; if 1329<emphasis> 1330eventOnly</emphasis> 1331 is <emphasis> 1332True</emphasis> 1333, it causes an event but no sound. If neither <emphasis> 1334forceSound</emphasis> 1335 nor <emphasis> 1336eventOnly</emphasis> 1337 are <emphasis> 1338True</emphasis> 1339, this request always generates an event; if the keyboard’s global <emphasis> 1340AudibleBell</emphasis> 1341 control is enabled, it also generates a sound. 1342</para> 1343 1344 1345<para> 1346Any bell event generated by this request contains all of the information about 1347the bell that was requested, including the symbolic name specified by <emphasis> 1348name</emphasis> 1349 and the event window specified by window. The <emphasis> 1350name</emphasis> 1351 and <emphasis> 1352window</emphasis> 1353 are not directly interpreted by XKB, but they must have the value <emphasis> 1354None</emphasis> 1355 or specify a legal Atom or Window, respectively. <emphasis> 1356XkbBellNotify</emphasis> 1357 events generated in response to core protocol or X input extension bell 1358requests always report <emphasis> 1359None</emphasis> 1360 as their <emphasis> 1361name</emphasis> 1362. 1363</para> 1364 1365 1366<para> 1367The <emphasis> 1368bellClass</emphasis> 1369, <emphasis> 1370bellID</emphasis> 1371, and <emphasis> 1372percent</emphasis> 1373 fields are interpreted as for the X input extension <emphasis> 1374DeviceBell</emphasis> 1375 request. If <emphasis> 1376pitch</emphasis> 1377 and <emphasis> 1378duration</emphasis> 1379 are zero, the server uses the corresponding values for that bell from the core 1380protocol or input extension, otherwise <emphasis> 1381pitch</emphasis> 1382 and <emphasis> 1383duration</emphasis> 1384 are interpreted as for the core protocol <emphasis> 1385ChangeKeyboardControl</emphasis> 1386 request; if they do not include legal values, a <emphasis> 1387Value</emphasis> 1388 error results. The <emphasis> 1389window</emphasis> 1390 field must specify a legal Window or have the value <emphasis> 1391None</emphasis> 1392, or a <emphasis> 1393Value</emphasis> 1394 error results. The name field must specify a legal Atom or have the value 1395<emphasis> 1396None</emphasis> 1397, or an <emphasis> 1398Atom</emphasis> 1399 error results. If an error occurs, this request has no other effect (i.e. does 1400not cause a sound or generate an event). 1401</para> 1402 1403 1404<para> 1405The <emphasis> 1406pitch</emphasis> 1407, <emphasis> 1408volume</emphasis> 1409, and <emphasis> 1410duration</emphasis> 1411 are suggested values for the bell, but XKB does not require the server to 1412honor them. 1413</para> 1414 1415 1416</sect2> 1417<sect2 id='Querying_and_Changing_Keyboard_State'> 1418<title>Querying and Changing Keyboard State</title> 1419 1420 1421<informaltable frame='none' tabstyle='proto'> 1422<?dbfo keep-together="always" ?> 1423<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1424<colspec colname='c1' colwidth='1.0*'/> 1425 <thead> 1426 <row> 1427 <entry role='protoname'>XkbGetState</entry> 1428 </row> 1429 </thead> 1430 <tbody> 1431 <row> 1432 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC 1433 </entry> 1434 </row> 1435 <row> 1436 <entry role='protoreply'> 1437deviceID: CARD8 1438 </entry> 1439 </row> 1440 <row> 1441 <entry role='protoreply'> 1442mods, baseMods, latchedMods, lockedMods: KEYMASK 1443 </entry> 1444 </row> 1445 <row> 1446 <entry role='protoreply'> 1447group, lockedGroup: KB_GROUP 1448 </entry> 1449 </row> 1450 <row> 1451 <entry role='protoreply'> 1452baseGroup, latchedGroup: INT16 1453 </entry> 1454 </row> 1455 <row> 1456 <entry role='protoreply'> 1457compatState: KEYMASK 1458 </entry> 1459 </row> 1460 <row> 1461 <entry role='protoreply'> 1462grabMods, compatGrabMods: KB_GROUP 1463 </entry> 1464 </row> 1465 <row> 1466 <entry role='protoreply'> 1467lookupMods, compatLookupMods: KEYMASK 1468 </entry> 1469 </row> 1470 <row> 1471 <entry role='protoreply'> 1472ptrBtnState: BUTMASK</entry> 1473 </row> 1474 <row> 1475 <entry role='protoerror'>Errors: <emphasis> 1476Keyboard</emphasis> 1477</entry> 1478 </row> 1479 1480 </tbody> 1481 </tgroup> 1482</informaltable> 1483 1484<para> 1485This request returns a detailed description of the current state of the 1486keyboard specified by <emphasis> 1487deviceSpec</emphasis> 1488. 1489</para> 1490 1491 1492<para> 1493The <emphasis> 1494deviceID</emphasis> 1495 return value contains the input extension identifier for the specified device, 1496or <emphasis> 14970</emphasis> 1498 if the server does not support the input extension. 1499</para> 1500 1501 1502<para> 1503The <emphasis> 1504baseMods</emphasis> 1505 return value reports the modifiers that are set because one or more modifier 1506keys are logically down. The <emphasis> 1507latchedMods</emphasis> 1508 and <emphasis> 1509lockedMods</emphasis> 1510 return values report the modifiers that are latched or locked respectively. 1511The <emphasis> 1512mods</emphasis> 1513 return value reports the effective modifier mask which results from the 1514current combination of base, latched and locked modifiers. 1515</para> 1516 1517 1518<para> 1519The <emphasis> 1520baseGroup</emphasis> 1521 return value reports the group state selected by group shift keys that are 1522logically down. The <emphasis> 1523latchedGroup</emphasis> 1524 and <emphasis> 1525lockedGroup</emphasis> 1526 return values detail the effects of latching or locking group shift keys and 1527<emphasis> 1528XkbLatchLockState</emphasis> 1529 requests. The <emphasis> 1530group</emphasis> 1531 return value reports the effective keyboard group which results from the 1532current combination of base, latched and locked group values. 1533</para> 1534 1535 1536<para> 1537The <emphasis> 1538lookupMods</emphasis> 1539 return value reports the lookup modifiers, which consist of the current 1540effective modifiers minus any server internal modifiers. The <emphasis> 1541grabMods</emphasis> 1542 return value reports the grab modifiers, which consist of the lookup modifiers 1543minus any members of the ignore locks mask that are not either latched or 1544logically depressed. <link linkend='Keyboard_State'>Keyboard 1545State</link> describes the lookup modifiers and grab modifiers in more detail. 1546</para> 1547 1548 1549<para> 1550The <emphasis> 1551ptrBtnState</emphasis> 1552 return value reports the current logical state of up to five buttons on the 1553core pointer device. 1554</para> 1555 1556 1557<para> 1558The <emphasis> 1559compatState</emphasis> 1560 return value reports the compatibility state that corresponds to the effective 1561keyboard group and modifier state. The <emphasis> 1562compatLookupMods</emphasis> 1563 and <emphasis> 1564compatGrabMods</emphasis> 1565 return values report the core protocol compatibility states that correspond to 1566the XKB lookup and grab state. All of the compatibility states are computed by 1567applying the group compatibility mapping to the corresponding XKB modifier and 1568group states, as described in <link linkend='Group_Compatibility_Map'> 1569Group Compatibility Map</link>. 1570</para> 1571 1572 1573 1574<informaltable frame='none' tabstyle='proto'> 1575<?dbfo keep-together="always" ?> 1576<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1577<colspec colname='c1' colwidth='1.0*'/> 1578 <thead> 1579 <row> 1580 <entry role='protoname'>XkbLatchLockState</entry> 1581 </row> 1582 </thead> 1583 <tbody> 1584 <row> 1585 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 1586 </row> 1587 <row> 1588 <entry role='protoname'> 1589affectModLocks, modLocks: KEYMASK</entry> 1590 </row> 1591 <row> 1592 <entry role='protoname'> 1593lockGroup: BOOL</entry> 1594 </row> 1595 <row> 1596 <entry role='protoname'> 1597groupLock: KB_GROUP</entry> 1598 </row> 1599 <row> 1600 <entry role='protoname'> 1601affectModLatches,modLatches: KEYMASK</entry> 1602 </row> 1603 <row> 1604 <entry role='protoname'> 1605latchGroup: BOOL</entry> 1606 </row> 1607 <row> 1608 <entry role='protoname'> 1609groupLatch: INT16</entry> 1610 </row> 1611 1612 <row> 1613 <entry role='protoerror'>Errors: <emphasis> 1614Keyboard</emphasis> 1615, <emphasis> 1616Value</emphasis> 1617</entry> 1618 </row> 1619 1620 </tbody> 1621 </tgroup> 1622</informaltable> 1623 1624<para> 1625This request locks or latches keyboard modifiers and group state for the device 1626specified by <emphasis> 1627deviceSpec</emphasis> 1628. If <emphasis> 1629deviceSpec</emphasis> 1630 specifies an illegal or non-keyboard device, a <emphasis> 1631Keyboard</emphasis> 1632 error occurs. 1633</para> 1634 1635 1636<para> 1637The locked state of any modifier specified in the <emphasis> 1638affectModLocks</emphasis> 1639 mask is set to the corresponding value from <emphasis> 1640modLocks</emphasis> 1641. If <emphasis> 1642lockGroup</emphasis> 1643 is <emphasis> 1644True</emphasis> 1645, the locked keyboard group is set to the group specified by <emphasis> 1646groupLock</emphasis> 1647. If any modifiers are set in <emphasis> 1648modLocks</emphasis> 1649 but not <emphasis> 1650affectModLocks</emphasis> 1651, a <emphasis> 1652Match</emphasis> 1653 error occurs. 1654</para> 1655 1656 1657<para> 1658The latched state of any modifier specified in the <emphasis> 1659affectModLatches</emphasis> 1660 mask is set to the corresponding value from <emphasis> 1661modLatches</emphasis> 1662. If <emphasis> 1663latchGroup</emphasis> 1664 is <emphasis> 1665True</emphasis> 1666, the latched keyboard group is set to the group specified by <emphasis> 1667groupLatch</emphasis> 1668. if any modifiers are set in <emphasis> 1669modLatches</emphasis> 1670 but not in <emphasis> 1671affectModLatches</emphasis> 1672, a <emphasis> 1673Match</emphasis> 1674 error occurs. 1675</para> 1676 1677 1678<para> 1679If the locked group exceeds the maximum number of groups permitted for the 1680specified keyboard, it is wrapped or truncated back into range as specified by 1681the global <emphasis> 1682GroupsWrap</emphasis> 1683<emphasis> 1684 </emphasis> 1685control. No error results from an out-of-range group specification. 1686</para> 1687 1688 1689<para> 1690After changing the locked and latched modifiers and groups as specified, the X 1691server recalculates the effective and compatibility keyboard state and 1692generates <emphasis> 1693XkbStateNotify</emphasis> 1694 events as appropriate if any state components have changed. Changing the 1695keyboard state might also turn indicators on or off which can cause <emphasis> 1696XkbIndicatorStateNotify</emphasis> 1697 events as well. 1698</para> 1699 1700 1701<para> 1702If any errors occur, this request has no effect. 1703</para> 1704 1705 1706</sect2> 1707<sect2 id='Querying_and_Changing_Keyboard_Controls'> 1708<title>Querying and Changing Keyboard Controls</title> 1709 1710 1711<informaltable frame='none' tabstyle='proto'> 1712<?dbfo keep-together="always" ?> 1713<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1714<colspec colname='c1' colwidth='1.0*'/> 1715 <thead> 1716 <row> 1717 <entry role='protoname'>XkbGetControls</entry> 1718 </row> 1719 </thead> 1720 <tbody> 1721 <row> 1722 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC 1723 </entry> 1724 </row> 1725 <row> 1726 <entry role='protoreply'> 1727deviceID: CARD8 1728 </entry> 1729 </row> 1730 <row> 1731 <entry role='protoreply'> 1732mouseKeysDfltBtn: CARD8 1733 </entry> 1734 </row> 1735 <row> 1736 <entry role='protoreply'> 1737numGroups: CARD8 1738 </entry> 1739 </row> 1740 <row> 1741 <entry role='protoreply'> 1742groupsWrap: KB_GROUPINFO 1743 </entry> 1744 </row> 1745 <row> 1746 <entry role='protoreply'> 1747internalMods,ignoreLockMods: KB_MODDEF 1748 </entry> 1749 </row> 1750 <row> 1751 <entry role='protoreply'> 1752repeatDelay,repeatInterval: CARD16 1753 </entry> 1754 </row> 1755 <row> 1756 <entry role='protoreply'> 1757slowKeysDelay, debounceDelay: CARD16 1758 </entry> 1759 </row> 1760 <row> 1761 <entry role='protoreply'> 1762mouseKeysDelay, mouseKeysInterval: CARD16 1763 </entry> 1764 </row> 1765 <row> 1766 <entry role='protoreply'> 1767mouseKeysTimeToMax, mouseKeysMaxSpeed: CARD16 1768 </entry> 1769 </row> 1770 <row> 1771 <entry role='protoreply'> 1772mouseKeysCurve: INT16 1773 </entry> 1774 </row> 1775 <row> 1776 <entry role='protoreply'> 1777accessXOptions: KB_AXOPTIONMASK 1778 </entry> 1779 </row> 1780 <row> 1781 <entry role='protoreply'> 1782accessXTimeout: CARD16 1783 </entry> 1784 </row> 1785 <row> 1786 <entry role='protoreply'> 1787accessXTimeoutOptionsMask, accessXTimeoutOptionValues: CARD16 1788 </entry> 1789 </row> 1790 <row> 1791 <entry role='protoreply'> 1792accessXTimeoutMask,accessXTimeoutValues: CARD32 1793 </entry> 1794 </row> 1795 <row> 1796 <entry role='protoreply'> 1797enabledControls: KB_BOOLCTRLMASK 1798 </entry> 1799 </row> 1800 <row> 1801 <entry role='protoreply'> 1802perKeyRepeat: LISTofCARD8</entry> 1803 </row> 1804 1805 <row> 1806 <entry role='protoerror'>Errors: <emphasis> 1807Keyboard</emphasis> 1808</entry> 1809 </row> 1810 1811 </tbody> 1812 </tgroup> 1813</informaltable> 1814 1815<para> 1816This request returns the current values and status of all controls for the 1817keyboard specified by <emphasis> 1818deviceSpec</emphasis> 1819. If <emphasis> 1820deviceSpec</emphasis> 1821 specifies an illegal device a <emphasis> 1822Keyboard</emphasis> 1823 error results. On return, the <emphasis> 1824deviceID</emphasis> 1825 specifies the identifier of the requested device or zero if the server does 1826not support the input extension. 1827</para> 1828 1829 1830<para> 1831The <emphasis> 1832numGroups</emphasis> 1833 return value reports the current number of groups, and <emphasis> 1834groupsWrap</emphasis> 1835 reports the treatment of out-of-range groups, as described in <link linkend='Key_Symbol_Map'>Key Symbol Map</link>. The <emphasis> 1836internalMods</emphasis> 1837 and <emphasis> 1838ignoreLockMods</emphasis> 1839 return values report the current values of the server internal and ignore 1840locks modifiers as described in <link linkend='Keyboard_State'> 1841Keyboard State</link>. Both are modifier definitions ( 1842<link linkend='Modifier_Definitions'>Modifier Definitions</link>) which 1843report the real modifiers, virtual modifiers, and the resulting combination of 1844real modifiers that are bound to the corresponding control. 1845</para> 1846 1847 1848<para> 1849The <emphasis> 1850repeatDelay</emphasis> 1851, <emphasis> 1852repeatInterval</emphasis> 1853, <emphasis> 1854slowKeysDelay</emphasis> 1855 and <emphasis> 1856debounceDelay</emphasis> 1857 fields report the current values of the for the autorepeat delay, autorepeat 1858interval, slow keys delay and bounce keys timeout, respectively. The <emphasis> 1859mouseKeysDelay</emphasis> 1860, <emphasis> 1861mouseKeysInterval</emphasis> 1862, <emphasis> 1863mouseKeysTimeToMax</emphasis> 1864 and <emphasis> 1865mouseKeysMaxSpeed</emphasis> 1866 and <emphasis> 1867mouseKeysCurve</emphasis> 1868 return values report the current acceleration applied to mouse keys, as 1869described in <link linkend='The_MouseKeysAccel_Control'>The MouseKeysAccel 1870Control</link>. All times are reported in milliseconds. 1871</para> 1872 1873 1874<para> 1875The <emphasis> 1876mouseKeysDfltBtn</emphasis> 1877 return value reports the current default pointer button for which events are 1878synthesized by the mouse keys server actions. 1879</para> 1880 1881 1882<para> 1883The <emphasis> 1884accessXOptions</emphasis> 1885 return value reports the current settings of the various AccessX options flags 1886which govern the behavior of the <emphasis> 1887StickyKeys</emphasis> 1888 control and of AccessX feedback. 1889</para> 1890 1891 1892<para> 1893The <emphasis> 1894accessXTimeout</emphasis> 1895 return value reports the length of time, in seconds, that the keyboard must 1896remain idle before AccessX controls are automatically changed; an <emphasis> 1897accessXTimeout</emphasis> 1898 of <emphasis> 18990</emphasis> 1900 indicates that AccessX controls are not automatically changed. The <emphasis> 1901accessXTimeoutMask</emphasis> 1902 specifies the boolean controls to be changed if the AccessX timeout expires; 1903the <emphasis> 1904accessXTimeoutValues</emphasis> 1905 field specifies new values for all of the controls in the timeout mask. The 1906<emphasis> 1907accessXTimeoutOptionsMask</emphasis> 1908 field specifies the AccessX options to be changed when the AccessX timeout 1909expires; the <emphasis> 1910accessXTimeoutOptionValues</emphasis> 1911 return value reports the values to which they will be set. 1912</para> 1913 1914 1915<para> 1916The <emphasis> 1917enabledControls</emphasis> 1918 return value reports the current state of all of the global boolean controls. 1919</para> 1920 1921 1922<para> 1923The <emphasis> 1924perKeyRepeat</emphasis> 1925 array consists of one bit per key and reports the current autorepeat behavior 1926of each keyboard key; if a bit is set in <emphasis> 1927perKeyRepeat</emphasis> 1928, the corresponding key repeats if it is held down while global keyboard 1929autorepeat is enabled. This array parallels the core protocol and input 1930extension keyboard controls, if the autorepeat behavior of a key is changed via 1931the core protocol or input extension, those changes are automatically reflected 1932in the <emphasis> 1933perKeyRepeat</emphasis> 1934 array. 1935</para> 1936 1937 1938 1939<informaltable frame='none' tabstyle='proto'> 1940<?dbfo keep-together="always" ?> 1941<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1942<colspec colname='c1' colwidth='1.0*'/> 1943 <thead> 1944 <row> 1945 <entry role='protoname'>XkbSetControls</entry> 1946 </row> 1947 </thead> 1948 <tbody> 1949 <row> 1950 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 1951 </row> 1952 <row> 1953 <entry role='protoname'> 1954affectInternalRealMods, internalRealMods: KEYMASK</entry> 1955 </row> 1956 <row> 1957 <entry role='protoname'> 1958affectInternalVirtualMods,internalVirtualMods: KB_VMODMASK</entry> 1959 </row> 1960 <row> 1961 <entry role='protoname'> 1962affectIgnoreLockRealMods,ignoreLockRealMods: KB_MODMASK</entry> 1963 </row> 1964 <row> 1965 <entry role='protoname'> 1966affectIgnoreLockVirtualMods,ignoreLockVirtualMods: KB_VMODMASK</entry> 1967 </row> 1968 <row> 1969 <entry role='protoname'> 1970mouseKeysDfltBtn: CARD8</entry> 1971 </row> 1972 <row> 1973 <entry role='protoname'> 1974groupsWrap: KB_GROUPINFO</entry> 1975 </row> 1976 <row> 1977 <entry role='protoname'> 1978accessXOptions: CARD16</entry> 1979 </row> 1980 <row> 1981 <entry role='protoname'> 1982affectEnabledControls: KB_BOOLCTRLMASK</entry> 1983 </row> 1984 <row> 1985 <entry role='protoname'> 1986enabledControls: KB_BOOLCTRLMASK</entry> 1987 </row> 1988 <row> 1989 <entry role='protoname'> 1990changeControls: KB_CONTROLMASK</entry> 1991 </row> 1992 <row> 1993 <entry role='protoname'> 1994repeatDelay,repeatInterval: CARD16</entry> 1995 </row> 1996 <row> 1997 <entry role='protoname'> 1998slowKeysDelay, debounceDelay: CARD16</entry> 1999 </row> 2000 <row> 2001 <entry role='protoname'> 2002mouseKeysDelay, mouseKeysInterval: CARD16</entry> 2003 </row> 2004 <row> 2005 <entry role='protoname'> 2006mouseKeysTimeToMax, mouseKeysMaxSpeed: CARD16</entry> 2007 </row> 2008 <row> 2009 <entry role='protoname'> 2010mouseKeysCurve: INT16</entry> 2011 </row> 2012 <row> 2013 <entry role='protoname'> 2014accessXTimeout: CARD16</entry> 2015 </row> 2016 <row> 2017 <entry role='protoname'> 2018accessXTimeoutMask, accessXTimeoutValues: KB_BOOLCTRLMASK</entry> 2019 </row> 2020 <row> 2021 <entry role='protoname'> 2022accessXTimeoutOptionsMask,accessXTimeoutOptionsValues: CARD16</entry> 2023 </row> 2024 <row> 2025 <entry role='protoname'> 2026perKeyRepeat: LISTofCARD8</entry> 2027 </row> 2028 2029 <row> 2030 <entry role='protoerror'>Errors:<emphasis> 2031 Keyboard</emphasis> 2032, <emphasis> 2033Value</emphasis> 2034</entry> 2035 </row> 2036 2037 </tbody> 2038 </tgroup> 2039</informaltable> 2040 2041<para> 2042This request sets the keyboard controls indicated in <emphasis> 2043changeControls</emphasis> 2044 for the keyboard specified by <emphasis> 2045deviceSpec</emphasis> 2046. Each bit that is set in <emphasis> 2047changeControls</emphasis> 2048 indicates that one or more of the other request fields should be applied, as 2049follows: 2050</para> 2051 2052<informaltable frame='topbot'> 2053<?dbfo keep-together="always" ?> 2054<tgroup cols='2' align='left' colsep='0' rowsep='0'> 2055<colspec colname='c1' colwidth='1.0*'/> 2056<colspec colname='c2' colwidth='2.0*'/> 2057<thead> 2058 <row rowsep='1'> 2059 <entry>Bit in changeControls</entry> 2060 <entry>Field(s) to be Applied</entry> 2061 </row> 2062</thead> 2063<tbody> 2064 <row> 2065 <entry><emphasis> 2066XkbRepeatKeysMask</emphasis> 2067</entry> 2068 <entry><emphasis> 2069repeatDelay</emphasis> 2070, <emphasis> 2071repeatInterval</emphasis> 2072</entry> 2073 </row> 2074 <row> 2075 <entry><emphasis> 2076XkbSlowKeysMask</emphasis> 2077</entry> 2078 <entry><emphasis> 2079slowKeysDelay</emphasis> 2080</entry> 2081 </row> 2082 <row> 2083 <entry><emphasis> 2084XkbStickyKeysMask</emphasis> 2085</entry> 2086 <entry><emphasis> 2087accessXOptions</emphasis> 2088 (only the <emphasis> 2089XkbAX_TwoKeys</emphasis> 2090<emphasis> 2091 </emphasis> 2092and the <emphasis> 2093XkbAX_LatchToLock</emphasis> 2094 options are affected)</entry> 2095 </row> 2096 <row> 2097 <entry><emphasis> 2098XkbBounceKeysMask</emphasis> 2099</entry> 2100 <entry><emphasis> 2101debounceDelay</emphasis> 2102</entry> 2103 </row> 2104 <row> 2105 <entry><emphasis> 2106XkbMouseKeysMask</emphasis> 2107</entry> 2108 <entry><emphasis> 2109mouseKeysDfltBtn</emphasis> 2110</entry> 2111 </row> 2112 <row> 2113 <entry><emphasis> 2114XkbMouseKeysAccelMask</emphasis> 2115</entry> 2116 <entry><emphasis> 2117mouseKeysDelay</emphasis> 2118, <emphasis> 2119mouseKeysInterval</emphasis> 2120, <emphasis> 2121mouseKeysCurve</emphasis> 2122, <emphasis> 2123mouseKeysTimeToMax</emphasis> 2124, <emphasis> 2125mouseKeysMaxSpeed</emphasis> 2126</entry> 2127 </row> 2128 <row> 2129 <entry><emphasis> 2130XkbAccessXKeysMask</emphasis> 2131</entry> 2132 <entry><emphasis> 2133accessXOptions (all options)</emphasis> 2134</entry> 2135 </row> 2136 <row> 2137 <entry><emphasis> 2138XkbAccessXTimeoutMask</emphasis> 2139</entry> 2140 <entry><emphasis> 2141accessXTimeout</emphasis> 2142, <emphasis> 2143accessXTimeoutMask</emphasis> 2144, <emphasis> 2145accessXTimeoutValues</emphasis> 2146, <emphasis> 2147accessXTimeoutOptionsMask</emphasis> 2148, <emphasis> 2149accessXTimeoutOptionsValues</emphasis> 2150</entry> 2151 </row> 2152 <row> 2153 <entry>XkbAccessXFeedbackMask</entry> 2154 <entry><emphasis> 2155accessXOptions</emphasis> 2156 (all options except those affected by the <emphasis> 2157XkbStickyKeysMask</emphasis> 2158 bit)</entry> 2159 </row> 2160 <row> 2161 <entry><emphasis> 2162XkbGroupsWrapMask</emphasis> 2163</entry> 2164 <entry><emphasis> 2165groupsWrap</emphasis> 2166</entry> 2167 </row> 2168 <row> 2169 <entry><emphasis> 2170XkbInternalModsMask</emphasis> 2171</entry> 2172 <entry><emphasis> 2173affectInternalRealMods</emphasis> 2174, <emphasis> 2175internalRealMods</emphasis> 2176, <emphasis> 2177affectInternalVirtualMods</emphasis> 2178, <emphasis> 2179internalVirtualMods</emphasis> 2180</entry> 2181 </row> 2182 <row> 2183 <entry><emphasis> 2184XkbIgnoreLockModsMask</emphasis> 2185</entry> 2186 <entry><emphasis> 2187affectIgnoreLockRealMods</emphasis> 2188, <emphasis> 2189ignoreLockRealMods</emphasis> 2190, <emphasis> 2191affectIgnoreLockVirtualMods</emphasis> 2192, <emphasis> 2193ignoreLockVirtualMods</emphasis> 2194</entry> 2195 </row> 2196 <row> 2197 <entry><emphasis> 2198XkbPerKeyRepeatMask</emphasis> 2199</entry> 2200 <entry><emphasis> 2201perKeyRepeat</emphasis> 2202</entry> 2203 </row> 2204 <row> 2205 <entry><emphasis> 2206XkbControlsEnabledMask</emphasis> 2207</entry> 2208 <entry><emphasis> 2209affectEnabledControls</emphasis> 2210, <emphasis> 2211enabledControls</emphasis> 2212</entry> 2213 </row> 2214</tbody> 2215</tgroup> 2216</informaltable> 2217 2218<para> 2219If any other bits are set in <emphasis> 2220changeControls</emphasis> 2221, a <emphasis> 2222Value</emphasis> 2223 error results. If any of the bits listed above are not set in <emphasis> 2224changeControls</emphasis> 2225, the corresponding fields must have the value <emphasis> 22260</emphasis> 2227, or a <emphasis> 2228Match</emphasis> 2229 error results. 2230</para> 2231 2232 2233<para> 2234If applied, <emphasis> 2235repeatDelay</emphasis> 2236 and <emphasis> 2237repeatInterval</emphasis> 2238 change the autorepeat characteristics of the keyboard, as described in 2239<link linkend='The_RepeatKeys_Control'>The RepeatKeys Control</link>. If 2240specified, <emphasis> 2241repeatDelay</emphasis> 2242 and <emphasis> 2243repeatInterval</emphasis> 2244 must both be non-zero or a <emphasis> 2245Value</emphasis> 2246 error results. 2247</para> 2248 2249 2250<para> 2251If applied, the <emphasis> 2252slowKeysDelay</emphasis> 2253 field specifies a new delay for the <emphasis> 2254SlowKeys</emphasis> 2255 control, as defined in <link linkend='The_SlowKeys_Control'>The 2256SlowKeys Control</link>. If specified, <emphasis> 2257slowKeysDelay</emphasis> 2258 must be non-zero, or a <emphasis> 2259Value</emphasis> 2260 error results. 2261</para> 2262 2263 2264<para> 2265If applied, the <emphasis> 2266debounceDelay</emphasis> 2267 field specifies a new delay for the <emphasis> 2268BounceKeys</emphasis> 2269 control, as described in <link linkend='The_BounceKeys_Control'>The 2270BounceKeys Control</link>. If present, the <emphasis> 2271debounceDelay</emphasis> 2272 must be non-zero or a <emphasis> 2273Value</emphasis> 2274 error results. 2275</para> 2276 2277 2278<para> 2279If applied, the <emphasis> 2280mouseKeysDfltBtn</emphasis> 2281 field specifies the core pointer button for which events are generated 2282whenever a <emphasis> 2283SA_PtrBtn</emphasis> 2284 or <emphasis> 2285SA_LockPtrBtn</emphasis> 2286 key action is activated. If present, <emphasis> 2287mouseKeysDfltBtn</emphasis> 2288 must specify a legal button for the core pointer device, or a <emphasis> 2289Value</emphasis> 2290 error results. <link linkend='Key_Actions'>Key 2291Actions</link> describes the <emphasis> 2292SA_PtrBtn</emphasis> 2293 and <emphasis> 2294SA_LockPtrBtn</emphasis> 2295 actions in more detail. 2296</para> 2297 2298 2299<para> 2300If applied, the <emphasis> 2301mouseKeysDelay</emphasis> 2302, <emphasis> 2303mouseKeysInterval</emphasis> 2304, <emphasis> 2305mouseKeysTimeToMax</emphasis> 2306, <emphasis> 2307mouseKeysMaxSpeed</emphasis> 2308 and <emphasis> 2309mouseKeysCurve</emphasis> 2310 fields change the rate at which the pointer moves when a key which generates a 2311<emphasis> 2312SA_MovePtr</emphasis> 2313 action is held down. <link linkend='The_MouseKeysAccel_Control'>The 2314MouseKeysAccel Control</link> describes these <emphasis> 2315MouseKeysAccel</emphasis> 2316 parameters in more detail. If defined, the <emphasis> 2317mouseKeysDelay</emphasis> 2318, <emphasis> 2319mouseKeysInterval</emphasis> 2320, <emphasis> 2321mouseKeysTimeToMax</emphasis> 2322 and <emphasis> 2323mouseKeysMaxSpeed</emphasis> 2324 values must all be greater than zero, or a <emphasis> 2325Value</emphasis> 2326 error results. The <emphasis> 2327mouseKeysCurve</emphasis> 2328 value must be greater than <emphasis> 2329-1000</emphasis> 2330 or a <emphasis> 2331Value</emphasis> 2332 error results. 2333</para> 2334 2335 2336<para> 2337If applied, the <emphasis> 2338accessXOptions</emphasis> 2339 field sets the AccessX options, which are described in detail in 2340<link linkend='The_AccessXKeys_Control'>The AccessXKeys Control</link>. If 2341either one of <emphasis> 2342XkbStickyKeysMask</emphasis> 2343 and <emphasis> 2344XkbAccessXFeedbackMask</emphasis> 2345 are set in <emphasis> 2346changeControls</emphasis> 2347 and <emphasis> 2348XkbAccessXKeysMask</emphasis> 2349 is not, only a subset of the AccessX options are changed, as described in the 2350table above; if both are set or if the <emphasis> 2351AccessXKeys</emphasis> 2352 bit is set in <emphasis> 2353changeControls</emphasis> 2354, all of the AccessX options are updated. Any bit in <emphasis> 2355accessXOptions</emphasis> 2356 whose interpretation is undefined must be zero, or a <emphasis> 2357Value</emphasis> 2358 error results. 2359</para> 2360 2361 2362<para> 2363If applied, the <emphasis> 2364accessXTimeout</emphasis> 2365, <emphasis> 2366accessXTimeoutMask</emphasis> 2367, <emphasis> 2368accessXTimeoutValues</emphasis> 2369, <emphasis> 2370accessXTimeoutOptionsMask</emphasis> 2371 and <emphasis> 2372accessXTimeoutOptionsValues</emphasis> 2373 fields change the behavior of the AccessX Timeout control, as described in 2374<link linkend='The_AccessXTimeout_Control'>The AccessXTimeout 2375Control</link>. The <emphasis> 2376accessXTimeout</emphasis> 2377 must be greater than zero, or a <emphasis> 2378Value</emphasis> 2379 error results. The <emphasis> 2380accessXTimeoutMask</emphasis> 2381 or <emphasis> 2382accessXTimeoutValues</emphasis> 2383 fields must specify only legal boolean controls, or a <emphasis> 2384Value</emphasis> 2385 error results. The <emphasis> 2386accessXTimeoutOptionsMask</emphasis> 2387 and <emphasis> 2388accessXTimeoutOptionsValues</emphasis> 2389 fields must contain only legal AccessX options or a <emphasis> 2390Value</emphasis> 2391 error results. If any bits are set in either values field but not in the 2392corresponding mask, a <emphasis> 2393Match</emphasis> 2394 error results. 2395</para> 2396 2397 2398<para> 2399If present, the <emphasis> 2400groupsWrap</emphasis> 2401 field specifies the treatment of out-of-range keyboard groups, as described in 2402<link linkend='Key_Symbol_Map'>Key Symbol Map</link>. If the 2403<emphasis> 2404groupsWrap</emphasis> 2405 field does not specify a legal treatment for out-of-range groups, a <emphasis> 2406Value</emphasis> 2407 error results. 2408</para> 2409 2410 2411<para> 2412If present, the <emphasis> 2413affectInternalRealMods</emphasis> 2414 field specifies the set of real modifiers to be changed in the internal 2415modifier definition and the <emphasis> 2416internalRealMods</emphasis> 2417 field specifies new values for those modifiers. The <emphasis> 2418affectInternalVirtualMods</emphasis> 2419 and <emphasis> 2420internalVirtualMods</emphasis> 2421 fields update the virtual modifier component of the modifier definition that 2422describes the internal modifiers in the same way. If any bits are set in either 2423values field but not in the corresponding mask field, a <emphasis> 2424Match</emphasis> 2425 error results. 2426</para> 2427 2428 2429<para> 2430If present, the <emphasis> 2431affectIgnoreLockRealMods</emphasis> 2432 field specifies the set of real modifiers to be changed in the ignore locks 2433modifier definition and the <emphasis> 2434ignoreLockRealMods</emphasis> 2435 field specifies new values for those modifiers. The <emphasis> 2436affectIgnoreLockVirtualMods</emphasis> 2437 and <emphasis> 2438ignoreLockVirtualMods</emphasis> 2439 fields update the virtual modifier component of the ignore locks modifier 2440definition in the same way. If any bits are set in either values field but not 2441in the corresponding mask field, a <emphasis> 2442Match</emphasis> 2443 error results. 2444</para> 2445 2446 2447<para> 2448If present, the <emphasis> 2449perKeyRepeat</emphasis> 2450 array specifies the repeat behavior of the individual keyboard keys. The 2451corresponding core protocol or input extension per-key autorepeat information 2452is updated to reflect any changes specified in <emphasis> 2453perKeyRepeat</emphasis> 2454. If the bits that correspond to any out-of-range keys are set in <emphasis> 2455perKeyRepeat</emphasis> 2456, a <emphasis> 2457Value</emphasis> 2458 error results. 2459</para> 2460 2461 2462<para> 2463If present, the <emphasis> 2464affectEnabledControls</emphasis> 2465 and <emphasis> 2466enabledControls</emphasis> 2467 field enable and disable global boolean controls. Any controls set in both 2468fields are enabled; any controls that are set in <emphasis> 2469affectEnabledControls</emphasis> 2470 but not in <emphasis> 2471enabledControls</emphasis> 2472 are disabled. Controls that are not set in either field are not affected. If 2473any controls are specified in <emphasis> 2474enabledControls</emphasis> 2475 but not in <emphasis> 2476affectEnabledControls</emphasis> 2477, a <emphasis> 2478Match</emphasis> 2479 error results. If either field contains anything except boolean controls, a 2480<emphasis> 2481Value</emphasis> 2482 error results. 2483</para> 2484 2485 2486</sect2> 2487<sect2 id='Querying_and_Changing_the_Keyboard_Mapping'> 2488<title>Querying and Changing the Keyboard Mapping</title> 2489 2490 2491<informaltable frame='none' tabstyle='proto'> 2492<?dbfo keep-together="always" ?> 2493<tgroup cols='1' align='left' colsep='0' rowsep='0'> 2494<colspec colname='c1' colwidth='1.0*'/> 2495 <thead> 2496 <row> 2497 <entry role='protoname'>XkbGetMap</entry> 2498 </row> 2499 </thead> 2500 <tbody> 2501 <row> 2502 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 2503 </row> 2504 <row> 2505 <entry role='protoname'> 2506full, partial: KB_MAPPARTMASK</entry> 2507 </row> 2508 <row> 2509 <entry role='protoname'> 2510firstType, nTypes: CARD8</entry> 2511 </row> 2512 <row> 2513 <entry role='protoname'> 2514firstKeySym, firstKeyAction: KEYCODE</entry> 2515 </row> 2516 <row> 2517 <entry role='protoname'> 2518nKeySyms, nKeyActions: CARD8</entry> 2519 </row> 2520 <row> 2521 <entry role='protoname'> 2522firstKeyBehavior,firstKeyExplicit: KEYCODE</entry> 2523 </row> 2524 <row> 2525 <entry role='protoname'> 2526nKeyBehaviors,nKeyExplicit: CARD8</entry> 2527 </row> 2528 <row> 2529 <entry role='protoname'> 2530firstModMapKey,firstVModMapKey: KEYCODE</entry> 2531 </row> 2532 <row> 2533 <entry role='protoname'> 2534nModMapKeys, nVModMapKeys: CARD8</entry> 2535 </row> 2536 <row> 2537 <entry role='protoname'> 2538virtualMods: KB_VMODMASK 2539 </entry> 2540 </row> 2541 <row> 2542 <entry role='protoreply'> 2543deviceID: CARD8 2544 </entry> 2545 </row> 2546 <row> 2547 <entry role='protoreply'> 2548minKeyCode, maxKeyCode: KEYCODE 2549 </entry> 2550 </row> 2551 <row> 2552 <entry role='protoreply'> 2553present: KB_MAPPARTMASK 2554 </entry> 2555 </row> 2556 <row> 2557 <entry role='protoreply'> 2558firstType, nTypes, nTotalTypes: CARD8 2559 </entry> 2560 </row> 2561 <row> 2562 <entry role='protoreply'> 2563firstKeySym, firstKeyAction: KEYCODE 2564 </entry> 2565 </row> 2566 <row> 2567 <entry role='protoreply'> 2568nKeySyms, nKeyActions: CARD8 2569 </entry> 2570 </row> 2571 <row> 2572 <entry role='protoreply'> 2573totalSyms, totalActions: CARD16 2574 </entry> 2575 </row> 2576 <row> 2577 <entry role='protoreply'> 2578firstKeyBehavior, firstKeyExplicit: KEYCODE 2579 </entry> 2580 </row> 2581 <row> 2582 <entry role='protoreply'> 2583nKeyBehaviors, nKeyExplicit: CARD8 2584 </entry> 2585 </row> 2586 <row> 2587 <entry role='protoreply'> 2588totalKeyBehaviors, totalKeyExplicit: CARD8 2589 </entry> 2590 </row> 2591 <row> 2592 <entry role='protoreply'> 2593firstModMapKey, firstVModMapKey: KEYCODE 2594 </entry> 2595 </row> 2596 <row> 2597 <entry role='protoreply'> 2598nModMapKeys, nVModMapKeys: CARD8 2599 </entry> 2600 </row> 2601 <row> 2602 <entry role='protoreply'> 2603totalModMapKeys, totalVModMapKeys: CARD8 2604 </entry> 2605 </row> 2606 <row> 2607 <entry role='protoreply'> 2608virtualMods: KB_VMODMASK 2609 </entry> 2610 </row> 2611 <row> 2612 <entry role='protoreply'> 2613typesRtrn: LISTofKB_KEYTYPE 2614 </entry> 2615 </row> 2616 <row> 2617 <entry role='protoreply'> 2618symsRtrn: LISTofKB_KEYSYMMAP 2619 </entry> 2620 </row> 2621 <row> 2622 <entry role='protoreply'> 2623actsRtrn: { count: LISTofCARD8, acts: LISTofKB_ACTION } 2624 </entry> 2625 </row> 2626 <row> 2627 <entry role='protoreply'> 2628behaviorsRtrn: LISTofKB_SETBEHAVIOR 2629 </entry> 2630 </row> 2631 <row> 2632 <entry role='protoreply'> 2633vmodsRtrn: LISTofSETofKEYMASK 2634 </entry> 2635 </row> 2636 <row> 2637 <entry role='protoreply'> 2638explicitRtrn: LISTofKB_SETEXPLICIT 2639 </entry> 2640 </row> 2641 <row> 2642 <entry role='protoreply'> 2643modmapRtrn: LISTofKB_KEYMODMAP 2644 </entry> 2645 </row> 2646 <row> 2647 <entry role='protoreply'> 2648vmodMapRtrn: LISTofKB_KEYVMODMAP 2649 </entry> 2650 </row> 2651 <row> 2652 <entry role='protoerror'> 2653Errors: <emphasis> 2654Keyboard</emphasis> 2655, <emphasis> 2656Value</emphasis> 2657, <emphasis> 2658Match</emphasis> 2659, <emphasis> 2660Alloc</emphasis> 2661</entry> 2662 </row> 2663 </tbody> 2664 </tgroup> 2665</informaltable> 2666 2667<para> 2668This request returns the indicated components of the server and client maps of 2669the keyboard specified by <emphasis> 2670deviceSpec</emphasis> 2671. The <emphasis> 2672full</emphasis> 2673 mask specifies the map components to be returned in full; the <emphasis> 2674partial</emphasis> 2675 mask specifies the components for which some subset of the legal elements are 2676to be returned. The server returns a <emphasis> 2677Match</emphasis> 2678 error if any component is specified in both <emphasis> 2679full</emphasis> 2680 and <emphasis> 2681partial</emphasis> 2682, or a <emphasis> 2683Value</emphasis> 2684 error if any undefined bits are set in either <emphasis> 2685full</emphasis> 2686 or <emphasis> 2687partial</emphasis> 2688. 2689</para> 2690 2691 2692<para> 2693Each bit in the <emphasis> 2694partial</emphasis> 2695 mask controls the interpretation of one or more of the other request fields, 2696as follows: 2697</para> 2698 2699<informaltable frame='topbot'> 2700<?dbfo keep-together="always" ?> 2701<tgroup cols='3' align='left' colsep='0' rowsep='0'> 2702<colspec colname='c1' colwidth='1.5*'/> 2703<colspec colname='c2' colwidth='1.0*'/> 2704<colspec colname='c3' colwidth='1.5*'/> 2705<thead> 2706 <row rowsep='1'> 2707 <entry>Bit in the Partial Mask</entry> 2708 <entry>Type</entry> 2709 <entry>Corresponding Field(s)</entry> 2710 </row> 2711</thead> 2712<tbody> 2713 <row> 2714 <entry><emphasis> 2715XkbKeyTypesMask</emphasis> 2716</entry> 2717 <entry>key types</entry> 2718 <entry><emphasis> 2719firstType</emphasis> 2720, <emphasis> 2721nTypes</emphasis> 2722</entry> 2723 </row> 2724 <row> 2725 <entry><emphasis> 2726XkbKeySymsMask</emphasis> 2727</entry> 2728 <entry>keycodes</entry> 2729 <entry><emphasis> 2730firstKeySym</emphasis> 2731, <emphasis> 2732nKeySyms</emphasis> 2733</entry> 2734 </row> 2735 <row> 2736 <entry><emphasis> 2737XkbKeyActionsMask</emphasis> 2738</entry> 2739 <entry>keycodes</entry> 2740 <entry><emphasis> 2741firstKeyAction</emphasis> 2742, <emphasis> 2743nKeyActions</emphasis> 2744</entry> 2745 </row> 2746 <row> 2747 <entry><emphasis> 2748XkbKeyBehaviorsMask</emphasis> 2749</entry> 2750 <entry>keycodes</entry> 2751 <entry><emphasis> 2752firstKeyBehavior</emphasis> 2753, <emphasis> 2754nKeyBehaviors</emphasis> 2755</entry> 2756 </row> 2757 <row> 2758 <entry><emphasis> 2759XkbExplicitComponentsMask</emphasis> 2760</entry> 2761 <entry>keycodes</entry> 2762 <entry><emphasis> 2763firstKeyExplicit</emphasis> 2764, <emphasis> 2765nKeyExplicit</emphasis> 2766</entry> 2767 </row> 2768 <row> 2769 <entry><emphasis> 2770XkbModifierMapMask</emphasis> 2771</entry> 2772 <entry>keycodes</entry> 2773 <entry><emphasis> 2774firstModMapKey</emphasis> 2775, <emphasis> 2776nModMapKeys</emphasis> 2777</entry> 2778 </row> 2779 <row> 2780 <entry><emphasis> 2781XkbVirtualModMapMask</emphasis> 2782</entry> 2783 <entry>keycodes</entry> 2784 <entry><emphasis> 2785firstVModMapKey</emphasis> 2786, <emphasis> 2787nVModMapKeys</emphasis> 2788</entry> 2789 </row> 2790 <row> 2791 <entry><emphasis> 2792XkbVirtualModsMask</emphasis> 2793</entry> 2794 <entry>virtual modifiers</entry> 2795 <entry><emphasis> 2796virtualMods</emphasis> 2797</entry> 2798 </row> 2799</tbody> 2800</tgroup> 2801</informaltable> 2802 2803<para> 2804If any of these keyboard map components are specified in <emphasis> 2805partial</emphasis> 2806, the corresponding values must specify a valid subset of the requested 2807components or this request reports a <emphasis> 2808Value</emphasis> 2809 error. If a keyboard map component is not specified in <emphasis> 2810partial</emphasis> 2811, the corresponding fields must contain zeroes, or a <emphasis> 2812Match</emphasis> 2813 error results. 2814</para> 2815 2816 2817<para> 2818If any error is generated, the request aborts and does not report any values. 2819</para> 2820 2821 2822<para> 2823On successful return, the <emphasis> 2824deviceID</emphasis> 2825 field reports the X input extension device ID of the keyboard for which 2826information is being returned, or <emphasis> 28270</emphasis> 2828 if the server does not support the X input extension. The <emphasis> 2829minKeyCode</emphasis> 2830 and <emphasis> 2831maxKeyCode</emphasis> 2832 return values report the minimum and maximum keycodes that are legal for the 2833keyboard in question. 2834</para> 2835 2836 2837<para> 2838The <emphasis> 2839present</emphasis> 2840 return value lists all of the keyboard map components contained in the reply. 2841The bits in <emphasis> 2842present</emphasis> 2843 affect the interpretation of the other return values as follows: 2844</para> 2845 2846 2847<para> 2848If <emphasis> 2849XkbKeyTypesMask</emphasis> 2850 is set in <emphasis> 2851present</emphasis> 2852: 2853</para> 2854 2855<itemizedlist> 2856<listitem> 2857 <para><emphasis> 2858firstType</emphasis> 2859 and <emphasis> 2860nTypes</emphasis> 2861 specify the types reported in the reply. 2862 </para> 2863</listitem> 2864<listitem> 2865 <para><emphasis> 2866nTotalTypes</emphasis> 2867 reports the total number of types defined for the keyboard 2868 </para> 2869</listitem> 2870<listitem> 2871 <para><emphasis> 2872typesRtrn</emphasis> 2873 has <emphasis> 2874nTypes</emphasis> 2875 elements of type KB_KEYTYPE which describe consecutive key types starting from 2876<emphasis> 2877firstType</emphasis> 2878. 2879 </para> 2880</listitem> 2881</itemizedlist> 2882 2883<para> 2884If <emphasis> 2885XkbKeySymsMask</emphasis> 2886 is set in <emphasis> 2887present</emphasis> 2888: 2889</para> 2890 2891<itemizedlist> 2892<listitem> 2893 <para><emphasis> 2894firstKeySym</emphasis> 2895 and <emphasis> 2896nKeySyms</emphasis> 2897 specify the subset of the keyboard keys for which symbols will be reported. 2898 </para> 2899</listitem> 2900<listitem> 2901 <para><emphasis> 2902totalSyms</emphasis> 2903 reports the total number of keysyms bound to the keys returned in this reply. 2904 </para> 2905</listitem> 2906<listitem> 2907 <para><emphasis> 2908symsRtrn</emphasis> 2909 has <emphasis> 2910nKeySyms</emphasis> 2911 elements of type KB_KEYSYMMAP, which describe the symbols bound to consecutive 2912keys starting from <emphasis> 2913firstKeySym</emphasis> 2914. 2915 </para> 2916</listitem> 2917</itemizedlist> 2918 2919<para> 2920If <emphasis> 2921XkbKeyActionsMask</emphasis> 2922 is set in <emphasis> 2923present</emphasis> 2924: 2925</para> 2926 2927<itemizedlist> 2928<listitem> 2929 <para><emphasis> 2930firstKeyAction</emphasis> 2931 and <emphasis> 2932nKeyActions</emphasis> 2933 specify the subset of the keys for which actions are reported. 2934 </para> 2935</listitem> 2936<listitem> 2937 <para><emphasis> 2938totalActions</emphasis> 2939 reports the total number of actions bound to the returned keys. 2940 </para> 2941</listitem> 2942<listitem> 2943 <para>The <emphasis> 2944count </emphasis> 2945field of the <emphasis> 2946actsRtrn</emphasis> 2947 return value has <emphasis> 2948nKeyActions</emphasis> 2949 entries of type CARD8, which specify the number of actions bound to 2950consecutive keys starting from <emphasis> 2951firstKeyAction</emphasis> 2952. The <emphasis> 2953acts</emphasis> 2954 field of <emphasis> 2955actsRtrn</emphasis> 2956 has <emphasis> 2957totalActions</emphasis> 2958 elements of type KB_ACTION and specifies the actions bound to the keys. 2959 </para> 2960</listitem> 2961</itemizedlist> 2962 2963<para> 2964If <emphasis> 2965XkbKeyBehaviorsMask</emphasis> 2966 is set in <emphasis> 2967present</emphasis> 2968: 2969</para> 2970 2971<itemizedlist> 2972<listitem> 2973 <para>The <emphasis> 2974firstKeyBehavior</emphasis> 2975 and <emphasis> 2976nKeyBehaviors</emphasis> 2977 return values report the range of keyboard keys for which behaviors will be 2978reported. 2979 </para> 2980</listitem> 2981<listitem> 2982 <para>The <emphasis> 2983totalKeyBehaviors</emphasis> 2984 return value reports the number of keys in the range to be reported that have 2985non-default values. 2986 </para> 2987</listitem> 2988<listitem> 2989 <para>The <emphasis> 2990behaviorsRtrn</emphasis> 2991 value has <emphasis> 2992totalKeyBehaviors</emphasis> 2993 entries of type KB_BEHAVIOR. Each entry specifies a key in the range for which 2994behaviors are being reported and the behavior associated with that key. Any 2995keys in that range that do not have an entry in <emphasis> 2996behaviorsRtrn</emphasis> 2997 have the default behavior, <emphasis> 2998KB_Default</emphasis> 2999. 3000 </para> 3001</listitem> 3002</itemizedlist> 3003 3004<para> 3005If <emphasis> 3006XkbExplicitComponentsMask</emphasis> 3007 is set in <emphasis> 3008present</emphasis> 3009: 3010</para> 3011 3012<itemizedlist> 3013<listitem> 3014 <para>The <emphasis> 3015firstKeyExplicit</emphasis> 3016 and <emphasis> 3017nKeyExplicit</emphasis> 3018 return values report the range of keyboard keys for which the set of explicit 3019components is to be returned. 3020 </para> 3021</listitem> 3022<listitem> 3023 <para>The <emphasis> 3024totalKeyExplicit</emphasis> 3025 return value reports the number of keys in the range specified by <emphasis> 3026firstKeyExplicit</emphasis> 3027 and <emphasis> 3028nKeyExplicit</emphasis> 3029 that have one or more explicit components. 3030 </para> 3031</listitem> 3032<listitem> 3033 <para>The <emphasis> 3034explicitRtrn</emphasis> 3035 return value has <emphasis> 3036totalKeyExplicit</emphasis> 3037 entries of type KB_KEYEXPLICIT. Each entry specifies the a key in the range 3038for which explicit components are being reported and the explicit components 3039that are bound to it. Any keys in that range that do not have an entry in 3040<emphasis> 3041explicitRtrn</emphasis> 3042 have no explicit components. 3043 </para> 3044</listitem> 3045</itemizedlist> 3046 3047<para> 3048If <emphasis> 3049XkbModifierMapMask</emphasis> 3050 is set in <emphasis> 3051present</emphasis> 3052: 3053</para> 3054 3055<itemizedlist> 3056<listitem> 3057 <para>The <emphasis> 3058firstModMapKey</emphasis> 3059 and <emphasis> 3060nModMapKeys</emphasis> 3061 return values report the range of keyboard keys for which the modifier map is 3062to be reported. 3063 </para> 3064</listitem> 3065<listitem> 3066 <para>The <emphasis> 3067totalModMapKeys</emphasis> 3068 return value reports the number of keys in the range specified by <emphasis> 3069firstModMapKey</emphasis> 3070 and <emphasis> 3071nModMapKeys</emphasis> 3072 that are bound with to one or more modifiers. 3073 </para> 3074</listitem> 3075<listitem> 3076 <para>The <emphasis> 3077modmapRtrn</emphasis> 3078 return value has <emphasis> 3079totalModMapKeys</emphasis> 3080 entries of type KB_KEYMODMAP. Each entry specifies the a key in the range for 3081which the modifier map is being reported and the set of modifiers that are 3082bound to that key. Any keys in that range that do not have an entry in 3083<emphasis> 3084modmapRtrn</emphasis> 3085 are not associated with any modifiers by the modifier mapping. 3086 </para> 3087</listitem> 3088</itemizedlist> 3089 3090<para> 3091If <emphasis> 3092XkbVirtualModMapMask</emphasis> 3093 is set in <emphasis> 3094present</emphasis> 3095: 3096</para> 3097 3098<itemizedlist> 3099<listitem> 3100 <para>The <emphasis> 3101firstVModMapKey</emphasis> 3102 and <emphasis> 3103nVModMapKeys</emphasis> 3104 return values report the range of keyboard keys for which the virtual modifier 3105map is to be reported. 3106 </para> 3107</listitem> 3108<listitem> 3109 <para>The <emphasis> 3110totalVModMapKeys</emphasis> 3111 return value reports the number of keys in the range specified by <emphasis> 3112firstVModMapKey</emphasis> 3113 and <emphasis> 3114nVModMapKeys</emphasis> 3115 that are bound with to or more virtual modifiers. 3116 </para> 3117</listitem> 3118<listitem> 3119 <para>The <emphasis> 3120vmodmapRtrn</emphasis> 3121 return value has <emphasis> 3122totalVModMapKeys</emphasis> 3123 entries of type KB_KEYVMODMAP. Each entry specifies the a key in the range for 3124which the virtual modifier map is being reported and the set of virtual 3125modifiers that are bound to that key. Any keys in that range that do not have 3126an entry in <emphasis> 3127vmodmapRtrn</emphasis> 3128 are not associated with any virtual modifiers, 3129 </para> 3130</listitem> 3131</itemizedlist> 3132 3133<para> 3134If <emphasis> 3135XkbVirtualModsMask</emphasis> 3136 is set in <emphasis> 3137present</emphasis> 3138: 3139</para> 3140 3141<itemizedlist> 3142<listitem> 3143 <para>The <emphasis> 3144virtualMods</emphasis> 3145 return value is a mask with one bit per virtual modifier which specifies the 3146virtual modifiers for which a set of corresponding real modifiers is to be 3147returned. 3148 </para> 3149</listitem> 3150<listitem> 3151 <para>The <emphasis> 3152vmodsRtrn</emphasis> 3153 return value is a list with one entry of type KEYBUTMASK for each virtual 3154modifier that is specified in <emphasis> 3155virtualMods</emphasis> 3156. The entries in <emphasis> 3157vmodsRtrn</emphasis> 3158 contain the real modifier bindings for the specified virtual modifiers, 3159beginning with the lowest-numbered virtual modifier that is present in 3160<emphasis> 3161virtualMods</emphasis> 3162 and proceeding to the highest. 3163 </para> 3164</listitem> 3165</itemizedlist> 3166 3167<para> 3168If any of these bits are not set in <emphasis> 3169present</emphasis> 3170, the corresponding numeric fields all have the value zero, and the 3171corresponding lists are all of length zero. 3172</para> 3173 3174 3175 3176<informaltable frame='none' tabstyle='proto'> 3177<?dbfo keep-together="always" ?> 3178<tgroup cols='1' align='left' colsep='0' rowsep='0'> 3179<colspec colname='c1' colwidth='1.0*'/> 3180 <thead> 3181 <row> 3182 <entry role='protoname'>XkbSetMap</entry> 3183 </row> 3184 </thead> 3185 <tbody> 3186 <row> 3187 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 3188 </row> 3189 <row> 3190 <entry role='protoname'> 3191flags: { <emphasis> 3192SetMapResizeTypes, SetMapRecomputeActions </emphasis> 3193}</entry> 3194 </row> 3195 <row> 3196 <entry role='protoname'> 3197present: KB_MAPPARTMASK</entry> 3198 </row> 3199 <row> 3200 <entry role='protoname'> 3201minKeyCode, maxKeyCode: KEYCODE</entry> 3202 </row> 3203 <row> 3204 <entry role='protoname'> 3205firstType, nTypes: CARD8</entry> 3206 </row> 3207 <row> 3208 <entry role='protoname'> 3209firstKeySym, firstKeyAction: KEYCODE</entry> 3210 </row> 3211 <row> 3212 <entry role='protoname'> 3213nKeySyms, nKeyActions: CARD8</entry> 3214 </row> 3215 <row> 3216 <entry role='protoname'> 3217totalSyms, totalActions: CARD16</entry> 3218 </row> 3219 <row> 3220 <entry role='protoname'> 3221firstKeyBehavior, firstKeyExplicit: KEYCODE</entry> 3222 </row> 3223 <row> 3224 <entry role='protoname'> 3225nKeyBehaviors, nKeyExplicit: CARD8</entry> 3226 </row> 3227 <row> 3228 <entry role='protoname'> 3229totalKeyBehaviors, totalKeyExplicit: CARD8</entry> 3230 </row> 3231 <row> 3232 <entry role='protoname'> 3233firstModMapKey, firstVModMapKey: KEYCODE</entry> 3234 </row> 3235 <row> 3236 <entry role='protoname'> 3237nModMapKeys, nVModMapKeys: CARD8</entry> 3238 </row> 3239 <row> 3240 <entry role='protoname'> 3241totalModMapKeys, totalVModMapKeys: CARD8</entry> 3242 </row> 3243 <row> 3244 <entry role='protoname'> 3245virtualMods: VMODMASK</entry> 3246 </row> 3247 <row> 3248 <entry role='protoname'> 3249types: LISTofKB_KEYTYPE</entry> 3250 </row> 3251 <row> 3252 <entry role='protoname'> 3253syms: LISTofKB_KEYSYMMAP</entry> 3254 </row> 3255 <row> 3256 <entry role='protoname'> 3257actions: { count: LISTofCARD8, actions: LISTofKB_ACTION }</entry> 3258 </row> 3259 <row> 3260 <entry role='protoname'> 3261behaviors: LISTofKB_BEHAVIOR</entry> 3262 </row> 3263 <row> 3264 <entry role='protoname'> 3265vmods: LISTofKEYMASK</entry> 3266 </row> 3267 <row> 3268 <entry role='protoname'> 3269explicit: LISTofKB_EXPLICIT</entry> 3270 </row> 3271 <row> 3272 <entry role='protoname'> 3273modmap: LISTofKB_KEYMODMAP</entry> 3274 </row> 3275 <row> 3276 <entry role='protoname'> 3277vmodmap: LISTofKB_KEYVMODMAP</entry> 3278 </row> 3279 3280 <row> 3281 <entry role='protoerror'>Errors: <emphasis> 3282Keyboard</emphasis> 3283, <emphasis> 3284Value</emphasis> 3285, <emphasis> 3286Match</emphasis> 3287, <emphasis> 3288Alloc</emphasis> 3289</entry> 3290 </row> 3291 3292 </tbody> 3293 </tgroup> 3294</informaltable> 3295 3296<para> 3297This request changes the indicated parts of the keyboard specified by <emphasis> 3298deviceSpec</emphasis> 3299. With XKB, the effect of a key release is independent of the keyboard mapping 3300at the time of the release, so this request can be processed regardless of the 3301logical state of the modifier keys at the time of the request. 3302</para> 3303 3304 3305<para> 3306The <emphasis> 3307present</emphasis> 3308 field specifies the keyboard map components contained to be changed. The bits 3309in <emphasis> 3310present</emphasis> 3311 affect the interpretation of the other fields as follows: 3312</para> 3313 3314 3315<para> 3316If <emphasis> 3317XkbKeyTypesMask</emphasis> 3318 is set in <emphasis> 3319present</emphasis> 3320, <emphasis> 3321firstType</emphasis> 3322 and <emphasis> 3323nTypes</emphasis> 3324 specify a subset of the key types bound to the keyboard to be changed or 3325created. The index of the first key type to be changed must be less than or 3326equal to the unmodified length of the list of key types or a <emphasis> 3327Value</emphasis> 3328 error results. 3329</para> 3330 3331 3332<para> 3333If <emphasis> 3334XkbKeyTypesMask</emphasis> 3335 is set in <emphasis> 3336present</emphasis> 3337 and <emphasis> 3338SetMapResizeTypes</emphasis> 3339 is set in <emphasis> 3340flags</emphasis> 3341, the server resizes the list of key types bound to the keyboard so that the 3342last key type specified by this request is the last element in the list. If the 3343list of key types is shrunk, any existing key definitions that use key types 3344that eliminated are automatically assigned key types from the list of canonical 3345key types as described in <link linkend='Assigning_Types_To_Groups_of_Symbols_for_a_Key'> 3346Assigning Types To Groups of Symbols for a Key</link>. The list of key types 3347bound to a keyboard must always include the four canonical types and cannot 3348have more than <emphasis> 3349XkbMaxTypesPerKey</emphasis> 3350 (32) types; any attempt to reduce the number of types bound to a keyboard 3351below four or above <emphasis> 3352XkbMaxTypesPerKey</emphasis> 3353 causes a <emphasis> 3354Value</emphasis> 3355 error. Symbolic names for newly created key types or levels within a key type 3356are initialized to <emphasis> 3357None</emphasis> 3358. 3359</para> 3360 3361 3362<para> 3363If <emphasis> 3364XkbKeyTypesMask</emphasis> 3365 is set in <emphasis> 3366present</emphasis> 3367, the types list has <emphasis> 3368nTypes</emphasis> 3369 entries of type KB_KEYTYPE.Each key type specified in <emphasis> 3370types</emphasis> 3371 must be valid or a <emphasis> 3372Value</emphasis> 3373 error results. To be valid a key type definition must meet the following 3374criteria: 3375</para> 3376 3377<itemizedlist> 3378<listitem> 3379 <para>The <emphasis> 3380numLevels</emphasis> 3381 for the type must be greater than zero. 3382 </para> 3383</listitem> 3384<listitem> 3385 <para>If the key type is <emphasis> 3386ONE_LEVEL</emphasis> 3387 (i.e. index zero in the list of key types), <emphasis> 3388numLevels</emphasis> 3389 must be one. 3390 </para> 3391</listitem> 3392<listitem> 3393 <para>If the key type is <emphasis> 3394TWO_LEVEL</emphasis> 3395 or <emphasis> 3396KEYPAD</emphasis> 3397, or <emphasis> 3398ALPHABETIC</emphasis> 3399 (i.e. index one, two, or three in the lest of key types) group width must be 3400two. 3401 </para> 3402</listitem> 3403</itemizedlist> 3404 3405<para> 3406Each key type in types must also be internally consistent, or a Match error 3407results. To be internally consistent, a key type definition must meet the 3408following criteria: 3409</para> 3410 3411<itemizedlist> 3412<listitem> 3413 <para>Each map entry must specify a resulting level that is legal for the 3414type. 3415 </para> 3416</listitem> 3417<listitem> 3418 <para>Any real or virtual modifiers specified in any of the map entries must 3419also be specified in the <emphasis> 3420mods</emphasis> 3421 for the type. 3422 </para> 3423</listitem> 3424</itemizedlist> 3425 3426<para> 3427If <emphasis> 3428XkbKeySymsMask</emphasis> 3429 is set in <emphasis> 3430present</emphasis> 3431, <emphasis> 3432firstKeySym</emphasis> 3433 and <emphasis> 3434nKeySyms</emphasis> 3435 specify a subset of the keyboard keys to which new symbols are to be assigned 3436and <emphasis> 3437totalSyms</emphasis> 3438 specifies the total number of symbols to be assigned to those keys. If any of 3439the keys specified by <emphasis> 3440firstKeySym</emphasis> 3441 and <emphasis> 3442nKeySyms</emphasis> 3443 are not legal, a <emphasis> 3444Match</emphasis> 3445 error results. The <emphasis> 3446syms</emphasis> 3447 list has <emphasis> 3448nKeySyms</emphasis> 3449 elements of type KB_KEYSYMMAP. Each key in the resulting key symbol map must 3450be valid and internally consistent or a <emphasis> 3451Value</emphasis> 3452 error results. To be valid and internally consistent, a key symbol map must 3453meet the following criteria: 3454</para> 3455 3456<itemizedlist> 3457<listitem> 3458 <para>The key type indices must specify legal result key types. 3459 </para> 3460</listitem> 3461<listitem> 3462 <para>The number of groups specified by <emphasis> 3463groupInfo</emphasis> 3464 must be in the range <emphasis> 34650…4</emphasis> 3466. 3467 </para> 3468</listitem> 3469<listitem> 3470 <para>The <emphasis> 3471width</emphasis> 3472 of the key symbol map must be equal to <emphasis> 3473numLevels</emphasis> 3474 of the widest key type bound to the key. 3475 </para> 3476</listitem> 3477<listitem> 3478 <para>The number of symbols, <emphasis> 3479nSyms</emphasis> 3480, must equal the number of groups times <emphasis> 3481width</emphasis> 3482. 3483 </para> 3484</listitem> 3485</itemizedlist> 3486 3487<para> 3488If <emphasis> 3489XkbKeyActionsMask</emphasis> 3490 is set in <emphasis> 3491present</emphasis> 3492, <emphasis> 3493firstKeyAction</emphasis> 3494 and <emphasis> 3495nKeyActions</emphasis> 3496 specify a subset of the keyboard keys to which new actions are to be assigned 3497and <emphasis> 3498totalActions</emphasis> 3499 specifies the total number of actions to be assigned to those keys. If any of 3500the keys specified by <emphasis> 3501firstKeyAction</emphasis> 3502 and <emphasis> 3503nKeyActions</emphasis> 3504 are not legal, a <emphasis> 3505Match</emphasis> 3506 error results. The <emphasis> 3507count</emphasis> 3508 field of the <emphasis> 3509actions</emphasis> 3510 return value has <emphasis> 3511nKeyActions</emphasis> 3512 elements of type CARD8; each element of <emphasis> 3513count</emphasis> 3514 specifies the number of actions bound to the corresponding key. The <emphasis> 3515actions</emphasis> 3516 list in the <emphasis> 3517actions</emphasis> 3518 field has <emphasis> 3519totalActions</emphasis> 3520 elements of type KB_ACTION. These actions are assigned to each target key in 3521turn, as specified by <emphasis> 3522count</emphasis> 3523. The list of actions assigned to each key must either be empty or have exactly 3524as many actions as the key has symbols, or a <emphasis> 3525Match</emphasis> 3526 error results. 3527</para> 3528 3529 3530<para> 3531If <emphasis> 3532XkbKeyBehaviorsMask</emphasis> 3533 is set in <emphasis> 3534present</emphasis> 3535, <emphasis> 3536firstKeyBehavior</emphasis> 3537 and <emphasis> 3538nKeyBehaviors</emphasis> 3539 specify a subset of the keyboard keys to which new behaviors are to be 3540assigned, and <emphasis> 3541totalKeyBehaviors</emphasis> 3542 specifies the total number of keys in that range to be assigned non-default 3543behavior. If any of the keys specified by <emphasis> 3544firstKeyBehavior</emphasis> 3545 and <emphasis> 3546nKeyBehaviors</emphasis> 3547 are not legal, a <emphasis> 3548Match</emphasis> 3549 error results. The <emphasis> 3550behaviors</emphasis> 3551 list has <emphasis> 3552totalKeyBehaviors</emphasis> 3553 elements of type KB_BEHAVIOR; each entry of <emphasis> 3554behaviors</emphasis> 3555 specifies a key in the specified range and a new behavior for that key; any 3556key that falls in the range specified by <emphasis> 3557firstBehavior</emphasis> 3558 and <emphasis> 3559nBehaviors</emphasis> 3560 for which no behavior is specified in <emphasis> 3561behaviors</emphasis> 3562 is assigned the default behavior, <emphasis> 3563KB_Default</emphasis> 3564. The new behaviors must be legal, or a <emphasis> 3565Value</emphasis> 3566 error results. To be legal, the behavior specified in the <emphasis> 3567XkbSetMap</emphasis> 3568 request must: 3569</para> 3570 3571<itemizedlist> 3572<listitem> 3573 <para>Specify a key in the range indicated by <emphasis> 3574firstKeyBehavior</emphasis> 3575 and <emphasis> 3576nKeyBehaviors</emphasis> 3577. 3578 </para> 3579</listitem> 3580<listitem> 3581 <para>Not specify the <emphasis> 3582permanent</emphasis> 3583 flag; permanent behaviors cannot be set or changed using the <emphasis> 3584XkbSetMap</emphasis> 3585 request. 3586 </para> 3587</listitem> 3588<listitem> 3589 <para>If present, the <emphasis> 3590KB_Overlay1</emphasis> 3591 and <emphasis> 3592KB_Overlay2</emphasis> 3593 behaviors must specify a keycode for the overlay key that is valid for the 3594current keyboard. 3595 </para> 3596</listitem> 3597<listitem> 3598 <para>If present, the <emphasis> 3599KB_RadioGroup</emphasis> 3600 behavior must specify a legal index (0…31) for the radio group to which the 3601key belongs. 3602 </para> 3603</listitem> 3604</itemizedlist> 3605 3606<para> 3607Key behaviors that are not recognized by the server are accepted but ignored. 3608Attempts to replace a "permanent" behavior are silently ignored; the behavior 3609is not replaced, but not error is generated and any other components specified 3610in the <emphasis> 3611XkbSetMap</emphasis> 3612 request are updated, as appropriate. 3613</para> 3614 3615 3616<para> 3617If <emphasis> 3618XkbVirtualModsMask</emphasis> 3619 is set in <emphasis> 3620present</emphasis> 3621, <emphasis> 3622virtualMods</emphasis> 3623 is a mask which specifies the virtual modifiers to be rebound. The <emphasis> 3624vmods</emphasis> 3625 list specifies the real modifiers that are bound to each of the virtual 3626modifiers specified in <emphasis> 3627virtualMods</emphasis> 3628, starting from the lowest numbered virtual modifier and progressing upward. 3629Any virtual modifier that is not specified in <emphasis> 3630virtualMods</emphasis> 3631 has no corresponding entry in <emphasis> 3632vmods</emphasis> 3633, so the <emphasis> 3634vmods</emphasis> 3635 list has one entry for each bit that is set in <emphasis> 3636virtualMods</emphasis> 3637. 3638</para> 3639 3640 3641<para> 3642If <emphasis> 3643XkbExplicitComponentsMask</emphasis> 3644 is set in <emphasis> 3645present</emphasis> 3646, <emphasis> 3647firstKeyExplicit</emphasis> 3648 and <emphasis> 3649nKeyExplicit</emphasis> 3650 specify a subset of the keyboard keys to which new explicit components are to 3651be assigned, and <emphasis> 3652totalKeyExplicit</emphasis> 3653 specifies the total number of keys in that range that have at least one 3654explicit component. The <emphasis> 3655explicit</emphasis> 3656 list has <emphasis> 3657totalKeyExplicit</emphasis> 3658 elements of type KB_KEYEXPLICIT; each entry of <emphasis> 3659explicit</emphasis> 3660 specifies a key in the specified range and a new set of explicit components 3661for that key. Any key that falls in the range specified by <emphasis> 3662firstKeyExplicit</emphasis> 3663 and <emphasis> 3664nKeyExplicit</emphasis> 3665 that is not assigned some value in <emphasis> 3666explicit</emphasis> 3667 has no explicit components. 3668</para> 3669 3670 3671<para> 3672If <emphasis> 3673XkbModifierMapMask</emphasis> 3674 is set in <emphasis> 3675present</emphasis> 3676, <emphasis> 3677firstModMapKey</emphasis> 3678 and <emphasis> 3679nModMapKeys</emphasis> 3680 specify a subset of the keyboard keys for which new modifier mappings are to 3681be assigned, and <emphasis> 3682totalModMapKeys</emphasis> 3683 specifies the total number of keys in that range to which at least one 3684modifier is bound. The <emphasis> 3685modmap</emphasis> 3686 list has <emphasis> 3687totalModMapKeys</emphasis> 3688 elements of type KB_KEYMODMAP; each entry of <emphasis> 3689modmap</emphasis> 3690 specifies a key in the specified range and a new set of modifiers to be 3691associated with that key. Any key that falls in the range specified by 3692<emphasis> 3693firstModMapKey</emphasis> 3694 and <emphasis> 3695nModMapKeys</emphasis> 3696 that is not assigned some value in <emphasis> 3697modmap</emphasis> 3698 has no associated modifiers. 3699</para> 3700 3701 3702<para> 3703If the modifier map is changed by the <emphasis> 3704XkbSetMap</emphasis> 3705 request, any changes are also reflected in the core protocol modifier mapping. 3706Changes to the core protocol modifier mapping are reported to XKB-unaware 3707clients via <emphasis> 3708MappingNotify</emphasis> 3709 events and can be retrieved with the core protocol <emphasis> 3710GetModifierMapping</emphasis> 3711 request. 3712</para> 3713 3714 3715<para> 3716If <emphasis> 3717XkbVirtualModMapMask</emphasis> 3718 is set in <emphasis> 3719present</emphasis> 3720, <emphasis> 3721firstVModMapKey</emphasis> 3722 and <emphasis> 3723nVModMapKeys</emphasis> 3724 specify a subset of the keyboard keys for which new modifier mappings are to 3725be assigned, and <emphasis> 3726totalVModMapKeys</emphasis> 3727 specifies the total number of keys in that range to which at least one virtual 3728modifier is bound. The <emphasis> 3729vmodmap</emphasis> 3730 list has <emphasis> 3731totalVModMapKeys</emphasis> 3732 elements of type KB_KEYVMODMAP; each entry of <emphasis> 3733vmodmap</emphasis> 3734 specifies a key in the specified range and a new set of virtual modifiers to 3735be associated with that key. Any key that falls in the range specified by 3736<emphasis> 3737firstVModMapKey</emphasis> 3738 and <emphasis> 3739nVModMapKeys</emphasis> 3740 that is not assigned some value in <emphasis> 3741vmodmap</emphasis> 3742 has no associated virtual modifiers. 3743</para> 3744 3745 3746<para> 3747If the resulting keyboard map is legal, the server updates the keyboard map. 3748Changes to some keyboard components have indirect effects on others: 3749</para> 3750 3751 3752<para> 3753If the <emphasis> 3754XkbSetMapRecomputeActions</emphasis> 3755 bit is set in <emphasis> 3756flags</emphasis> 3757, the actions associated with any keys for which symbol or modifier bindings 3758were changed by this request are recomputed as described in 3759<link linkend='Assigning_Actions_To_Keys'>Assigning Actions To Keys</link>. Note 3760that actions are recomputed <emphasis> 3761after </emphasis> 3762any actions specified in this request are bound to keys, so the actions 3763specified in this request might be clobbered by the automatic assignment of 3764actions to keys. 3765</para> 3766 3767 3768<para> 3769If the group width of an existing key type is changed, the list of symbols 3770associated with any keys of the changed type might be resized accordingly. If 3771the list increases in size, any unspecified new symbols are initialized to 3772<emphasis> 3773NoSymbol</emphasis> 3774. 3775</para> 3776 3777 3778<para> 3779If the list of actions associated with a key is not empty, changing the key 3780type of the key resizes the list. Unspecified new actions are calculated by 3781applying any keyboard symbol interpretations to the corresponding symbols. 3782</para> 3783 3784 3785<para> 3786The number of groups global to the keyboard is always equal to the largest 3787number of groups specified by any of the key symbol maps. Changing the number 3788of groups in one or more key symbol maps may change the number of groups global 3789to the keyboard. 3790</para> 3791 3792 3793<para> 3794Assigning key behavior <emphasis> 3795KB_RadioGroup</emphasis> 3796 to a key adds that key as a member of the specified radio group. Changing a 3797key with the existing behavior <emphasis> 3798KB_RadioGroup</emphasis> 3799 removes that key from the group. Changing the elements of a radio group can 3800cause synthetic key press or key release events if the key to be added or 3801removed is logically down at the time of the change. 3802</para> 3803 3804 3805<para> 3806Changing a key with behavior <emphasis> 3807KB_Lock</emphasis> 3808 causes a synthetic key release event if the key is logically but not 3809physically down at the time of the change. 3810</para> 3811 3812 3813<para> 3814This request sends an <emphasis> 3815XkbMapNotify</emphasis> 3816 event which reflects both explicit and indirect map changes to any interested 3817clients. If any symbolic names are changed, it sends a <emphasis> 3818XkbNamesNotify</emphasis> 3819 reflecting the changes to any interested clients. XKB-unaware clients are 3820notified of keyboard changes via core protocol <emphasis> 3821MappingNotify</emphasis> 3822 events. 3823</para> 3824 3825 3826<para> 3827Key press and key release events caused by changing key behavior may cause 3828additional <emphasis> 3829XkbStateNotify</emphasis> 3830 or <emphasis> 3831XkbIndicatorStateNotify</emphasis> 3832 events. 3833</para> 3834 3835 3836</sect2> 3837<sect2 id='Querying_and_Changing_the_Compatibility_Map'> 3838<title>Querying and Changing the Compatibility Map</title> 3839 3840 3841<informaltable frame='none' tabstyle='proto'> 3842<?dbfo keep-together="always" ?> 3843<tgroup cols='1' align='left' colsep='0' rowsep='0'> 3844<colspec colname='c1' colwidth='1.0*'/> 3845 <thead> 3846 <row> 3847 <entry role='protoname'>XkbGetCompatMap</entry> 3848 </row> 3849 </thead> 3850 <tbody> 3851 <row> 3852 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 3853 </row> 3854 <row> 3855 <entry role='protoname'> 3856groups: KB_GROUPMASK</entry> 3857 </row> 3858 <row> 3859 <entry role='protoname'> 3860getAllSI: BOOL</entry> 3861 </row> 3862 <row> 3863 <entry role='protoname'> 3864firstSI, nSI: CARD16 3865 </entry> 3866 </row> 3867 <row> 3868 <entry role='protoreply'> 3869deviceID: CARD8 3870 </entry> 3871 </row> 3872 <row> 3873 <entry role='protoreply'> 3874groupsRtrn: KB_GROUPMASK 3875 </entry> 3876 </row> 3877 <row> 3878 <entry role='protoreply'> 3879firstSIRtrn, nSIRtrn, nTotalSI: CARD16 3880 </entry> 3881 </row> 3882 <row> 3883 <entry role='protoreply'> 3884siRtrn: LISTofKB_SYMINTERP 3885 </entry> 3886 </row> 3887 <row> 3888 <entry role='protoreply'> 3889groupRtrn: LISTofKB_MODDEF</entry> 3890 </row> 3891 <row> 3892 <entry role='protoerror'>Errors: <emphasis> 3893Keyboard</emphasis> 3894, <emphasis> 3895Match</emphasis> 3896, <emphasis> 3897Alloc</emphasis> 3898</entry> 3899 </row> 3900 3901 </tbody> 3902 </tgroup> 3903</informaltable> 3904 3905<para> 3906This request returns the listed compatibility map components for the keyboard 3907specified by <emphasis> 3908deviceSpec</emphasis> 3909. If <emphasis> 3910deviceSpec</emphasis> 3911 does not specify a valid keyboard device, a <emphasis> 3912Keyboard</emphasis> 3913 Error results. On return, <emphasis> 3914deviceID</emphasis> 3915 reports the input extension identifier of the keyboard device or <emphasis> 39160</emphasis> 3917 if the server does not support the input extension. 3918</para> 3919 3920 3921<para> 3922If <emphasis> 3923getAllSI</emphasis> 3924 is <emphasis> 3925False</emphasis> 3926, <emphasis> 3927firstSI</emphasis> 3928 and <emphasis> 3929nSI</emphasis> 3930 specify a subset of the symbol interpretations to be returned; if used, 3931<emphasis> 3932nSI</emphasis> 3933 must be greater than <emphasis> 39340</emphasis> 3935 and all of the elements specified by <emphasis> 3936firstSI</emphasis> 3937 and <emphasis> 3938nSI</emphasis> 3939 must be defined or a <emphasis> 3940Value</emphasis> 3941 error results. If <emphasis> 3942getAllSyms</emphasis> 3943 is <emphasis> 3944True</emphasis> 3945, the server ignores <emphasis> 3946firstSym</emphasis> 3947 and <emphasis> 3948nSyms</emphasis> 3949 and returns all of the symbol interpretations defined for the keyboard. 3950</para> 3951 3952 3953<para> 3954The <emphasis> 3955groups</emphasis> 3956 mask specifies the groups for which compatibility maps are to be returned. 3957</para> 3958 3959 3960<para> 3961The <emphasis> 3962nTotalSI</emphasis> 3963 return value reports the total number of symbol interpretations defined for 3964the keyboard. On successful return, the <emphasis> 3965siRtrn</emphasis> 3966 return list contains the definitions for <emphasis> 3967nSIRtrn</emphasis> 3968 symbol interpretations beginning at <emphasis> 3969firstSIRtrn</emphasis> 3970. 3971</para> 3972 3973 3974<para> 3975The <emphasis> 3976groupRtrn</emphasis> 3977 return values report the entries in the group compatibility map for any groups 3978specified in the <emphasis> 3979groupsRtrn</emphasis> 3980 return value. 3981</para> 3982 3983 3984 3985<informaltable frame='none' tabstyle='proto'> 3986<?dbfo keep-together="always" ?> 3987<tgroup cols='1' align='left' colsep='0' rowsep='0'> 3988<colspec colname='c1' colwidth='1.0*'/> 3989 <thead> 3990 <row> 3991 <entry role='protoname'>XkbSetCompatMap</entry> 3992 </row> 3993 </thead> 3994 <tbody> 3995 <row> 3996 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 3997 </row> 3998 <row> 3999 <entry role='protoname'> 4000recomputeActions: BOOL</entry> 4001 </row> 4002 <row> 4003 <entry role='protoname'> 4004truncateSI: BOOL</entry> 4005 </row> 4006 <row> 4007 <entry role='protoname'> 4008groups: KB_GROUPMASK</entry> 4009 </row> 4010 <row> 4011 <entry role='protoname'> 4012firstSI, nSI: CARD16</entry> 4013 </row> 4014 <row> 4015 <entry role='protoname'> 4016si: LISTofKB_SYMINTERPRET</entry> 4017 </row> 4018 <row> 4019 <entry role='protoname'> 4020groupMaps: LISTofKB_MODDEF</entry> 4021 </row> 4022 4023 <row> 4024 <entry role='protoerror'>Errors: <emphasis> 4025Keyboard</emphasis> 4026, <emphasis> 4027Match</emphasis> 4028, <emphasis> 4029Value</emphasis> 4030, <emphasis> 4031Alloc</emphasis> 4032</entry> 4033 </row> 4034 4035 </tbody> 4036 </tgroup> 4037</informaltable> 4038 4039<para> 4040This request changes a specified subset of the compatibility map of the 4041keyboard indicated by <emphasis> 4042deviceSpec</emphasis> 4043. If <emphasis> 4044deviceSpec</emphasis> 4045 specifies an invalid device, a <emphasis> 4046Keyboard</emphasis> 4047 error results and nothing is changed. 4048</para> 4049 4050 4051<para> 4052The <emphasis> 4053firstSI</emphasis> 4054 and <emphasis> 4055nSI</emphasis> 4056 fields specify a subset of the keyboard symbol interpretations to be changed. 4057The <emphasis> 4058si</emphasis> 4059 list specifies new values for each of the interpretations in that range. 4060</para> 4061 4062 4063<para> 4064The first symbol interpretation to be changed, <emphasis> 4065firstSI</emphasis> 4066, must be less than or equal to the unchanged length of the list of symbol 4067interpretations, or a <emphasis> 4068Value</emphasis> 4069 error results. If the resulting list would be larger than the unchanged list, 4070it server list of symbol interpretations is automatically increased in size. 4071Otherwise, if <emphasis> 4072truncateSyms</emphasis> 4073 is <emphasis> 4074True</emphasis> 4075, the server deletes any symbol interpretations after the last element changed 4076by this request, and reduces the length of the list accordingly. 4077</para> 4078 4079 4080<para> 4081The <emphasis> 4082groupMaps</emphasis> 4083 fields contain new definitions for a subset of the group compatibility map; 4084<emphasis> 4085groups</emphasis> 4086 specifies the group compatibility map entries to be updated from <emphasis> 4087groupMaps</emphasis> 4088. 4089</para> 4090 4091 4092<para> 4093 All changed compatibility maps and symbol interpretations must either ignore 4094group state or specify a legal range of groups, or a <emphasis> 4095Value</emphasis> 4096 error results. 4097</para> 4098 4099 4100<para> 4101If the <emphasis> 4102recomputeActions</emphasis> 4103 field is <emphasis> 4104True</emphasis> 4105, the server regenerates recalculates the actions bound to all keyboard keys by 4106applying the new symbol interpretations to the entire key symbol map, as 4107described in <link linkend='Assigning_Actions_To_Keys'>Assigning Actions To 4108Keys</link>. 4109</para> 4110 4111 4112</sect2> 4113<sect2 id='Querying_and_Changing_Indicators'> 4114<title>Querying and Changing Indicators</title> 4115 4116 4117<informaltable frame='none' tabstyle='proto'> 4118<?dbfo keep-together="always" ?> 4119<tgroup cols='1' align='left' colsep='0' rowsep='0'> 4120<colspec colname='c1' colwidth='1.0*'/> 4121 <thead> 4122 <row> 4123 <entry role='protoname'>XkbGetIndicatorState</entry> 4124 </row> 4125 </thead> 4126 <tbody> 4127 <row> 4128 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 4129 </row> 4130 <row> 4131 <entry role='protoreply'> 4132deviceID: CARD8 4133state: KB_INDICATORMASK</entry> 4134 </row> 4135 4136 <row> 4137 <entry role='protoerror'>Errors: <emphasis> 4138Keyboard</emphasis> 4139</entry> 4140 </row> 4141 4142 </tbody> 4143 </tgroup> 4144</informaltable> 4145 4146<para> 4147This request reports the current state of the indicators for the keyboard 4148specified by <emphasis> 4149deviceSpec</emphasis> 4150. If <emphasis> 4151deviceSpec</emphasis> 4152 does not specify a valid keyboard, a <emphasis> 4153Keyboard</emphasis> 4154 error results. 4155</para> 4156 4157 4158<para> 4159On successful return, the <emphasis> 4160deviceID</emphasis> 4161 field reports the input extension identifier of the keyboard or <emphasis> 41620</emphasis> 4163 if the server does not support the input extension. The <emphasis> 4164state</emphasis> 4165 return value reports the state of each of the thirty-two indicators on the 4166specified keyboard. The least-significant bit corresponds to indicator 0, the 4167most significant bit to indicator 31; if a bit is set, the corresponding 4168indicator is lit. 4169</para> 4170 4171 4172 4173<informaltable frame='none' tabstyle='proto'> 4174<?dbfo keep-together="always" ?> 4175<tgroup cols='1' align='left' colsep='0' rowsep='0'> 4176<colspec colname='c1' colwidth='1.0*'/> 4177 <thead> 4178 <row> 4179 <entry role='protoname'>XkbGetIndicatorMap</entry> 4180 </row> 4181 </thead> 4182 <tbody> 4183 <row> 4184 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 4185 </row> 4186 <row> 4187 <entry role='protoname'> 4188which: KB_INDICATORMASK 4189 </entry> 4190 </row> 4191 <row> 4192 <entry role='protoreply'> 4193deviceID: CARD8 4194 </entry> 4195 </row> 4196 <row> 4197 <entry role='protoreply'> 4198which: KB_INDICATORMASK 4199 </entry> 4200 </row> 4201 <row> 4202 <entry role='protoreply'> 4203realIndicators: KB_INDICATORMASK 4204 </entry> 4205 </row> 4206 <row> 4207 <entry role='protoreply'> 4208nIndicators: CARD8 4209 </entry> 4210 </row> 4211 <row> 4212 <entry role='protoreply'> 4213maps: LISTofKB_INDICATORMAP</entry> 4214 </row> 4215 <row> 4216 <entry role='protoerror'>Errors: <emphasis> 4217Keyboard</emphasis> 4218, <emphasis> 4219Value</emphasis> 4220</entry> 4221 </row> 4222 </tbody> 4223 </tgroup> 4224</informaltable> 4225 4226<para> 4227This request returns a subset of the maps for the indicators on the keyboard 4228specified by <emphasis> 4229deviceSpec</emphasis> 4230. If <emphasis> 4231deviceSpec</emphasis> 4232 does not specify a valid keyboard device, a <emphasis> 4233Keyboard</emphasis> 4234 error results. 4235</para> 4236 4237 4238<para> 4239The <emphasis> 4240which</emphasis> 4241 field specifies the subset to be returned; a set bit in the which field 4242indicates that the map for the corresponding indicator should be returned. 4243</para> 4244 4245 4246<para> 4247On successful return, the <emphasis> 4248deviceID</emphasis> 4249 field reports the input extension identifier of the keyboard or <emphasis> 42500</emphasis> 4251 if the server does not support the input extension. Any indicators specified 4252in <emphasis> 4253realIndicators</emphasis> 4254 are actually present on the keyboard; the rest are virtual indicators. Virtual 4255indicators do not directly cause any visible or audible effect when they change 4256state, but they do cause <emphasis> 4257XkbIndicatorStateNotify</emphasis> 4258 events. 4259</para> 4260 4261 4262<para> 4263The <emphasis> 4264maps</emphasis> 4265 return value reports the requested indicator maps. Indicator maps are 4266described in <link linkend='Indicator_Maps'>Indicator Maps</link> 4267</para> 4268 4269 4270 4271<informaltable frame='none' tabstyle='proto'> 4272<?dbfo keep-together="always" ?> 4273<tgroup cols='1' align='left' colsep='0' rowsep='0'> 4274<colspec colname='c1' colwidth='1.0*'/> 4275 <thead> 4276 <row> 4277 <entry role='protoname'>XkbSetIndicatorMap</entry> 4278 </row> 4279 </thead> 4280 <tbody> 4281 <row> 4282 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 4283 </row> 4284 <row> 4285 <entry role='protoname'> 4286which: KB_INDICATORMASK</entry> 4287 </row> 4288 <row> 4289 <entry role='protoname'> 4290maps: LISTofKB_INDICATORMAP</entry> 4291 </row> 4292 4293 <row> 4294 <entry role='protoerror'>Errors: <emphasis> 4295Keyboard</emphasis> 4296, <emphasis> 4297Value</emphasis> 4298</entry> 4299 </row> 4300 4301 </tbody> 4302 </tgroup> 4303</informaltable> 4304 4305<para> 4306This request changes a subset of the maps on the keyboard specified by 4307<emphasis> 4308deviceSpec</emphasis> 4309. If <emphasis> 4310deviceSpec</emphasis> 4311 does not specify a valid keyboard device, a <emphasis> 4312Keyboard</emphasis> 4313 error results. 4314</para> 4315 4316 4317<para> 4318The <emphasis> 4319which</emphasis> 4320 field specifies the subset to be changed; the <emphasis> 4321maps</emphasis> 4322 field contains the new definitions. 4323</para> 4324 4325 4326<para> 4327If successful, the new indicator maps are applied immediately. If any 4328indicators change state as a result of the new maps, the server generates 4329<emphasis> 4330XkbIndicatorStateNotify</emphasis> 4331 events as appropriate. 4332</para> 4333 4334 4335 4336<informaltable frame='none' tabstyle='proto'> 4337<?dbfo keep-together="always" ?> 4338<tgroup cols='1' align='left' colsep='0' rowsep='0'> 4339<colspec colname='c1' colwidth='1.0*'/> 4340 <thead> 4341 <row> 4342 <entry role='protoname'>XkbGetNamedIndicator</entry> 4343 </row> 4344 </thead> 4345 <tbody> 4346 <row> 4347 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 4348 </row> 4349 <row> 4350 <entry role='protoname'> 4351ledClass: KB_LEDCLASSSPEC</entry> 4352 </row> 4353 <row> 4354 <entry role='protoname'> 4355ledID: KB_IDSPEC</entry> 4356 </row> 4357 <row> 4358 <entry role='protoname'> 4359indicator: ATOM 4360 </entry> 4361 </row> 4362 <row> 4363 <entry role='protoreply'> 4364deviceID: CARD8 4365 </entry> 4366 </row> 4367 <row> 4368 <entry role='protoreply'> 4369supported: BOOL 4370 </entry> 4371 </row> 4372 <row> 4373 <entry role='protoreply'> 4374indicator: ATOM 4375 </entry> 4376 </row> 4377 <row> 4378 <entry role='protoreply'> 4379found: BOOL 4380 </entry> 4381 </row> 4382 <row> 4383 <entry role='protoreply'> 4384on: BOOL 4385 </entry> 4386 </row> 4387 <row> 4388 <entry role='protoreply'> 4389realIndicator: BOOL 4390 </entry> 4391 </row> 4392 <row> 4393 <entry role='protoreply'> 4394ndx: CARD8 4395 </entry> 4396 </row> 4397 <row> 4398 <entry role='protoreply'> 4399map: KB_INDICATORMAP</entry> 4400 </row> 4401 4402 <row> 4403 <entry role='protoerror'>Errors: <emphasis> 4404Keyboard</emphasis> 4405, <emphasis> 4406Atom</emphasis> 4407, <emphasis> 4408Value</emphasis> 4409</entry> 4410 </row> 4411 4412 </tbody> 4413 </tgroup> 4414</informaltable> 4415 4416<para> 4417This request returns information about the indicator specified by <emphasis> 4418ledClass</emphasis> 4419, <emphasis> 4420ledID</emphasis> 4421, and <emphasis> 4422indicator</emphasis> 4423 on the keyboard specified by <emphasis> 4424deviceSpec</emphasis> 4425. The <emphasis> 4426indicator</emphasis> 4427 field specifies the name of the indicator for which information is to be 4428returned. 4429</para> 4430 4431 4432<para> 4433If <emphasis> 4434deviceSpec</emphasis> 4435 does not specify a device with indicators, a <emphasis> 4436Keyboard</emphasis> 4437 error results. If <emphasis> 4438ledClass</emphasis> 4439 does not have the value <emphasis> 4440DfltXIClass</emphasis> 4441, <emphasis> 4442LedFeedbackClass</emphasis> 4443, or <emphasis> 4444KbdFeedbackClass</emphasis> 4445, a <emphasis> 4446Value</emphasis> 4447 error results. If <emphasis> 4448ledID</emphasis> 4449 does not have the value <emphasis> 4450DfltXIId</emphasis> 4451 or specify the identifier of a feedback of the class specified by <emphasis> 4452ledClass</emphasis> 4453 on the device specified by <emphasis> 4454deviceSpec</emphasis> 4455, a <emphasis> 4456Match</emphasis> 4457 error results. If <emphasis> 4458indicator</emphasis> 4459 is not a valid ATOM other than <emphasis> 4460None</emphasis> 4461, an <emphasis> 4462Atom</emphasis> 4463 error results. 4464</para> 4465 4466 4467<para> 4468This request is always supported with default class and identifier on the core 4469keyboard device. If the request specifies a device other than the core keyboard 4470device or a feedback class and identifier other than the defaults, and the 4471server does not support indicator names or indicator maps for extension 4472devices, the <emphasis> 4473supported</emphasis> 4474 return value is <emphasis> 4475False</emphasis> 4476 and the values of the other fields in the reply are undefined. If the client 4477which issued the unsupported request has also selected to do so, it will also 4478receive an <emphasis> 4479XkbExtensionDeviceNotify</emphasis> 4480 event which reports the attempt to use an unsupported feature, in this case 4481one or both of <emphasis> 4482XkbXI_IndicatorMaps</emphasis> 4483 or <emphasis> 4484XkbXI_IndicatorNames</emphasis> 4485. 4486</para> 4487 4488 4489<para> 4490Otherwise, <emphasis> 4491supported</emphasis> 4492 is <emphasis> 4493True</emphasis> 4494 and the <emphasis> 4495deviceID</emphasis> 4496 field reports the input extension identifier of the keyboard or <emphasis> 44970</emphasis> 4498 if the server does not support the input extension. The <emphasis> 4499indicator</emphasis> 4500 return value reports the name for which information was requested and the 4501<emphasis> 4502found</emphasis> 4503 return value is <emphasis> 4504True</emphasis> 4505 if an indicator with the specified name was found on the device. 4506</para> 4507 4508 4509<para> 4510If a matching indicator was found: 4511</para> 4512 4513<itemizedlist> 4514<listitem> 4515 <para>The <emphasis> 4516on</emphasis> 4517 return value reports the state of the indicator at the time of the request. 4518 </para> 4519</listitem> 4520<listitem> 4521 <para>The <emphasis> 4522realIndicator</emphasis> 4523 return value is <emphasis> 4524True</emphasis> 4525 if the requested indicator is actually present on the keyboard or <emphasis> 4526False</emphasis> 4527 if it is virtual. 4528 </para> 4529</listitem> 4530<listitem> 4531 <para>The <emphasis> 4532ndx</emphasis> 4533 return value reports the index of the indicator in the requested feedback. 4534 </para> 4535</listitem> 4536<listitem> 4537 <para>The <emphasis> 4538map</emphasis> 4539 return value reports the indicator map used by to automatically change the 4540state of the specified indicator in response to changes in keyboard state or 4541controls. 4542 </para> 4543</listitem> 4544</itemizedlist> 4545 4546<para> 4547If no matching indicator is found, the <emphasis> 4548found</emphasis> 4549 return value is <emphasis> 4550False</emphasis> 4551, and the <emphasis> 4552on</emphasis> 4553, <emphasis> 4554realIndicator</emphasis> 4555, <emphasis> 4556ndx</emphasis> 4557, and <emphasis> 4558map</emphasis> 4559 return values are undefined. 4560</para> 4561 4562 4563 4564<informaltable frame='none' tabstyle='proto'> 4565<?dbfo keep-together="always" ?> 4566<tgroup cols='1' align='left' colsep='0' rowsep='0'> 4567<colspec colname='c1' colwidth='1.0*'/> 4568 <thead> 4569 <row> 4570 <entry role='protoname'>XkbSetNamedIndicator</entry> 4571 </row> 4572 </thead> 4573 <tbody> 4574 <row> 4575 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 4576 </row> 4577 <row> 4578 <entry role='protoname'> 4579ledClass: KB_LEDCLASSSPEC</entry> 4580 </row> 4581 <row> 4582 <entry role='protoname'> 4583ledID: KB_IDSPEC</entry> 4584 </row> 4585 <row> 4586 <entry role='protoname'> 4587indicator: ATOM</entry> 4588 </row> 4589 <row> 4590 <entry role='protoname'> 4591setState: BOOL</entry> 4592 </row> 4593 <row> 4594 <entry role='protoname'> 4595on: BOOL</entry> 4596 </row> 4597 <row> 4598 <entry role='protoname'> 4599setMap: BOOL</entry> 4600 </row> 4601 <row> 4602 <entry role='protoname'> 4603createMap: BOOL</entry> 4604 </row> 4605 <row> 4606 <entry role='protoname'> 4607map: KB_SETINDICATORMAP</entry> 4608 </row> 4609 4610 <row> 4611 <entry role='protoerror'>Errors: <emphasis> 4612Keyboard</emphasis> 4613, <emphasis> 4614Atom</emphasis> 4615, <emphasis> 4616Access</emphasis> 4617</entry> 4618 </row> 4619 4620 </tbody> 4621 </tgroup> 4622</informaltable> 4623 4624<para> 4625This request changes various aspects of the indicator specified by <emphasis> 4626ledClass</emphasis> 4627, <emphasis> 4628ledID</emphasis> 4629, and <emphasis> 4630indicator</emphasis> 4631 on the keyboard specified by <emphasis> 4632deviceSpec</emphasis> 4633. The <emphasis> 4634indicator</emphasis> 4635 argument specifies the name of the indicator to be updated. 4636</para> 4637 4638 4639<para> 4640If <emphasis> 4641deviceSpec</emphasis> 4642 does not specify a device with indicators, a <emphasis> 4643Keyboard</emphasis> 4644 error results. If <emphasis> 4645ledClass</emphasis> 4646 does not have the value <emphasis> 4647DfltXIClass</emphasis> 4648, <emphasis> 4649LedFeedbackClass</emphasis> 4650, or <emphasis> 4651KbdFeedbackClass</emphasis> 4652, a <emphasis> 4653Value</emphasis> 4654 error results. If <emphasis> 4655ledID</emphasis> 4656 does not have the value <emphasis> 4657DfltXIId</emphasis> 4658 or specify the identifier of a feedback of the class specified by <emphasis> 4659ledClass</emphasis> 4660 on the device specified by <emphasis> 4661deviceSpec</emphasis> 4662, a <emphasis> 4663Match</emphasis> 4664 error results. If <emphasis> 4665indicator</emphasis> 4666 is not a valid ATOM other than <emphasis> 4667None</emphasis> 4668, an <emphasis> 4669Atom</emphasis> 4670 error results. 4671</para> 4672 4673 4674<para> 4675This request is always supported with default class and identifier on the core 4676keyboard device. If the request specifies a device other than the core keyboard 4677device or a feedback class and identifier other than the defaults, and the 4678server does not support indicator names or indicator maps for extension 4679devices, the <emphasis> 4680supported</emphasis> 4681 return value is <emphasis> 4682False</emphasis> 4683 and the values of the other fields in the reply are undefined. If the client 4684which issued the unsupported request has also selected to do so, it will also 4685receive an <emphasis> 4686XkbExtensionDeviceNotify</emphasis> 4687 event which reports the attempt to use an unsupported feature, in this case 4688one or both of <emphasis> 4689XkbXI_IndicatorMaps</emphasis> 4690 and <emphasis> 4691XkbXI_IndicatorNames</emphasis> 4692. 4693</para> 4694 4695 4696<para> 4697Otherwise, <emphasis> 4698supported</emphasis> 4699 is <emphasis> 4700True</emphasis> 4701 and the <emphasis> 4702deviceID</emphasis> 4703 field reports the input extension identifier of the keyboard or <emphasis> 47040</emphasis> 4705 if the server does not support the input extension. The <emphasis> 4706indicator</emphasis> 4707 return value reports the name for which information was requested and the 4708<emphasis> 4709found</emphasis> 4710 return value is <emphasis> 4711True</emphasis> 4712 if an indicator with the specified name was found on the device. 4713</para> 4714 4715 4716<para> 4717If no indicator with the specified name is found on the specified device, and 4718the <emphasis> 4719createMap</emphasis> 4720 field is <emphasis> 4721True</emphasis> 4722, XKB assigns the specified name to the lowest-numbered indicator that has no 4723name (i.e. whose name is <emphasis> 4724None</emphasis> 4725) and applies the rest of the fields in the request to the newly named 4726indicator. If no unnamed indicators remain, this request reports no error and 4727has no effect. 4728</para> 4729 4730 4731<para> 4732If no matching indicator is found or new indicator assigned this request 4733reports no error and has no effect. Otherwise, it updates the indicator as 4734follows: 4735</para> 4736 4737 4738<para> 4739If <emphasis> 4740setMap </emphasis> 4741is <emphasis> 4742True</emphasis> 4743, XKB changes the map for the indicator (see <link linkend='Indicator_Maps'>Indicator Maps</link>) to reflect the 4744values specified in <emphasis> 4745map</emphasis> 4746. 4747</para> 4748 4749 4750<para> 4751If <emphasis> 4752setState</emphasis> 4753 is <emphasis> 4754True</emphasis> 4755, XKB attempts to explicitly change the state of the indicator to the state 4756specified in <emphasis> 4757on</emphasis> 4758. The effects of an attempt to explicitly change the state of an indicator 4759depend on the values in the map for that indicator and are not guaranteed to 4760succeed. 4761</para> 4762 4763 4764<para> 4765If this request affects both indicator map and state, it updates the indicator 4766map before attempting to change its state, so the success of the explicit 4767change depends on the indicator map values specified in the request. 4768</para> 4769 4770 4771<para> 4772If this request changes the indicator map, it applies the new map immediately 4773to determine the appropriate state for the indicator given the new indicator 4774map and the current state of the keyboard. 4775</para> 4776 4777 4778</sect2> 4779<sect2 id='Querying_and_Changing_Symbolic_Names'> 4780<title>Querying and Changing Symbolic Names</title> 4781 4782 4783<informaltable frame='none' tabstyle='proto'> 4784<?dbfo keep-together="always" ?> 4785<tgroup cols='1' align='left' colsep='0' rowsep='0'> 4786<colspec colname='c1' colwidth='1.0*'/> 4787 <thead> 4788 <row> 4789 <entry role='protoname'>XkbGetNames</entry> 4790 </row> 4791 </thead> 4792 <tbody> 4793 <row> 4794 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 4795 </row> 4796 <row> 4797 <entry role='protoname'> 4798which: KB_NAMEDETAILMASK</entry> 4799 </row> 4800 <row> 4801 <entry role='protoreply'> 4802deviceID: CARD8 4803which: KB_NAMESMASK 4804minKeyCode, maxKeyCode: KEYCODE 4805nTypes: CARD8 4806nKTLevels: CARD16 4807groupNames: KB_GROUPMASK 4808virtualMods: KB_VMODMASK 4809firstKey: KEYCODE 4810nKeys: CARD8 4811indicators: KB_INDICATORMASK 4812nRadioGroups, nKeyAliases: CARD8 4813present: KB_NAMEDETAILMASK 4814valueList: LISTofITEMs</entry> 4815 </row> 4816 4817 <row> 4818 <entry role='protoerror'>Errors: <emphasis> 4819Keyboard</emphasis> 4820, <emphasis> 4821Value</emphasis> 4822</entry> 4823 </row> 4824 4825 </tbody> 4826 </tgroup> 4827</informaltable> 4828 4829<para> 4830This request returns the symbolic names for various components of the keyboard 4831mapping for the device specified by <emphasis> 4832deviceSpec</emphasis> 4833. The <emphasis> 4834which</emphasis> 4835 field specifies the keyboard components for which names are to be returned. If 4836<emphasis> 4837deviceSpec</emphasis> 4838 does not specify a valid keyboard device, a <emphasis> 4839Keyboard</emphasis> 4840 error results. If any undefined bits in <emphasis> 4841which</emphasis> 4842 are non-zero, a <emphasis> 4843Value</emphasis> 4844 error results. 4845</para> 4846 4847 4848<para> 4849The <emphasis> 4850deviceID</emphasis> 4851 return value contains the X Input Extension device identifier of the specified 4852device or <emphasis> 48530</emphasis> 4854 if the server does not support the input extension. The <emphasis> 4855present</emphasis> 4856 and <emphasis> 4857valueList</emphasis> 4858 return values specify the components for which names are being reported. If a 4859component is specified in <emphasis> 4860present</emphasis> 4861, the corresponding element is present in the <emphasis> 4862valueList</emphasis> 4863, otherwise that component has length <emphasis> 48640</emphasis> 4865. The components of the <emphasis> 4866valueList</emphasis> 4867 appear in the following order, when present:. 4868</para> 4869 4870<informaltable frame='none'> 4871<?dbfo keep-together="always" ?> 4872<tgroup cols='3' align='left' colsep='0' rowsep='0'> 4873<colspec colname='c1' colwidth='1.0*'/> 4874<colspec colname='c2' colwidth='1.0*'/> 4875<colspec colname='c3' colwidth='1.0*'/> 4876<thead> 4877 <row rowsep='1'> 4878 <entry>Component</entry> 4879 <entry>Size</entry> 4880 <entry>Type</entry> 4881 </row> 4882</thead> 4883<tbody> 4884 <row> 4885 <entry><emphasis> 4886XkbKeycodesName</emphasis> 4887</entry> 4888 <entry>1</entry> 4889 <entry> ATOM</entry> 4890 </row> 4891 <row> 4892 <entry><emphasis> 4893XkbGeometryName</emphasis> 4894</entry> 4895 <entry>1</entry> 4896 <entry> ATOM</entry> 4897 </row> 4898 <row> 4899 <entry><emphasis> 4900XkbSymbolsName</emphasis> 4901</entry> 4902 <entry>1</entry> 4903 <entry> ATOM</entry> 4904 </row> 4905 <row> 4906 <entry><emphasis> 4907XkbPhysSymbolsName</emphasis> 4908</entry> 4909 <entry>1</entry> 4910 <entry> ATOM</entry> 4911 </row> 4912 <row> 4913 <entry><emphasis> 4914XkbTypesName</emphasis> 4915</entry> 4916 <entry>1</entry> 4917 <entry> ATOM</entry> 4918 </row> 4919 <row> 4920 <entry><emphasis> 4921XkbCompatName</emphasis> 4922</entry> 4923 <entry>1</entry> 4924 <entry> ATOM</entry> 4925 </row> 4926 <row> 4927 <entry><emphasis> 4928XkbKeyTypeNames</emphasis> 4929 </entry> 4930 <entry><emphasis> 4931nTypes</emphasis> 4932</entry> 4933 <entry> LISTofATOM</entry> 4934 </row> 4935 <row> 4936 <entry><emphasis> 4937XkbKTLevelNames</emphasis> 4938 </entry> 4939 <entry><emphasis> 4940nTypes</emphasis> 4941, 4942<emphasis> 4943nKTLevels</emphasis> 4944</entry> 4945 <entry>{ count: LISTofCARD8, 4946 names: LISTofATOM }</entry> 4947 </row> 4948 <row> 4949 <entry><emphasis> 4950XkbIndicatorNames</emphasis> 4951 </entry> 4952 <entry>One per bit set in <emphasis> 4953indicators</emphasis> 4954</entry> 4955 <entry> LISTofATOM</entry> 4956 </row> 4957 <row> 4958 <entry><emphasis> 4959XkbVirtualModNames</emphasis> 4960 </entry> 4961 <entry>One per bit set in <emphasis> 4962virtualMods</emphasis> 4963</entry> 4964 <entry> LISTofATOM</entry> 4965 </row> 4966 <row> 4967 <entry><emphasis> 4968XkbGroupNames </emphasis> 4969</entry> 4970 <entry>One per bit set in <emphasis> 4971groupNames</emphasis> 4972</entry> 4973 <entry> LISTofATOM</entry> 4974 </row> 4975 <row> 4976 <entry><emphasis> 4977XkbKeyNames</emphasis> 4978</entry> 4979 <entry><emphasis> 4980nKeys</emphasis> 4981</entry> 4982 <entry> LISTofKB_KEYNAME</entry> 4983 </row> 4984 <row> 4985 <entry><emphasis> 4986XkbKeyAliases</emphasis> 4987</entry> 4988 <entry><emphasis> 4989nKeyAliases</emphasis> 4990</entry> 4991 <entry> LISTofKB_KEYALIAS</entry> 4992 </row> 4993 <row> 4994 <entry><emphasis> 4995XkbRGNames</emphasis> 4996</entry> 4997 <entry><emphasis> 4998nRadioGroups</emphasis> 4999</entry> 5000 <entry> LISTofATOM</entry> 5001 </row> 5002</tbody> 5003</tgroup> 5004</informaltable> 5005 5006<para> 5007If type names are reported, the <emphasis> 5008nTypes</emphasis> 5009 return value reports the number of types defined for the keyboard, and the 5010list of key type names in <emphasis> 5011valueList</emphasis> 5012 has <emphasis> 5013nTypes</emphasis> 5014 elements. 5015</para> 5016 5017 5018<para> 5019If key type level names are reported, the list of key type level names in the 5020<emphasis> 5021valueList</emphasis> 5022 has two parts: The <emphasis> 5023count</emphasis> 5024 array has <emphasis> 5025nTypes</emphasis> 5026 elements, each of which reports the number of level names reported for the 5027corresponding key type. The <emphasis> 5028names</emphasis> 5029 array has <emphasis> 5030nKTLevels</emphasis> 5031 atoms and reports the names of each type sequentially. The <emphasis> 5032nKTLevels</emphasis> 5033 return value is always equal to the sum of all of the elements of the 5034<emphasis> 5035count</emphasis> 5036 array. 5037</para> 5038 5039 5040<para> 5041If indicator names are reported, the <emphasis> 5042indicators</emphasis> 5043 mask specifies the indicators for which names are defined; any indicators not 5044specified in <emphasis> 5045indicators</emphasis> 5046 have the name <emphasis> 5047None</emphasis> 5048. The list of indicator names in <emphasis> 5049valueList</emphasis> 5050 contains the names of the listed indicators, beginning with the 5051lowest-numbered indicator for which a name is defined and proceeding to the 5052highest. 5053</para> 5054 5055 5056<para> 5057If virtual modifier names are reported, the <emphasis> 5058virtualMods</emphasis> 5059 mask specifies the virtual modifiers for which names are defined; any virtual 5060modifiers not specified in <emphasis> 5061virtualMods</emphasis> 5062 have the name <emphasis> 5063None</emphasis> 5064. The list of virtual modifier names in <emphasis> 5065valueList</emphasis> 5066 contains the names of the listed virtual modifiers, beginning with the 5067lowest-numbered virtual modifier for which a name is defined and proceeding to 5068the highest. 5069</para> 5070 5071 5072<para> 5073If group names are reported, the <emphasis> 5074groupNames</emphasis> 5075 mask specifies the groups for which names are defined; any groups not 5076specified in <emphasis> 5077groupNames</emphasis> 5078 have the name <emphasis> 5079None</emphasis> 5080. The list of group names in <emphasis> 5081valueList</emphasis> 5082 contains the names of the listed groups, beginning with the lowest-numbered 5083group for which a name is defined and proceeding to the highest. 5084</para> 5085 5086 5087<para> 5088If key names are reported, the <emphasis> 5089firstKey</emphasis> 5090 and <emphasis> 5091nKeys</emphasis> 5092 return values specify a range of keys which includes all keys for which names 5093are defined; any key that does not fall in the range specified by <emphasis> 5094firstKey</emphasis> 5095 and <emphasis> 5096nKeys</emphasis> 5097 has the name <emphasis> 5098NullKeyName</emphasis> 5099. The list of key names in the <emphasis> 5100valueList</emphasis> 5101 has <emphasis> 5102nKeys</emphasis> 5103 entries and specifies the names of the keys beginning at <emphasis> 5104firstKey</emphasis> 5105. 5106</para> 5107 5108 5109<para> 5110If key aliases are reported, the <emphasis> 5111nKeyAliases</emphasis> 5112 return value specifies the total number of key aliases defined for the 5113keyboard. The list of key aliases in <emphasis> 5114valueList</emphasis> 5115 has <emphasis> 5116nKeyAliases</emphasis> 5117 entries, each of which reports an alias and the real name of the key to which 5118it corresponds. 5119</para> 5120 5121 5122<para> 5123If radio group names are reported, the <emphasis> 5124nRadioGroups</emphasis> 5125 return value specifies the number of radio groups on the keyboard for which 5126names are defined. The list of radio group names in <emphasis> 5127valueList</emphasis> 5128 reports the names of each group and has <emphasis> 5129nRadioGroups</emphasis> 5130 entries. 5131</para> 5132 5133 5134 5135<informaltable frame='none' tabstyle='proto'> 5136<?dbfo keep-together="always" ?> 5137<tgroup cols='1' align='left' colsep='0' rowsep='0'> 5138<colspec colname='c1' colwidth='1.0*'/> 5139 <thead> 5140 <row> 5141 <entry role='protoname'>XkbSetNames</entry> 5142 </row> 5143 </thead> 5144 <tbody> 5145 <row> 5146 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 5147 </row> 5148 <row> 5149 <entry role='protoargs'>which: KB_NAMEDETAILMASK</entry> 5150 </row> 5151 <row> 5152 <entry role='protoname'> 5153virtualMods: KB_VMODMASK</entry> 5154 </row> 5155 <row> 5156 <entry role='protoname'> 5157firstType, nTypes: CARD8</entry> 5158 </row> 5159 <row> 5160 <entry role='protoname'> 5161firstKTLevel, nKTLevels: CARD8</entry> 5162 </row> 5163 <row> 5164 <entry role='protoname'> 5165totalKTLevelNames: CARD16</entry> 5166 </row> 5167 <row> 5168 <entry role='protoname'> 5169indicators: KB_INDICATORMASK</entry> 5170 </row> 5171 <row> 5172 <entry role='protoname'> 5173groupNames: KB_GROUPMASK</entry> 5174 </row> 5175 <row> 5176 <entry role='protoname'> 5177nRadioGroups: CARD8</entry> 5178 </row> 5179 <row> 5180 <entry role='protoname'> 5181firstKey: KEYCODE</entry> 5182 </row> 5183 <row> 5184 <entry role='protoname'> 5185nKeys, nKeyAliases: CARD8</entry> 5186 </row> 5187 <row> 5188 <entry role='protoname'> 5189valueList: LISTofITEMs</entry> 5190 </row> 5191 5192 <row> 5193 <entry role='protoerror'>Errors: <emphasis> 5194Keyboard</emphasis> 5195, <emphasis> 5196Atom</emphasis> 5197, <emphasis> 5198Value</emphasis> 5199, <emphasis> 5200Match</emphasis> 5201, <emphasis> 5202Alloc</emphasis> 5203</entry> 5204 </row> 5205 5206 </tbody> 5207 </tgroup> 5208</informaltable> 5209 5210<para> 5211This request changes the symbolic names for the requested components of the 5212keyboard specified by <emphasis> 5213deviceSpec</emphasis> 5214. The <emphasis> 5215which</emphasis> 5216 field specifies the components for which one or more names are to be updated. 5217If <emphasis> 5218deviceSpec</emphasis> 5219 does not specify a valid keyboard device, a <emphasis> 5220Keyboard</emphasis> 5221 error results. If any undefined bits in <emphasis> 5222which</emphasis> 5223 are non-zero, a <emphasis> 5224Value</emphasis> 5225 error results. If any error (other than <emphasis> 5226Alloc</emphasis> 5227 or <emphasis> 5228Implementation</emphasis> 5229) occurs, this request returns without modifying any names. 5230</para> 5231 5232 5233<para> 5234The <emphasis> 5235which</emphasis> 5236 and <emphasis> 5237valueList</emphasis> 5238 fields specify the components to be changed; the type of each <emphasis> 5239valueList</emphasis> 5240 entry, the order in which components appear in the <emphasis> 5241valueList</emphasis> 5242 when specified, and the correspondence between components in <emphasis> 5243which</emphasis> 5244 and the entries in the <emphasis> 5245valueList</emphasis> 5246 are as specified for the <emphasis> 5247XkbGetNames</emphasis> 5248 request. 5249</para> 5250 5251 5252<para> 5253If keycodes, geometry, symbols, physical symbols, types or compatibility map 5254names are to be changed, the corresponding entries in the <emphasis> 5255valueList</emphasis> 5256 must have the value <emphasis> 5257None</emphasis> 5258 or specify a valid ATOM, else an <emphasis> 5259Atom</emphasis> 5260 error occurs. 5261</para> 5262 5263 5264<para> 5265If key type names are to be changed, the <emphasis> 5266firstType</emphasis> 5267 and <emphasis> 5268nTypes</emphasis> 5269 fields specify a range of types for which new names are supplied, and the list 5270of key type names in <emphasis> 5271valueList</emphasis> 5272 has <emphasis> 5273nTypes</emphasis> 5274 elements. Names for types that fall outside of the range specified by 5275<emphasis> 5276firstType</emphasis> 5277 and <emphasis> 5278nTypes</emphasis> 5279 are not affected. If this request specifies names for types that are not 5280present on the keyboard, a <emphasis> 5281Match</emphasis> 5282 error results. All of the type names in the <emphasis> 5283valueList</emphasis> 5284 must be valid ATOMs or have the value <emphasis> 5285None</emphasis> 5286, or an <emphasis> 5287Atom</emphasis> 5288 error results. 5289</para> 5290 5291 5292<para> 5293The names of the first four keyboard types are specified by the XKB extension 5294and cannot be changed; including any of the canonical types in this request 5295causes an <emphasis> 5296Access</emphasis> 5297 error, as does trying to assign the name reserved for a canonical type to one 5298of the other key types. 5299</para> 5300 5301 5302<para> 5303If key type level names are to be changed, the <emphasis> 5304firstKTLevel</emphasis> 5305 and <emphasis> 5306nKTLevels</emphasis> 5307 fields specify a range of key types for which new level names are supplied, 5308and the list of key type level names in the <emphasis> 5309valueList</emphasis> 5310 has two parts: The <emphasis> 5311count</emphasis> 5312 array has <emphasis> 5313nKTLevels</emphasis> 5314 elements, each of which specifies the number of levels for which names are 5315supplied on the corresponding key type; any levels for which no names are 5316specified are assigned the name <emphasis> 5317None</emphasis> 5318. The <emphasis> 5319names</emphasis> 5320 array has <emphasis> 5321totalKTLevels</emphasis> 5322 atoms and specifies the names of each type sequentially. The <emphasis> 5323totalKTLevels</emphasis> 5324 field must always equal the sum of all of the elements of the <emphasis> 5325count</emphasis> 5326 array. Level names for types that fall outside of the specified range are not 5327affected. If this request specifies level names for types that are not present 5328on the keyboard, or if it specifies more names for a type than the type has 5329levels, a <emphasis> 5330Match</emphasis> 5331 error results. All specified type level names must be <emphasis> 5332None</emphasis> 5333 or a valid ATOM or an <emphasis> 5334Atom</emphasis> 5335 error results. 5336</para> 5337 5338 5339<para> 5340If indicator names are to be changed, the <emphasis> 5341indicators</emphasis> 5342 mask specifies the indicators for which new names are specified; the names for 5343indicators not specified in <emphasis> 5344indicators</emphasis> 5345 are not affected. The list of indicator names in <emphasis> 5346valueList</emphasis> 5347 contains the new names for the listed indicators, beginning with the 5348lowest-numbered indicator for which a name is defined and proceeding to the 5349highest. All specified indicator names must be a valid ATOM or <emphasis> 5350None</emphasis> 5351, or an <emphasis> 5352Atom</emphasis> 5353 error results. 5354</para> 5355 5356 5357<para> 5358If virtual modifier names are to be changed, the <emphasis> 5359virtualMods</emphasis> 5360 mask specifies the virtual modifiers for which new names are specified; names 5361for any virtual modifiers not specified in <emphasis> 5362virtualMods</emphasis> 5363 are not affected. The list of virtual modifier names in <emphasis> 5364valueList</emphasis> 5365 contains the new names for the specified virtual modifiers, beginning with the 5366lowest-numbered virtual modifier for which a name is defined and proceeding to 5367the highest. All virtual modifier names must be valid ATOMs or <emphasis> 5368None</emphasis> 5369, or an <emphasis> 5370Atom</emphasis> 5371 error results. 5372</para> 5373 5374 5375<para> 5376If group names are to be changed, the <emphasis> 5377groupNames</emphasis> 5378 mask specifies the groups for which new names are specified; the name of any 5379group not specified in <emphasis> 5380groupNames</emphasis> 5381 is not changed. The list of group names in <emphasis> 5382valueList</emphasis> 5383 contains the new names for the listed groups, beginning with the 5384lowest-numbered group for which a name is defined and proceeding to the 5385highest. All specified group names must be a valid ATOM or <emphasis> 5386None</emphasis> 5387, or an <emphasis> 5388Atom</emphasis> 5389 error results. 5390</para> 5391 5392 5393<para> 5394If key names are to be changed, the <emphasis> 5395firstKey</emphasis> 5396 and <emphasis> 5397nKeys</emphasis> 5398 fields specify a range of keys for which new names are defined; the name of 5399any key that does not fall in the range specified by <emphasis> 5400firstKey</emphasis> 5401 and <emphasis> 5402nKeys</emphasis> 5403 is not changed. The list of key names in the <emphasis> 5404valueList</emphasis> 5405 has <emphasis> 5406nKeys</emphasis> 5407 entries and specifies the names of the keys beginning at <emphasis> 5408firstKey</emphasis> 5409. 5410</para> 5411 5412 5413<para> 5414If key aliases are to be changed, the <emphasis> 5415nKeyAliases</emphasis> 5416 field specifies the length of a new list of key aliases for the keyboard. The 5417list of key aliases can only be replaced in its entirety; it cannot be 5418replaced. The list of key aliases in <emphasis> 5419valueList</emphasis> 5420 has <emphasis> 5421nKeyAliases</emphasis> 5422 entries, each of which reports an alias and the real name of the key to which 5423it corresponds. 5424</para> 5425 5426 5427<para> 5428XKB does not check key names or aliases for consistency and validity, so 5429applications should take care not to assign duplicate names or aliases 5430</para> 5431 5432 5433<para> 5434If radio group names are to be changed, the <emphasis> 5435nRadioGroups</emphasis> 5436 field specifies the length of a new list of radio group names for the 5437keyboard. There is no way to edit the list of radio group names; it can only be 5438replaced in its entirety. The list of radio group names in <emphasis> 5439valueList</emphasis> 5440 reports the names of each group and has <emphasis> 5441nRadioGroups</emphasis> 5442 entries. If the list of radio group names specifies names for more radio 5443groups than XKB allows (32), a <emphasis> 5444Match</emphasis> 5445 error results. All specified radio group names must be valid ATOMs or have the 5446value <emphasis> 5447None</emphasis> 5448, or an <emphasis> 5449Atom</emphasis> 5450 error results. 5451</para> 5452 5453 5454</sect2> 5455<sect2 id='Querying_and_Changing_Keyboard_Geometry'> 5456<title>Querying and Changing Keyboard Geometry</title> 5457 5458 5459<informaltable frame='none' tabstyle='proto'> 5460<?dbfo keep-together="always" ?> 5461<tgroup cols='1' align='left' colsep='0' rowsep='0'> 5462<colspec colname='c1' colwidth='1.0*'/> 5463 <thead> 5464 <row> 5465 <entry role='protoname'>XkbGetGeometry</entry> 5466 </row> 5467 </thead> 5468 <tbody> 5469 <row> 5470 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC 5471 </entry> 5472 </row> 5473 <row> 5474 <entry role='protoname'> 5475name: ATOM</entry> 5476 </row> 5477 <row> 5478 <entry role='protoreply'> 5479deviceID: CARD8 5480 </entry> 5481 </row> 5482 <row> 5483 <entry role='protoname'> 5484name: ATOM 5485 </entry> 5486 </row> 5487 <row> 5488 <entry role='protoname'> 5489found: BOOL 5490 </entry> 5491 </row> 5492 <row> 5493 <entry role='protoname'> 5494widthMM, heightMM: CARD16 5495 </entry> 5496 </row> 5497 <row> 5498 <entry role='protoname'> 5499baseColorNdx, labelColorNdx: CARD8 5500 </entry> 5501 </row> 5502 <row> 5503 <entry role='protoname'> 5504properties: LISTofKB_PROPERTY 5505 </entry> 5506 </row> 5507 <row> 5508 <entry role='protoname'> 5509colors: LISTofSTRING8 5510 </entry> 5511 </row> 5512 <row> 5513 <entry role='protoname'> 5514shapes: LISTofKB_SHAPE 5515 </entry> 5516 </row> 5517 <row> 5518 <entry role='protoname'> 5519sections: LISTofKB_SECTION 5520 </entry> 5521 </row> 5522 <row> 5523 <entry role='protoname'> 5524doodads: LISTofKB_DOODAD 5525 </entry> 5526 </row> 5527 <row> 5528 <entry role='protoname'> 5529keyAliases: LISTofKB_KEYALIAS</entry> 5530 </row> 5531 <row> 5532 <entry role='protoerror'>Errors: <emphasis> 5533Keyboard</emphasis> 5534</entry> 5535 </row> 5536 </tbody> 5537 </tgroup> 5538</informaltable> 5539 5540<para> 5541This request returns a description of the physical layout of a keyboard. If the 5542<emphasis> 5543name</emphasis> 5544 field has the value <emphasis> 5545None</emphasis> 5546, or if name is identical to the name of the geometry for the keyboard 5547specified by <emphasis> 5548deviceSpec</emphasis> 5549, this request returns the geometry of the keyboard specified by <emphasis> 5550deviceSpec</emphasis> 5551; otherwise, if <emphasis> 5552name</emphasis> 5553 is a valid atom other than <emphasis> 5554None</emphasis> 5555, the server returns the keyboard geometry description with that name in the 5556server database of keyboard components (see <link linkend='The_Server_Database_of_Keyboard_Components'>The Server Database of Keyboard 5557Components</link>) if one exists. If <emphasis> 5558deviceSpec</emphasis> 5559 does not specify a valid keyboard device, a <emphasis> 5560Keyboard</emphasis> 5561 error results. If <emphasis> 5562name</emphasis> 5563 has a value other than <emphasis> 5564None</emphasis> 5565 or a valid ATOM, an <emphasis> 5566Atom</emphasis> 5567 error results. 5568</para> 5569 5570 5571<para> 5572On successful return, the <emphasis> 5573deviceID</emphasis> 5574 field reports the X Input extension identifier of the keyboard device 5575specified in the request, or <emphasis> 55760</emphasis> 5577 if the server does not support the input extension. 5578</para> 5579 5580 5581<para> 5582The <emphasis> 5583found</emphasis> 5584 return value reports whether the requested geometry was available. If 5585<emphasis> 5586found</emphasis> 5587 is <emphasis> 5588False</emphasis> 5589, no matching geometry was found and the remaining fields in the request reply 5590are undefined; if <emphasis> 5591found</emphasis> 5592 is <emphasis> 5593True</emphasis> 5594, the remaining fields of the reply describe the requested keyboard geometry. 5595The interpretation of the components that make up a keyboard geometry is 5596described in detail in <link linkend='Keyboard_Geometry'>Keyboard 5597Geometry</link> 5598</para> 5599 5600 5601 5602<informaltable frame='none' tabstyle='proto'> 5603<?dbfo keep-together="always" ?> 5604<tgroup cols='1' align='left' colsep='0' rowsep='0'> 5605<colspec colname='c1' colwidth='1.0*'/> 5606 <thead> 5607 <row> 5608 <entry role='protoname'>XkbSetGeometry</entry> 5609 </row> 5610 </thead> 5611 <tbody> 5612 <row> 5613 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 5614 </row> 5615 <row> 5616 <entry role='protoname'> 5617name: ATOM</entry> 5618 </row> 5619 <row> 5620 <entry role='protoname'> 5621widthMM, heightMM, CARD16</entry> 5622 </row> 5623 <row> 5624 <entry role='protoname'> 5625baseColorNdx, labelColorNdx: CARD8</entry> 5626 </row> 5627 <row> 5628 <entry role='protoname'> 5629shapes: LISTofKB_SHAPE</entry> 5630 </row> 5631 <row> 5632 <entry role='protoname'> 5633sections: LISTofKB_SECTION</entry> 5634 </row> 5635 <row> 5636 <entry role='protoname'> 5637properties: LISTofKB_PROPERTY</entry> 5638 </row> 5639 <row> 5640 <entry role='protoname'> 5641colors: LISTofSTRING8</entry> 5642 </row> 5643 <row> 5644 <entry role='protoname'> 5645doodads: LISTofKB_DOODAD</entry> 5646 </row> 5647 <row> 5648 <entry role='protoname'> 5649keyAliases: LISTofKB_KEYALIAS</entry> 5650 </row> 5651 5652 <row> 5653 <entry role='protoerror'>Errors: <emphasis> 5654Keyboard</emphasis> 5655, <emphasis> 5656Atom</emphasis> 5657, <emphasis> 5658Value</emphasis> 5659</entry> 5660 </row> 5661 5662 </tbody> 5663 </tgroup> 5664</informaltable> 5665 5666<para> 5667This request changes the reported description of the geometry for the keyboard 5668specified by <emphasis> 5669deviceSpec</emphasis> 5670. If deviceSpec does not specify a valid keyboard device, a <emphasis> 5671Keyboard</emphasis> 5672 error results. 5673</para> 5674 5675 5676<para> 5677The <emphasis> 5678name</emphasis> 5679 field specifies the name of the new keyboard geometry and must be a valid ATOM 5680or an <emphasis> 5681Atom</emphasis> 5682 error results. The new geometry is not added to the server database of 5683keyboard components, but it can be retrieved using the <emphasis> 5684XkbGetGeometry</emphasis> 5685 request for as long as it is bound to the keyboard. The keyboard geometry 5686symbolic name is also updated from the name field, and an <emphasis> 5687XkbNamesNotify</emphasis> 5688 event is generated, if necessary. 5689</para> 5690 5691 5692<para> 5693The list of <emphasis> 5694colors</emphasis> 5695 must include at least two definitions, or a <emphasis> 5696Value</emphasis> 5697 error results. All color definitions in the geometry must specify a legal 5698color (i.e. must specify a valid index for one of the entries of the <emphasis> 5699colors</emphasis> 5700 list) or a <emphasis> 5701Match</emphasis> 5702 error results. The <emphasis> 5703baseColorNdx</emphasis> 5704 and the <emphasis> 5705labelColorNdx</emphasis> 5706 must be different or a <emphasis> 5707Match</emphasis> 5708 error results. 5709</para> 5710 5711 5712<para> 5713The list of <emphasis> 5714shapes</emphasis> 5715 must include at least one shape definition, or a <emphasis> 5716Value</emphasis> 5717 error results. If any two shapes have the same name, a <emphasis> 5718Match</emphasis> 5719 error result. All doodads and keys which specify shape must specify a valid 5720index for one of the elements of the <emphasis> 5721shapes</emphasis> 5722 list, or a <emphasis> 5723Match</emphasis> 5724 error results. 5725</para> 5726 5727 5728<para> 5729All section, shape and doodad names must be valid ATOMs or an <emphasis> 5730Atom</emphasis> 5731 error results; the constant <emphasis> 5732None</emphasis> 5733 is not permitted for any of these components. 5734</para> 5735 5736 5737<para> 5738All doodads must be of a known type; XKB does not support "private" doodad 5739types. 5740</para> 5741 5742 5743<para> 5744If, after rotation, any keys or doodads fall outside of the bounding box for a 5745section, the bounding box is automatically adjusted to the minimum size which 5746encloses all of its components. 5747</para> 5748 5749 5750<para> 5751If, after adjustment and rotation, the bounding box of any section or doodad 5752extends below zero on either the X or Y axes, the entire geometry is translated 5753so that the minimum extent along either axis is zero. 5754</para> 5755 5756 5757<para> 5758If, after rotation and translation, any keyboard components fall outside of the 5759rectangle specified by <emphasis> 5760widthMM</emphasis> 5761 and <emphasis> 5762heightMM</emphasis> 5763, the keyboard dimensions are automatically resized to the minimum bounding box 5764that surrounds all components. Otherwise, the width and height of the keyboard 5765are left as specified. 5766</para> 5767 5768 5769<para> 5770The <emphasis> 5771under</emphasis> 5772 field of any overlay key definitions must specify a key that is in the section 5773that contains the overlay key, or a <emphasis> 5774Match</emphasis> 5775 error results. This request does not check the value of the <emphasis> 5776over</emphasis> 5777 field of an overlay key definition, so applications must be careful to avoid 5778conflicts with actual keys. 5779</para> 5780 5781 5782<para> 5783This request does not verify that key names or aliases are unique. It also does 5784not verify that all key names specified in the geometry are bound to some 5785keycode or that all keys that are named in the keyboard definition are also 5786available in the geometry. Applications should make sure that keyboard geometry 5787has no internal conflicts and is consistent with the other components of the 5788keyboard definition, but XKB does not check for or guarantee it. 5789</para> 5790 5791 5792</sect2> 5793<sect2 id='Querying_and_Changing_Per_Client_Flags'> 5794<title>Querying and Changing Per-Client Flags</title> 5795 5796 5797<informaltable frame='none' tabstyle='proto'> 5798<?dbfo keep-together="always" ?> 5799<tgroup cols='1' align='left' colsep='0' rowsep='0'> 5800<colspec colname='c1' colwidth='1.0*'/> 5801 <thead> 5802 <row> 5803 <entry role='protoname'>XkbPerClientFlags</entry> 5804 </row> 5805 </thead> 5806 <tbody> 5807 <row> 5808 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 5809 </row> 5810 <row> 5811 <entry role='protoname'> 5812change: KB_PCFMASK</entry> 5813 </row> 5814 <row> 5815 <entry role='protoname'> 5816value: KB_PCFMASK</entry> 5817 </row> 5818 <row> 5819 <entry role='protoname'> 5820ctrlsToChange: KB_BOOLCTRLMASK</entry> 5821 </row> 5822 <row> 5823 <entry role='protoname'> 5824autoCtrls: KB_BOOLCTRLMASK</entry> 5825 </row> 5826 <row> 5827 <entry role='protoname'> 5828autoCtrlValues: KB_BOOLCTRLMASK</entry> 5829 </row> 5830 <row> 5831 <entry role='protoreply'> 5832deviceID: CARD8 5833supported: KB_PCFMASK 5834value: KB_PCFMASK 5835autoCtrls: KB_BOOLCTRLMASK 5836autoCtrlValues: KB_BOOLCTRLMASK 5837where: KB_PCFMASK:</entry> 5838 </row> 5839 5840 <row> 5841 <entry role='protoerror'>Errors: <emphasis> 5842Keyboard</emphasis> 5843, <emphasis> 5844Value</emphasis> 5845, <emphasis> 5846Match</emphasis> 5847, <emphasis> 5848Alloc</emphasis> 5849</entry> 5850 </row> 5851 5852 </tbody> 5853 </tgroup> 5854</informaltable> 5855 5856<para> 5857Changes the client specific flags for the keyboard specified by <emphasis> 5858deviceSpec</emphasis> 5859. Reports a <emphasis> 5860Keyboard</emphasis> 5861 error if <emphasis> 5862deviceSpec</emphasis> 5863 does not specify a valid keyboard device. 5864</para> 5865 5866 5867<para> 5868Any flags specified in <emphasis> 5869change</emphasis> 5870 are set to the corresponding values in <emphasis> 5871value</emphasis> 5872, provided that the server supports the requested control. Legal 5873per-client-flags are: 5874</para> 5875 5876<informaltable frame='topbot'> 5877<?dbfo keep-together="always" ?> 5878<tgroup cols='2' align='left' colsep='0' rowsep='0'> 5879<colspec colname='c1' colwidth='1.0*'/> 5880<colspec colname='c2' colwidth='1.0*'/> 5881<thead> 5882 <row rowsep='1'> 5883 <entry>Flag…</entry> 5884 <entry>Described in…</entry> 5885 </row> 5886</thead> 5887<tbody> 5888 <row> 5889 <entry><emphasis> 5890XkbPCF_DetectableAutorepeat</emphasis> 5891</entry> 5892 <entry><link linkend='Detectable_Autorepeat'>Detectable 5893Autorepeat</link></entry> 5894 </row> 5895 <row> 5896 <entry><emphasis> 5897XkbPCF_GrabsUseXKBStateMask</emphasis> 5898</entry> 5899 <entry><link linkend='Setting_a_Passive_Grab_for_an_XKB_State'>Setting a Passive Grab 5900for an XKB State</link></entry> 5901 </row> 5902 <row> 5903 <entry><emphasis> 5904XkbPCF_AutoResetControlsMask</emphasis> 5905</entry> 5906 <entry><link linkend='Automatic_Reset_of_Boolean_Controls'>Automatic Reset of 5907Boolean Controls</link></entry> 5908 </row> 5909 <row> 5910 <entry><emphasis> 5911XkbPCF_LookupStateWhenGrabbed</emphasis> 5912</entry> 5913 <entry><link linkend='Effects_of_XKB_on_Core_Protocol_Events'>Effects of XKB on Core 5914Protocol Events</link></entry> 5915 </row> 5916 <row> 5917 <entry><emphasis> 5918XkbPCF_SendEventUsesXKBState</emphasis> 5919</entry> 5920 <entry><link linkend='Sending_Events_to_Clients'>Sending Events to 5921Clients</link></entry> 5922 </row> 5923</tbody> 5924</tgroup> 5925</informaltable> 5926 5927<para> 5928If <emphasis> 5929PCF_AutoResetControls</emphasis> 5930 is set in both <emphasis> 5931change</emphasis> 5932 and <emphasis> 5933value</emphasis> 5934, the client’s mask of controls to be changed is updated from <emphasis> 5935ctrlsToChange</emphasis> 5936, <emphasis> 5937autoCtrls</emphasis> 5938, and <emphasis> 5939autoCtrlValues</emphasis> 5940. Any controls specified in <emphasis> 5941ctrlsToChange</emphasis> 5942 are modified in the auto-reset controls mask for the client; the corresponding 5943bits from the <emphasis> 5944autoCtrls</emphasis> 5945 field are copied into the auto-reset controls mask and the corresponding bits 5946from <emphasis> 5947autoCtrlValues</emphasis> 5948 are copied into the auto-reset controls state values. If any controls are 5949specified in <emphasis> 5950autoCtrlValues</emphasis> 5951 but not in <emphasis> 5952autoCtrls</emphasis> 5953, a <emphasis> 5954Match</emphasis> 5955 error results. If any controls are specified in <emphasis> 5956autoCtrls</emphasis> 5957 but not in <emphasis> 5958ctrlsToChange</emphasis> 5959, a <emphasis> 5960Match</emphasis> 5961 error results. 5962</para> 5963 5964 5965<para> 5966If <emphasis> 5967PCF_AutoResetControls</emphasis> 5968 is set in <emphasis> 5969change</emphasis> 5970 but not in <emphasis> 5971value</emphasis> 5972, the client’s mask of controls to be changed is reset to all zeroes (i.e. 5973the client does not change any controls when it exits). 5974</para> 5975 5976 5977<para> 5978This request reports a <emphasis> 5979Match</emphasis> 5980 error if a bit is set in any of the value masks but not in the control mask 5981that governs it or a <emphasis> 5982Value</emphasis> 5983 error if any undefined bits are set in any of the masks. 5984</para> 5985 5986 5987<para> 5988On successful return, the <emphasis> 5989deviceID</emphasis> 5990 field reports the X Input extension identifier of the keyboard, or <emphasis> 59910</emphasis> 5992 if the server does not support the X Input Extension. 5993</para> 5994 5995 5996<para> 5997The <emphasis> 5998supported</emphasis> 5999 return value reports the set of per-client flags that are supported by the 6000server; in this version of XKB, only the <emphasis> 6001XkbPCF_DetectableAutorepeat</emphasis> 6002 per-client flag is optional; all other per-client flags must be supported. 6003</para> 6004 6005 6006<para> 6007The <emphasis> 6008value</emphasis> 6009 return value reports the current settings of all per-client flags for the 6010specified keyboard. The <emphasis> 6011autoCtrls</emphasis> 6012 return value reports the current set of controls to be reset when the client 6013exits, while the <emphasis> 6014autoCtrlValues</emphasis> 6015 return value reports the state to which they should be set. 6016</para> 6017 6018 6019</sect2> 6020<sect2 id='Using_the_Servers_Database_of_Keyboard_Components'> 6021<title>Using the Server’s Database of Keyboard Components</title> 6022 6023 6024<informaltable frame='none' tabstyle='proto'> 6025<?dbfo keep-together="always" ?> 6026<tgroup cols='1' align='left' colsep='0' rowsep='0'> 6027<colspec colname='c1' colwidth='1.0*'/> 6028 <thead> 6029 <row> 6030 <entry role='protoname'>XkbListComponents</entry> 6031 </row> 6032 </thead> 6033 <tbody> 6034 <row> 6035 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 6036 </row> 6037 <row> 6038 <entry role='protoname'> 6039maxNames: CARD16</entry> 6040 </row> 6041 <row> 6042 <entry role='protoname'> 6043keymapsSpec: STRING8</entry> 6044 </row> 6045 <row> 6046 <entry role='protoname'> 6047keycodesSpec: STRING8</entry> 6048 </row> 6049 <row> 6050 <entry role='protoname'> 6051typesSpec: STRING8</entry> 6052 </row> 6053 <row> 6054 <entry role='protoname'> 6055compatMapSpec: STRING8</entry> 6056 </row> 6057 <row> 6058 <entry role='protoname'> 6059symbolsSpec: STRING8</entry> 6060 </row> 6061 <row> 6062 <entry role='protoname'> 6063geometrySpec: STRING8 6064 </entry> 6065 </row> 6066 <row> 6067 <entry role='protoreply'> 6068deviceID: CARD8 6069 </entry> 6070 </row> 6071 <row> 6072 <entry role='protoreply'> 6073extra: CARD16 6074 </entry> 6075 </row> 6076 <row> 6077 <entry role='protoreply'> 6078keymaps,keycodes,types,compatMaps: LISTofKB_COMPONENTNAME 6079 </entry> 6080 </row> 6081 <row> 6082 <entry role='protoreply'> 6083symbols, geometries: LISTofKB_COMPONENTNAME</entry> 6084 </row> 6085 <row> 6086 <entry role='protoreply'>Where:</entry> 6087 </row> 6088 <row> 6089 <entry role='protoreply'>KB_COMPONENTNAME { hints: CARD8, name: 6090STRING8 }</entry> 6091 </row> 6092 <row> 6093 <entry role='protoerror'>Errors: <emphasis> 6094Keyboard</emphasis> 6095, <emphasis> 6096Alloc</emphasis> 6097</entry> 6098 </row> 6099 </tbody> 6100 </tgroup> 6101</informaltable> 6102 6103<para> 6104This request returns one or more lists of keyboard components that are 6105available from the X server database of keyboard components for the device 6106specified by <emphasis> 6107deviceSpec</emphasis> 6108. The X server is allowed, but not required or expected, to maintain separate 6109databases for each keyboard device. A <emphasis> 6110Keyboard</emphasis> 6111 error results if <emphasis> 6112deviceSpec</emphasis> 6113 does not specify a valid keyboard device. 6114</para> 6115 6116 6117<para> 6118The <emphasis> 6119maxNames</emphasis> 6120 field specifies the maximum number of component names to be reported, in 6121total, by this request. 6122</para> 6123 6124 6125<para> 6126The <emphasis> 6127keymapsSpec</emphasis> 6128, <emphasis> 6129keycodesSpec</emphasis> 6130, <emphasis> 6131typesSpec</emphasis> 6132, <emphasis> 6133compatMapSpec</emphasis> 6134, <emphasis> 6135symbolsSpec</emphasis> 6136 and <emphasis> 6137geometrySpec</emphasis> 6138 request fields specify a pattern to be matched against the names of all 6139components of the corresponding type in the server database of keyboard 6140components. 6141</para> 6142 6143 6144<para> 6145Each pattern uses the ISO Latin-1 encoding and should contain only parentheses, 6146the wildcard characters "?" and "*" or characters that are permitted in a 6147component class or member name (see <link linkend='Component_Names'>Component Names</link>). Illegal 6148characters in a pattern are simply ignored; no error results if a pattern 6149contains illegal characters. 6150</para> 6151 6152 6153<para> 6154Comparison is case-sensitive and, in a pattern, the "?" wildcard character 6155matches any single character except parentheses while the "*" character matches 6156any number of characters except parentheses. If an implementation accepts 6157characters other than those required by XKB, whether or not those characters 6158match either wildcard is also implementation dependent. An empty pattern does 6159not match any component names. 6160</para> 6161 6162 6163<para> 6164On successful return, the <emphasis> 6165deviceID</emphasis> 6166 return value reports the X Input Extension device identifier of the specified 6167device, or <emphasis> 61680</emphasis> 6169 if the server does not support the X input extension. The <emphasis> 6170extra</emphasis> 6171 return value reports the number of matching component names that could not be 6172returned due to the setting of the <emphasis> 6173maxNames</emphasis> 6174 field in the request. 6175</para> 6176 6177 6178<para> 6179The <emphasis> 6180keymaps</emphasis> 6181, <emphasis> 6182keycodes</emphasis> 6183, <emphasis> 6184types</emphasis> 6185, <emphasis> 6186compatMaps</emphasis> 6187, <emphasis> 6188symbols</emphasis> 6189 and <emphasis> 6190geometries</emphasis> 6191 return the hints (see <link linkend='Component_Hints'>Component 6192Hints</link>) and names of any components from the server database that match 6193the corresponding pattern. 6194</para> 6195 6196 6197<para> 6198<link linkend='The_Server_Database_of_Keyboard_Components'>The Server Database of Keyboard 6199Components</link> describes the X server database of keyboard components in 6200more detail. 6201</para> 6202 6203 6204 6205<informaltable frame='none' tabstyle='proto'> 6206<?dbfo keep-together="always" ?> 6207<tgroup cols='1' align='left' colsep='0' rowsep='0'> 6208<colspec colname='c1' colwidth='1.0*'/> 6209 <thead> 6210 <row> 6211 <entry role='protoname'>XkbGetKbdByName</entry> 6212 </row> 6213 </thead> 6214 <tbody> 6215 <row> 6216 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 6217 </row> 6218 <row> 6219 <entry role='protoname'> 6220need, want: KB_GBNDETAILMASK</entry> 6221 </row> 6222 <row> 6223 <entry role='protoname'> 6224load: BOOL</entry> 6225 </row> 6226 <row> 6227 <entry role='protoname'> 6228keymapsSpec: STRING8</entry> 6229 </row> 6230 <row> 6231 <entry role='protoname'> 6232keycodesSpec, typesSpec: STRING8</entry> 6233 </row> 6234 <row> 6235 <entry role='protoname'> 6236compatMapSpec, symbolsSpec: STRING8</entry> 6237 </row> 6238 <row> 6239 <entry role='protoname'> 6240geometrySpec: STRING8 6241 </entry> 6242 </row> 6243 <row> 6244 <entry role='protoreply'> 6245deviceID: CARD8 6246 </entry> 6247 </row> 6248 <row> 6249 <entry role='protoreply'> 6250minKeyCode, maxKeyCode: KEYCODE 6251 </entry> 6252 </row> 6253 <row> 6254 <entry role='protoreply'> 6255loaded, newKeyboard: BOOL 6256 </entry> 6257 </row> 6258 <row> 6259 <entry role='protoreply'> 6260found, reported: KB_GBNDETAILMASK 6261 </entry> 6262 </row> 6263 <row> 6264 <entry role='protoreply'> 6265map: optional <emphasis> 6266XkbGetMap</emphasis> 6267 reply 6268 </entry> 6269 </row> 6270 <row> 6271 <entry role='protoreply'> 6272compat: optional <emphasis> 6273XkbGetCompatMap</emphasis> 6274 reply 6275 </entry> 6276 </row> 6277 <row> 6278 <entry role='protoreply'> 6279indicators: optional <emphasis> 6280XkbGetIndicatorMap</emphasis> 6281 reply 6282 </entry> 6283 </row> 6284 <row> 6285 <entry role='protoreply'> 6286names: optional <emphasis> 6287XkbGetNames</emphasis> 6288 reply 6289 </entry> 6290 </row> 6291 <row> 6292 <entry role='protoreply'> 6293geometry: optional <emphasis> 6294XkbGetGeometry</emphasis> 6295 reply</entry> 6296 </row> 6297 6298 <row> 6299 <entry role='protoerror'>Errors: <emphasis> 6300Keyboard</emphasis> 6301, <emphasis> 6302Access</emphasis> 6303, <emphasis> 6304Alloc</emphasis> 6305</entry> 6306 </row> 6307 6308 </tbody> 6309 </tgroup> 6310</informaltable> 6311 6312<para> 6313Assembles and returns a keymap from the current mapping and specified elements 6314from the server database of keymap components for the keyboard specified by 6315<emphasis> 6316deviceSpec</emphasis> 6317, and optionally replaces the current keyboard mapping with the newly generated 6318description. If <emphasis> 6319deviceSpec</emphasis> 6320 does not specify a valid keyboard device, a <emphasis> 6321Keyboard</emphasis> 6322 error results. 6323</para> 6324 6325 6326<para> 6327The <emphasis> 6328keymapsSpec</emphasis> 6329, <emphasis> 6330keycodesSpec</emphasis> 6331, <emphasis> 6332typesSpec</emphasis> 6333, <emphasis> 6334compatMapSpec</emphasis> 6335, <emphasis> 6336symbolsSpec</emphasis> 6337 and <emphasis> 6338geometrySpec</emphasis> 6339 component expressions (see <link linkend='Partial_Components_and_Combining_Multiple_Components'> 6340Partial Components and Combining Multiple Components</link>) specify the 6341database components to be used to assemble the keyboard description. 6342</para> 6343 6344 6345<para> 6346The <emphasis> 6347want</emphasis> 6348 field lists the pieces of the keyboard description that the client wants to 6349have reported for the newly constructed keymap. The <emphasis> 6350need</emphasis> 6351 field lists all of the pieces that must be reported. If any of the pieces in 6352<emphasis> 6353need</emphasis> 6354 cannot be loaded from the specified names, no description of the keyboard is 6355returned. 6356</para> 6357 6358 6359<para> 6360The <emphasis> 6361want</emphasis> 6362 and <emphasis> 6363need</emphasis> 6364 fields can include any combinations of these <emphasis> 6365XkbGetMapByName</emphasis> 6366 (GBN) components: 6367</para> 6368 6369<informaltable frame='topbot'> 6370<?dbfo keep-together="always" ?> 6371<tgroup cols='3' align='left' colsep='0' rowsep='0'> 6372<colspec colname='c1' colwidth='1.0*'/> 6373<colspec colname='c2' colwidth='1.0*'/> 6374<colspec colname='c3' colwidth='1.0*'/> 6375<thead> 6376 <row rowsep='1'> 6377 <entry>XkbGetMapByName Keyboard Component…</entry> 6378 <entry>Database Component…</entry> 6379 <entry>Components of Keyboard Description</entry> 6380 </row> 6381</thead> 6382<tbody> 6383 <row> 6384 <entry><emphasis> 6385XkbGBN_Types</emphasis> 6386</entry> 6387 <entry>types</entry> 6388 <entry>key types</entry> 6389 </row> 6390 <row> 6391 <entry><emphasis> 6392XkbGBN_CompatMap</emphasis> 6393</entry> 6394 <entry>compat</entry> 6395 <entry>symbol interpretations, group compatibility map</entry> 6396 </row> 6397 <row> 6398 <entry><emphasis> 6399XkbGBN_ClientSymbols</emphasis> 6400</entry> 6401 <entry>symbols, types, keycodes</entry> 6402 <entry>key types, key symbol mappings, modifier mapping</entry> 6403 </row> 6404 <row> 6405 <entry><emphasis> 6406XkbGBN_ServerSymbols</emphasis> 6407</entry> 6408 <entry>symbols, types, keycodes</entry> 6409 <entry>key behaviors, key actions, key explicit components, virtual 6410modifiers, virtual modifier mapping</entry> 6411 </row> 6412 <row> 6413 <entry><emphasis> 6414XkbGBN_IndicatorMap</emphasis> 6415</entry> 6416 <entry>compat</entry> 6417 <entry>indicator maps, indicator names</entry> 6418 </row> 6419 <row> 6420 <entry><emphasis> 6421XkbGBN_KeyNames</emphasis> 6422</entry> 6423 <entry>keycodes</entry> 6424 <entry>key names, key aliases</entry> 6425 </row> 6426 <row> 6427 <entry><emphasis> 6428XkbGBN_Geometry</emphasis> 6429</entry> 6430 <entry>geometry</entry> 6431 <entry>keyboard geometry</entry> 6432 </row> 6433 <row> 6434 <entry><emphasis> 6435XkbGBN_OtherNames</emphasis> 6436</entry> 6437 <entry>all</entry> 6438 <entry>key types, symbol interpretations, indicator maps, names, 6439geometry</entry> 6440 </row> 6441</tbody> 6442</tgroup> 6443</informaltable> 6444 6445<para> 6446If either field contains a GBN component that depends on some database 6447component for which the request does not supply an expression, XKB 6448automatically substitutes the special pattern "%" which copies the 6449corresponding component from the current keyboard description, as described in 6450<link linkend='Partial_Components_and_Combining_Multiple_Components'>Partial Components and Combining 6451Multiple Components</link>. 6452</para> 6453 6454 6455<para> 6456The <emphasis> 6457load</emphasis> 6458 flag asks the server to replace the current keyboard description for <emphasis> 6459deviceSpec</emphasis> 6460 with the newly constructed keyboard description. If <emphasis> 6461load</emphasis> 6462 is <emphasis> 6463True</emphasis> 6464, the request must include component expressions for all of the database 6465components; if any are missing, XKB substitutes "%" as described above. 6466</para> 6467 6468 6469<para> 6470If all necessary components are both specified and found, the new keyboard 6471description is loaded. If the new keyboard description has a different geometry 6472or keycode range than the previous keyboard description, XKB sends <emphasis> 6473XkbNewKeyboardNotify</emphasis> 6474 events to all interested clients. See 6475<link linkend='Replacing_the_Keyboard_On_the_Fly'>Replacing the Keyboard 6476"On-the-Fly"</link> for more information about the effects of replacing the 6477keyboard description on the fly. 6478</para> 6479 6480 6481<para> 6482If the range of keycodes changes, clients that have requested <emphasis> 6483XkbNewKeyboardNotify</emphasis> 6484 events are not sent any other change notification events by this request. 6485Clients that do not request <emphasis> 6486XkbNewKeyboardNotify</emphasis> 6487 events are sent other XKB change notification events (e.g. <emphasis> 6488XkbMapNotify</emphasis> 6489, <emphasis> 6490XkbNamesNotify</emphasis> 6491) as necessary to alert them to as many of the keyboard changes as possible. 6492</para> 6493 6494 6495<para> 6496If no error occurs, the request reply reports the GBN components that were 6497found and sends a description of any of the resulting keyboard that includes 6498and of the components that were requested. 6499</para> 6500 6501 6502<para> 6503The <emphasis> 6504deviceID</emphasis> 6505 return value reports the X Input extension device identifier of the keyboard 6506that was used, or <emphasis> 65070</emphasis> 6508 if the server does not support the X input extension. 6509</para> 6510 6511 6512<para> 6513The <emphasis> 6514minKeyCode</emphasis> 6515 and <emphasis> 6516maxKeyCode</emphasis> 6517 return values report the legal range of keycodes for the keyboard description 6518that was created. If the resulting keyboard description does not include at 6519least one of the key names, client symbols or server symbols components, 6520<emphasis> 6521minKeyCode</emphasis> 6522 and <emphasis> 6523maxKeyCode</emphasis> 6524 are both <emphasis> 65250</emphasis> 6526. 6527</para> 6528 6529 6530<para> 6531The <emphasis> 6532loaded</emphasis> 6533 return value reports whether or not the existing keyboard definition was 6534replaced with the newly created one. If <emphasis> 6535loaded</emphasis> 6536 is <emphasis> 6537True</emphasis> 6538, the <emphasis> 6539newKeyboard</emphasis> 6540 return value reports whether or not the new map changed the geometry or range 6541of keycodes and caused <emphasis> 6542XkbNewKeyboardNotify</emphasis> 6543 events for clients that have requested them. 6544</para> 6545 6546 6547<para> 6548The <emphasis> 6549found</emphasis> 6550 return value reports the GBN components that were present in the keymap that 6551was constructed by this request. The <emphasis> 6552reported</emphasis> 6553 return value lists the subset of those components for which descriptions 6554follow. if any of the components specified in the <emphasis> 6555need</emphasis> 6556 field of the request were not found, <emphasis> 6557reported</emphasis> 6558 is empty, otherwise it contains the intersection of the <emphasis> 6559found</emphasis> 6560 return value with the union of the <emphasis> 6561need</emphasis> 6562 and <emphasis> 6563want</emphasis> 6564 request fields. 6565</para> 6566 6567 6568<para> 6569If any of <emphasis> 6570GBN_Types</emphasis> 6571, <emphasis> 6572GBN_ClientSymbols</emphasis> 6573 or <emphasis> 6574GBN_ServerSymbols</emphasis> 6575 are set in <emphasis> 6576reported</emphasis> 6577, the <emphasis> 6578map</emphasis> 6579 return value has the same format as the reply to an <emphasis> 6580XkbGetMap</emphasis> 6581 request and reports the corresponding pieces of the newly constructed keyboard 6582description. 6583</para> 6584 6585 6586<para> 6587If <emphasis> 6588GBN_CompatMap</emphasis> 6589 is set in <emphasis> 6590reported</emphasis> 6591, the <emphasis> 6592compat</emphasis> 6593 return value has the same format as the reply to an <emphasis> 6594XkbGetCompatMap</emphasis> 6595 request and reports the symbol interpretations and group compatibility map for 6596the newly constructed keyboard description. 6597</para> 6598 6599 6600<para> 6601If <emphasis> 6602GBN_IndicatorMap</emphasis> 6603 is set in <emphasis> 6604reported</emphasis> 6605, the <emphasis> 6606indicators</emphasis> 6607 return value has the same format as the reply to an <emphasis> 6608XkbGetIndicatorMap</emphasis> 6609 request and reports the physical indicators and indicator maps for the newly 6610constructed keyboard description. 6611</para> 6612 6613 6614<para> 6615If <emphasis> 6616GBN_KeyNames</emphasis> 6617 or <emphasis> 6618GBN_OtherNames</emphasis> 6619 are set in <emphasis> 6620reported</emphasis> 6621, the <emphasis> 6622names</emphasis> 6623 return value has the same format as the reply to an <emphasis> 6624XkbGetNames</emphasis> 6625 reply and reports the corresponding set of symbolic names for the newly 6626constructed keyboard description. 6627</para> 6628 6629 6630<para> 6631If <emphasis> 6632GBN_Geometry</emphasis> 6633 is set in <emphasis> 6634reported</emphasis> 6635, the <emphasis> 6636geometry</emphasis> 6637 return value has the same format as the reply to an <emphasis> 6638XkbGetGeometryMap</emphasis> 6639 request and reports the keyboard geometry for the newly constructed keyboard 6640description. 6641</para> 6642 6643 6644</sect2> 6645<sect2 id='Querying_and_Changing_Input_Extension_Devices'> 6646<title>Querying and Changing Input Extension Devices</title> 6647 6648 6649<informaltable frame='none' tabstyle='proto'> 6650<?dbfo keep-together="always" ?> 6651<tgroup cols='1' align='left' colsep='0' rowsep='0'> 6652<colspec colname='c1' colwidth='1.0*'/> 6653 <thead> 6654 <row> 6655 <entry role='protoname'>XkbGetDeviceInfo</entry> 6656 </row> 6657 </thead> 6658 <tbody> 6659 <row> 6660 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 6661 </row> 6662 <row> 6663 <entry role='protoname'> 6664wanted: KB_XIDEVFEATUREMASK</entry> 6665 </row> 6666 <row> 6667 <entry role='protoname'> 6668ledClass: KB_LEDCLASSSPEC</entry> 6669 </row> 6670 <row> 6671 <entry role='protoname'> 6672ledID: KB_IDSPEC</entry> 6673 </row> 6674 <row> 6675 <entry role='protoname'> 6676allButtons: BOOL</entry> 6677 </row> 6678 <row> 6679 <entry role='protoname'> 6680firstButton, nButtons: CARD8 6681 </entry> 6682 </row> 6683 <row> 6684 <entry role='protoreply'> 6685deviceID: CARD8 6686 </entry> 6687 </row> 6688 <row> 6689 <entry role='protoreply'> 6690present: KB_XIDEVFEATUREMASK 6691 </entry> 6692 </row> 6693 <row> 6694 <entry role='protoreply'> 6695supported: KB_XIFEATUREMASK 6696 </entry> 6697 </row> 6698 <row> 6699 <entry role='protoreply'> 6700unsupported: KB_XIFEATUREMASK 6701 </entry> 6702 </row> 6703 <row> 6704 <entry role='protoreply'> 6705firstBtnWanted: CARD8 6706 </entry> 6707 </row> 6708 <row> 6709 <entry role='protoreply'> 6710nBtnsWanted: CARD8 6711 </entry> 6712 </row> 6713 <row> 6714 <entry role='protoreply'> 6715firstBtnRtrn: CARD8 6716 </entry> 6717 </row> 6718 <row> 6719 <entry role='protoreply'> 6720nBtnsRtrn: CARD8 6721 </entry> 6722 </row> 6723 <row> 6724 <entry role='protoreply'> 6725totalBtns: CARD8 6726 </entry> 6727 </row> 6728 <row> 6729 <entry role='protoreply'> 6730hasOwnState: BOOL 6731 </entry> 6732 </row> 6733 <row> 6734 <entry role='protoreply'> 6735dfltKbdFB, dfltLedFB: KB_IDSPEC 6736 </entry> 6737 </row> 6738 <row> 6739 <entry role='protoreply'> 6740devType: ATOM 6741 </entry> 6742 </row> 6743 <row> 6744 <entry role='protoreply'> 6745name: STRING 6746 </entry> 6747 </row> 6748 <row> 6749 <entry role='protoreply'> 6750btnActions: LISTofKB_ACTION 6751 </entry> 6752 </row> 6753 <row> 6754 <entry role='protoreply'> 6755leds: LISTofKB_DEVICELEDINFO</entry> 6756 </row> 6757 6758 <row> 6759 <entry role='protoerror'>Errors: <emphasis> 6760Device</emphasis> 6761, <emphasis> 6762Match</emphasis> 6763, <emphasis> 6764Access</emphasis> 6765, <emphasis> 6766Alloc</emphasis> 6767</entry> 6768 </row> 6769 6770 </tbody> 6771 </tgroup> 6772</informaltable> 6773 6774<para> 6775Reports a subset of the XKB-supplied information about the input device 6776specified by <emphasis> 6777deviceSpec</emphasis> 6778. Unlike most XKB requests, the device specified for <emphasis> 6779XkbGetDeviceInfo</emphasis> 6780 need not be a keyboard device. Nonetheless, a <emphasis> 6781Keyboard</emphasis> 6782 error results if <emphasis> 6783deviceSpec</emphasis> 6784 does not specify a valid core or input extension device. 6785</para> 6786 6787 6788<para> 6789The <emphasis> 6790wanted</emphasis> 6791 field specifies the types of information to be returned, and controls the 6792interpretation of the other request fields. 6793</para> 6794 6795 6796<para> 6797If the server does not support assignment of XKB actions to extension device 6798buttons, the <emphasis> 6799allButtons</emphasis> 6800, <emphasis> 6801firstButton</emphasis> 6802 and <emphasis> 6803nButtons</emphasis> 6804 fields are ignored. 6805</para> 6806 6807 6808<para> 6809Otherwise, if the <emphasis> 6810XkbXI_ButtonActions</emphasis> 6811 flag is set in <emphasis> 6812wanted</emphasis> 6813, the <emphasis> 6814allButtons</emphasis> 6815, <emphasis> 6816firstButton</emphasis> 6817 and <emphasis> 6818nButtons</emphasis> 6819 fields specify the device buttons for which actions should be returned. 6820Setting <emphasis> 6821allButtons</emphasis> 6822 to <emphasis> 6823True</emphasis> 6824 requests actions for all device buttons; if <emphasis> 6825allButtons</emphasis> 6826 is <emphasis> 6827False</emphasis> 6828, <emphasis> 6829firstButton</emphasis> 6830 and <emphasis> 6831nButtons</emphasis> 6832 specify a range of buttons for which actions are requested. If the device has 6833no buttons or if <emphasis> 6834firstButton</emphasis> 6835 and <emphasis> 6836nButtons</emphasis> 6837 specify illegal buttons, a <emphasis> 6838Match</emphasis> 6839 error results. If <emphasis> 6840allButtons</emphasis> 6841 is <emphasis> 6842True</emphasis> 6843, <emphasis> 6844firstButton</emphasis> 6845 and <emphasis> 6846nButtons</emphasis> 6847 are ignored. 6848</para> 6849 6850 6851<para> 6852If the server does not support XKB access to any aspect of the indicators on 6853extension devices, or if the <emphasis> 6854wanted</emphasis> 6855 field does not include any of the indicator flags, the <emphasis> 6856ledClass</emphasis> 6857 and <emphasis> 6858ledID</emphasis> 6859 fields are ignored. Otherwise, <emphasis> 6860ledClass</emphasis> 6861 and <emphasis> 6862ledID</emphasis> 6863 specify one or more feedback(s) for which indicator information is requested. 6864If <emphasis> 6865ledClass</emphasis> 6866 or <emphasis> 6867ledID</emphasis> 6868 have illegal values, a <emphasis> 6869Value</emphasis> 6870 error results. If they have legal values but do not specify a keyboard or 6871indicator class feedback for the device in question, a <emphasis> 6872Match</emphasis> 6873 error results. 6874</para> 6875 6876 6877<para> 6878The <emphasis> 6879ledClass</emphasis> 6880 field can specify either <emphasis> 6881KbdFeedbackClass</emphasis> 6882, <emphasis> 6883LedFeedbackClass</emphasis> 6884, <emphasis> 6885XkbDfltXIClass</emphasis> 6886, or <emphasis> 6887XkbAllXIClasses</emphasis> 6888. If at least one keyboard feedback is defined for the specified device, 6889<emphasis> 6890XkbDfltXIClass</emphasis> 6891 is equivalent to <emphasis> 6892KbdFeedbackClass</emphasis> 6893, otherwise it is equivalent to <emphasis> 6894LedFeedbackClass</emphasis> 6895. If <emphasis> 6896XkbAllXIClasses</emphasis> 6897 is specified, this request returns information about both indicator and 6898keyboard class feedbacks which match the requested identifier, as described 6899below. 6900</para> 6901 6902 6903<para> 6904The <emphasis> 6905ledID</emphasis> 6906 field can specify any valid input extension feedback identifier, <emphasis> 6907XkbDfltXIId</emphasis> 6908, or <emphasis> 6909XkbAllXIIds</emphasis> 6910. The default keyboard feedback is the one that is affected by core protocol 6911requests; the default led feedback is implementation-specific. If <emphasis> 6912XkbAllXIIds</emphasis> 6913 is specified, this request returns indicator information about all feedbacks 6914of the class(es) specified by <emphasis> 6915ledClass</emphasis> 6916. 6917</para> 6918 6919 6920<para> 6921If no error results, the <emphasis> 6922deviceID</emphasis> 6923 return value reports the input extension device identifier of the device for 6924which values are being returned. The <emphasis> 6925supported</emphasis> 6926 return value reports the set of optional XKB extension device features that 6927are supported by this implementation (see 6928<link linkend='Interactions_Between_XKB_and_the_X_Input_Extension'> 6929Interactions Between XKB and the X Input 6930Extension</link>) for the specified device, and the unsupported return value 6931reports any <emphasis> 6932unsupported</emphasis> 6933 features. 6934</para> 6935 6936 6937<para> 6938If <emphasis> 6939hasOwnState</emphasis> 6940 is <emphasis> 6941True</emphasis> 6942, the device is also a keyboard, and any indicator maps bound to the device use 6943the current state and control settings for this device to control automatic 6944changes. If <emphasis> 6945hasOwnState</emphasis> 6946 is <emphasis> 6947False</emphasis> 6948, the state and control settings of the core keyboard device control automatic 6949indicator changes. 6950</para> 6951 6952 6953<para> 6954The <emphasis> 6955name</emphasis> 6956 field reports the X Input Extension name for the device. The <emphasis> 6957devType</emphasis> 6958 field reports the X Input Extension device type. Both fields are provided 6959merely for convenience and are not interpreted by XKB. 6960</para> 6961 6962 6963<para> 6964The <emphasis> 6965present</emphasis> 6966 return value reports the kinds of device information being returned, and 6967controls the interpretation of the remaining fields. The <emphasis> 6968present</emphasis> 6969 field consists of the <emphasis> 6970wanted</emphasis> 6971 field from the original request minus the flags for any unsupported features. 6972</para> 6973 6974 6975<para> 6976If <emphasis> 6977XkbXI_ButtonActions</emphasis> 6978 is set in <emphasis> 6979present</emphasis> 6980, the <emphasis> 6981totalBtns</emphasis> 6982 return value reports the total number of buttons present on the device, 6983<emphasis> 6984firstBtnWanted</emphasis> 6985 and <emphasis> 6986nBtnsWanted</emphasis> 6987 specify the range of buttons for which actions were requested, and the 6988<emphasis> 6989firstBtnRtrn</emphasis> 6990 and <emphasis> 6991nBtnsRtrn </emphasis> 6992values specify the range of buttons for which actions are reported. The 6993<emphasis> 6994actionsRtrn</emphasis> 6995 list has <emphasis> 6996nButtonsRtrn</emphasis> 6997 entries which contain the actions bound to the specified buttons on the 6998device. Any buttons for which actions were requested but not returned have the 6999action <emphasis> 7000NoAction()</emphasis> 7001. 7002</para> 7003 7004 7005<para> 7006If any indicator information is reported, the leds list contains one element 7007for each requested feedback. For example, if <emphasis> 7008ledClass</emphasis> 7009 is <emphasis> 7010XkbAllXIClasses</emphasis> 7011 and <emphasis> 7012ledID</emphasis> 7013 is <emphasis> 7014XkbAllXIIds</emphasis> 7015, <emphasis> 7016leds</emphasis> 7017 describes all of the indicators on the device and has one element for each 7018keyboard or led class feedback defined for the device. If any information at 7019all is reported about a feedback, the set of physical indicators is also 7020reported in the <emphasis> 7021physIndicators</emphasis> 7022 field of the corresponding element of <emphasis> 7023leds</emphasis> 7024. 7025</para> 7026 7027 7028<para> 7029If the server supports assignment of indicator maps to extension device 7030indicators, and if the <emphasis> 7031XkbXI_IndicatorMaps</emphasis> 7032 flag is set in <emphasis> 7033wanted</emphasis> 7034, each member of <emphasis> 7035leds</emphasis> 7036 reports any indicators on the corresponding feedback to which names have been 7037assigned. Any indicators for which no map is reported have the default map, 7038which allows explicit changes and does not request any automatic changes. 7039</para> 7040 7041 7042<para> 7043If the server supports assignment of indicator names to extension device 7044indicators, and the <emphasis> 7045XkbXI_IndicatorNames</emphasis> 7046 flag is set in <emphasis> 7047wanted</emphasis> 7048, each member of <emphasis> 7049leds</emphasis> 7050 reports any indicators on the corresponding feedback to which names have been 7051assigned. Any indicators for which no name is reported have the name <emphasis> 7052None</emphasis> 7053. 7054</para> 7055 7056 7057<para> 7058If the server supports XKB access to the state of extension device indicators, 7059and the <emphasis> 7060XkbXI_IndicatorState</emphasis> 7061 flag is set in wanted, each member of leds reports the state of the indicators 7062on the corresponding feedback. 7063</para> 7064 7065 7066<para> 7067If any unsupported features are requested, and the requesting client has 7068selected for them, the server sends the client an <emphasis> 7069XkbExtensionDeviceNotify</emphasis> 7070 event which indicates that an unsupported feature was requested. This event is 7071only generated if the client which issued the unsupported request has selected 7072for it and, if generated, is not sent to any other clients. 7073</para> 7074 7075 7076 7077<informaltable frame='none' tabstyle='proto'> 7078<?dbfo keep-together="always" ?> 7079<tgroup cols='1' align='left' colsep='0' rowsep='0'> 7080<colspec colname='c1' colwidth='1.0*'/> 7081 <thead> 7082 <row> 7083 <entry role='protoname'>XkbSetDeviceInfo</entry> 7084 </row> 7085 </thead> 7086 <tbody> 7087 <row> 7088 <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> 7089 </row> 7090 <row> 7091 <entry role='protoname'> 7092change: KB_XIDEVFEATUREMASK</entry> 7093 </row> 7094 <row> 7095 <entry role='protoname'> 7096firstBtn, nBtns: CARD8</entry> 7097 </row> 7098 <row> 7099 <entry role='protoname'> 7100btnActions:LISTofKB_ACTION</entry> 7101 </row> 7102 <row> 7103 <entry role='protoname'> 7104leds: LISTofKB_DEVICELEDINFO</entry> 7105 </row> 7106 7107 <row> 7108 <entry role='protoerror'>Errors: <emphasis> 7109Device</emphasis> 7110, <emphasis> 7111Match</emphasis> 7112, <emphasis> 7113Access</emphasis> 7114, <emphasis> 7115Alloc</emphasis> 7116</entry> 7117 </row> 7118 7119 </tbody> 7120 </tgroup> 7121</informaltable> 7122 7123<para> 7124Changes a subset of the XKB-supplied information about the input device 7125specified by <emphasis> 7126deviceSpec</emphasis> 7127. Unlike most XKB requests, the device specified for <emphasis> 7128XkbGetDeviceInfo</emphasis> 7129 need not be a keyboard device. Nonetheless, a <emphasis> 7130Keyboard</emphasis> 7131 error results if <emphasis> 7132deviceSpec</emphasis> 7133 does not specify a valid core or input extension device 7134</para> 7135 7136 7137<para> 7138The <emphasis> 7139change</emphasis> 7140 field specifies the features for which new values are supplied, and controls 7141the interpretation of the other request fields. 7142</para> 7143 7144 7145<para> 7146If the server does not support assignment of XKB actions to extension device 7147buttons, the <emphasis> 7148firstButton</emphasis> 7149 and <emphasis> 7150nButtons</emphasis> 7151 fields are ignored. 7152</para> 7153 7154 7155<para> 7156Otherwise, if the <emphasis> 7157XkbXI_ButtonActions</emphasis> 7158 flag is set in <emphasis> 7159change</emphasis> 7160, the <emphasis> 7161firstBtn</emphasis> 7162 and <emphasis> 7163nBtns</emphasis> 7164 fields specify a range of buttons for which actions are specified in this 7165request. If the device has no buttons or if <emphasis> 7166firstBtn</emphasis> 7167 and <emphasis> 7168nBtns</emphasis> 7169 specify illegal buttons, a <emphasis> 7170Match</emphasis> 7171 error results. 7172</para> 7173 7174 7175<para> 7176Each element of the <emphasis> 7177leds</emphasis> 7178 list describes the changes for a single keyboard or led feedback. If the 7179<emphasis> 7180ledClass</emphasis> 7181 field of any element of <emphasis> 7182leds</emphasis> 7183 contains any value other than <emphasis> 7184KbdFeedbackClass</emphasis> 7185, <emphasis> 7186LedFeedbackClass</emphasis> 7187 or <emphasis> 7188XkbDfltXIClass</emphasis> 7189, a <emphasis> 7190Value</emphasis> 7191 error results. If the <emphasis> 7192ledId</emphasis> 7193 field of any element of leds contains any value other than a valid input 7194extension feedback identifier or <emphasis> 7195XkbDfltXIId</emphasis> 7196, a <emphasis> 7197Value</emphasis> 7198 error results. If both fields are valid, but the device has no matching 7199feedback, a <emphasis> 7200Match</emphasis> 7201 error results. 7202</para> 7203 7204 7205<para> 7206The fields of each element of <emphasis> 7207leds</emphasis> 7208 are interpreted as follows: 7209</para> 7210 7211<itemizedlist> 7212<listitem> 7213 <para>If <emphasis> 7214XkbXI_IndicatorMaps</emphasis> 7215 is set in <emphasis> 7216change</emphasis> 7217 and the server supports XKB assignment of indicator maps to the corresponding 7218feedback, the maps for all indicators on the corresponding feedback are taken 7219from <emphasis> 7220leds</emphasis> 7221. If the server does not support this feature, any maps specified in <emphasis> 7222leds</emphasis> 7223 are ignored. 7224 </para> 7225</listitem> 7226<listitem> 7227 <para>If <emphasis> 7228XkbXI_IndicatorNames</emphasis> 7229 is set in <emphasis> 7230change</emphasis> 7231, and the server supports XKB assignment of names to indicators for the 7232corresponding feedback, the names for all indicators on the corresponding 7233feedback are taken from <emphasis> 7234leds</emphasis> 7235. If the server does not support this feature, any names specified in <emphasis> 7236leds</emphasis> 7237 are ignored. Regardless of whether they are used, any names be a valid Atom or 7238<emphasis> 7239None</emphasis> 7240, or an <emphasis> 7241Atom</emphasis> 7242 error results. 7243 </para> 7244</listitem> 7245<listitem> 7246 <para>If <emphasis> 7247XkbXI_IndicatorState</emphasis> 7248 is set in change, and the server supports XKB changes to extension device 7249indicator state, the server attempts to change the indicators on the 7250corresponding feedback as specified by <emphasis> 7251leds</emphasis> 7252. Any indicator maps bound to the feedback are applied, so state changes might 7253be blocked or have side-effects. 7254 </para> 7255</listitem> 7256</itemizedlist> 7257 7258<para> 7259If any unsupported features are requested, and the requesting client has 7260selected for them, the server sends the client an <emphasis> 7261XkbExtensionDeviceNotify</emphasis> 7262 event which indicates that an unsupported feature was requested. This event is 7263only generated if the client which issued the unsupported request has selected 7264for it and, if generated, is not sent to any other clients. 7265</para> 7266 7267 7268</sect2> 7269<sect2 id='Debugging_the_X_Keyboard_Extension'> 7270<title>Debugging the X Keyboard Extension</title> 7271 7272 7273<informaltable frame='none' tabstyle='proto'> 7274<?dbfo keep-together="always" ?> 7275<tgroup cols='1' align='left' colsep='0' rowsep='0'> 7276<colspec colname='c1' colwidth='1.0*'/> 7277 <thead> 7278 <row> 7279 <entry role='protoname'>XkbSetDebuggingFlags</entry> 7280 </row> 7281 </thead> 7282 <tbody> 7283 <row> 7284 <entry role='protoargs'>affectFlags, flags: CARD32</entry> 7285 </row> 7286 <row> 7287 <entry role='protoname'> 7288affectCtrls, ctrls: CARD32</entry> 7289 </row> 7290 <row> 7291 <entry role='protoname'> 7292message: STRING 7293 </entry> 7294 </row> 7295 <row> 7296 <entry role='protoreply'> 7297currentFlags, supportedFlags: CARD32 7298 </entry> 7299 </row> 7300 <row> 7301 <entry role='protoreply'> 7302currentCtrls, supportedCtrls: CARD32</entry> 7303 </row> 7304 7305 </tbody> 7306 </tgroup> 7307</informaltable> 7308 7309<para> 7310This request sets up various internal XKB debugging flags and controls. It is 7311intended for developer use and may be disabled in production servers. If 7312disabled, <emphasis> 7313XkbSetDebuggingFlags</emphasis> 7314 has no effect but returns <emphasis> 7315Success</emphasis> 7316. 7317</para> 7318 7319 7320<para> 7321The <emphasis> 7322affectFlags</emphasis> 7323 field specifies the debugging flags to be changed, the <emphasis> 7324flags</emphasis> 7325 field specifies new values for the changed flags. The interpretation of the 7326debugging flags is implementation-specific, but flags are intended to control 7327debugging output and should not otherwise affect the operation of the server. 7328</para> 7329 7330 7331<para> 7332The <emphasis> 7333affectCtrls</emphasis> 7334 field specifies the debugging controls to be changed, the <emphasis> 7335ctrls</emphasis> 7336 field specifies new values for the changed controls. The interpretation of the 7337debugging controls is implementation-specific, but debugging controls are 7338allowed to affect the behavior of the server. 7339</para> 7340 7341 7342<para> 7343The <emphasis> 7344message</emphasis> 7345 field provides a message that the X server can print in any logging or 7346debugging files before changing the flags. The server must accept this field 7347but it is not required to actually display it anywhere. 7348</para> 7349 7350 7351<para> 7352The X Test Suite makes some assumptions about the implementation of locking 7353modifier keys that do not apply when XKB is present. The <emphasis> 7354XkbDF_DisableLocks</emphasis> 7355 debugging control provides a simple workaround to these test suite problems by 7356simply disabling all locking keys. If <emphasis> 7357XkbDF_DisableLocks</emphasis> 7358 is enabled, the <emphasis> 7359SA_LockMods</emphasis> 7360 and <emphasis> 7361SA_LockGroup</emphasis> 7362 actions behave like <emphasis> 7363SA_SetMods</emphasis> 7364 and <emphasis> 7365SA_LockMods</emphasis> 7366, respectively. If it is disabled, <emphasis> 7367SA_LockMods</emphasis> 7368 and <emphasis> 7369SA_LockGroup</emphasis> 7370 actions behave normally. 7371</para> 7372 7373 7374<para> 7375Implementations are free to ignore the <emphasis> 7376XkbDF_DisableLocks</emphasis> 7377 debugging control or to define others. 7378</para> 7379 7380 7381<para> 7382The <emphasis> 7383currentFlags</emphasis> 7384 return value reports the current setting for the debugging flags, if 7385applicable. The <emphasis> 7386currentCtrls</emphasis> 7387 return value reports the setting for the debugging controls, if applicable. 7388The <emphasis> 7389supportedFlags</emphasis> 7390 and <emphasis> 7391supportedCtrls</emphasis> 7392 fields report the flags and controls that are recognized by the 7393implementation. Attempts to change unsupported fields or controls are silently 7394ignored. 7395</para> 7396 7397 7398<para> 7399If the <emphasis> 7400XkbSetDebuggingFlags</emphasis> 7401 request contains more data than expected, the server ignores the extra data, 7402but no error results. If the request has less data than expected, a <emphasis> 7403Length</emphasis> 7404 error results. 7405</para> 7406 7407 7408<para> 7409If the <emphasis> 7410XkbSetDebuggingFlags</emphasis> 7411 reply contains more data than expected, the client just ignores any 7412uninterpreted data without reporting an error. If the reply has less data than 7413expected, a <emphasis> 7414Length</emphasis> 7415 error results. 7416</para> 7417 7418 7419</sect2> 7420</sect1> 7421<sect1 id='Events'> 7422<title>Events</title> 7423 7424<para> 7425All XKB events report the time at which they occurred in a field named 7426<emphasis> 7427time</emphasis> 7428 and the device on which they occurred in a field named <emphasis> 7429deviceID</emphasis> 7430. XKB uses a single X event code for all events and uses a common field to 7431distinguish XKB event type. 7432</para> 7433 7434 7435<sect2 id='Tracking_Keyboard_Replacement'> 7436<title>Tracking Keyboard Replacement</title> 7437 7438 7439<informaltable frame='none' tabstyle='proto'> 7440<?dbfo keep-together="always" ?> 7441<tgroup cols='1' align='left' colsep='0' rowsep='0'> 7442<colspec colname='c1' colwidth='1.0*'/> 7443 <thead> 7444 <row> 7445 <entry role='protoname'>XkbNewKeyboardNotify</entry> 7446 </row> 7447 </thead> 7448 <tbody> 7449 <row> 7450 <entry role='protoargs'>time: TIMESTAMP</entry> 7451 </row> 7452 <row> 7453 <entry role='protoname'> 7454deviceID: CARD8</entry> 7455 </row> 7456 <row> 7457 <entry role='protoname'> 7458changed: KB_NKNDETAILMASK</entry> 7459 </row> 7460 <row> 7461 <entry role='protoname'> 7462minKeyCode, maxKeyCode: KEYCODE</entry> 7463 </row> 7464 <row> 7465 <entry role='protoname'> 7466oldDeviceID: CARD8</entry> 7467 </row> 7468 <row> 7469 <entry role='protoname'> 7470oldMinKeyCode, oldMaxKeyCode: KEYCODE</entry> 7471 </row> 7472 <row> 7473 <entry role='protoname'> 7474requestMajor, requestMinor: CARD8</entry> 7475 </row> 7476 7477 </tbody> 7478 </tgroup> 7479</informaltable> 7480 7481<para> 7482An <emphasis> 7483XkbNewKeyboardNotify</emphasis> 7484 event reports that a new core keyboard has been installed. New keyboard notify 7485events can be generated: 7486</para> 7487 7488<itemizedlist> 7489<listitem> 7490 <para>When the X server detects that the keyboard was changed. 7491 </para> 7492</listitem> 7493<listitem> 7494 <para>When a client installs a new extension device as the core keyboard 7495using the X Input Extension <emphasis> 7496ChangeKeyboardDevice</emphasis> 7497 request. 7498 </para> 7499</listitem> 7500<listitem> 7501 <para>When a client issues an <emphasis> 7502XkbGetMapByName</emphasis> 7503 request which changes the keycodes range or geometry. 7504 </para> 7505</listitem> 7506</itemizedlist> 7507 7508<para> 7509The <emphasis> 7510changed</emphasis> 7511 field of the event reports the aspects of the keyboard that have changed, and 7512can contain any combination of the event details for this event: 7513</para> 7514 7515<informaltable frame='topbot'> 7516<?dbfo keep-together="always" ?> 7517<tgroup cols='2' align='left' colsep='0' rowsep='0'> 7518<colspec colname='c1' colwidth='1.0*'/> 7519<colspec colname='c2' colwidth='2.0*'/> 7520<thead> 7521 <row rowsep='1'> 7522 <entry>Bit in Changed</entry> 7523 <entry>Meaning</entry> 7524 </row> 7525</thead> 7526<tbody> 7527 <row> 7528 <entry>NKN_Keycodes</entry> 7529 <entry>The new keyboard has a different minimum or maximum keycode.</entry> 7530 </row> 7531 <row> 7532 <entry>NKN_Geometry</entry> 7533 <entry>The new keyboard has a different keyboard geometry.</entry> 7534 </row> 7535 <row> 7536 <entry>NKN_DeviceID</entry> 7537 <entry>The new keyboard has a new X Input Extension device 7538identifier</entry> 7539 </row> 7540</tbody> 7541</tgroup> 7542</informaltable> 7543 7544<para> 7545The server sends an <emphasis> 7546XkbNewKeyboardNotify</emphasis> 7547 event to a client only if at least one of the bits that is set in the 7548<emphasis> 7549changed</emphasis> 7550 field of the event is also set in the appropriate event details mask for the 7551client. 7552</para> 7553 7554 7555<para> 7556The <emphasis> 7557minKeyCode</emphasis> 7558 and <emphasis> 7559maxKeyCode</emphasis> 7560 fields report the minimum and maximum keycodes that can be returned by the new 7561keyboard. The <emphasis> 7562oldMinKeyCode</emphasis> 7563 and <emphasis> 7564oldMaxKeyCode</emphasis> 7565 fields report the minimum and maximum values that could be returned before the 7566change. This event always reports all four values, but the old and new values 7567are the same unless <emphasis> 7568NKN_Keycodes</emphasis> 7569 is set in <emphasis> 7570changed</emphasis> 7571. 7572</para> 7573 7574 7575<para> 7576Once a client receives a new keyboard notify event which reports a new keycode 7577range, the X server reports events from all keys in the new range to that 7578client. Clients that do not request or receive new keyboard notify events 7579receive events only from keys that fall in the last range for legal keys 7580reported to that client. See <link linkend='Replacing_the_Keyboard_On_the_Fly'> 7581Replacing the Keyboard "On-the-Fly"</link> for a more detailed explanation. 7582</para> 7583 7584 7585<para> 7586If <emphasis> 7587NKN_Keycodes</emphasis> 7588 is set in <emphasis> 7589changed</emphasis> 7590, the <emphasis> 7591XkbNewKeyboardNotify</emphasis> 7592 event subsumes all other change notification events (e.g. <emphasis> 7593XkbMapNotify</emphasis> 7594, <emphasis> 7595XkbNamesNotify</emphasis> 7596) that would otherwise result from the keyboard change. Clients who receive an 7597<emphasis> 7598XkbNewKeyboardNotify</emphasis> 7599 event should assume that all other aspects of the keyboard mapping have 7600changed and regenerate the entire local copy of the keyboard description. 7601</para> 7602 7603 7604<para> 7605The <emphasis> 7606deviceID</emphasis> 7607 field reports the X Input Extension device identifier of the new keyboard 7608device; <emphasis> 7609oldDeviceID</emphasis> 7610 reports the device identifier before the change. This event always includes 7611both values, but they are the same unless <emphasis> 7612NKN_DeviceID</emphasis> 7613 is set in <emphasis> 7614changed</emphasis> 7615. If the server does not support the X Input Extension, both fields have the 7616value <emphasis> 76170</emphasis> 7618. 7619</para> 7620 7621 7622<para> 7623The <emphasis> 7624requestMajor</emphasis> 7625 and <emphasis> 7626requestMinor</emphasis> 7627 fields report the major and minor opcode of the request that caused the 7628keyboard change. If the keyboard change was not caused by some client request, 7629both fields have the value <emphasis> 76300</emphasis> 7631. 7632</para> 7633 7634 7635</sect2> 7636<sect2 id='Tracking_Keyboard_Mapping_Changes'> 7637<title>Tracking Keyboard Mapping Changes</title> 7638 7639 7640<informaltable frame='none' tabstyle='proto'> 7641<?dbfo keep-together="always" ?> 7642<tgroup cols='1' align='left' colsep='0' rowsep='0'> 7643<colspec colname='c1' colwidth='1.0*'/> 7644 <thead> 7645 <row> 7646 <entry role='protoname'>XkbMapNotify</entry> 7647 </row> 7648 </thead> 7649 <tbody> 7650 <row> 7651 <entry role='protoargs'>time: TIMESTAMP</entry> 7652 </row> 7653 <row> 7654 <entry role='protoname'> 7655deviceID: CARD8</entry> 7656 </row> 7657 <row> 7658 <entry role='protoname'> 7659ptrBtnActions: CARD8</entry> 7660 </row> 7661 <row> 7662 <entry role='protoname'> 7663changed: KB_MAPPARTMASK</entry> 7664 </row> 7665 <row> 7666 <entry role='protoname'> 7667minKeyCode, maxKeyCode: KEYCODE</entry> 7668 </row> 7669 <row> 7670 <entry role='protoname'> 7671firstType, nTypes: CARD8</entry> 7672 </row> 7673 <row> 7674 <entry role='protoname'> 7675firstKeySym, firstKeyAction: KEYCODE</entry> 7676 </row> 7677 <row> 7678 <entry role='protoname'> 7679nKeySyms, nKeyActions: CARD8</entry> 7680 </row> 7681 <row> 7682 <entry role='protoname'> 7683firstKeyBehavior, firstKeyExplicit: KEYCODE</entry> 7684 </row> 7685 <row> 7686 <entry role='protoname'> 7687nKeyBehaviors, nKeyExplicit: CARD8</entry> 7688 </row> 7689 <row> 7690 <entry role='protoname'> 7691virtualMods: KB_VMODMASK</entry> 7692 </row> 7693 <row> 7694 <entry role='protoname'> 7695firstModMapKey, firstVModMapKey: KEYCODE</entry> 7696 </row> 7697 <row> 7698 <entry role='protoname'> 7699nModMapKeys, nVModMapKeys: CARD8</entry> 7700 </row> 7701 7702 </tbody> 7703 </tgroup> 7704</informaltable> 7705 7706<para> 7707An <emphasis> 7708XkbMapNotify</emphasis> 7709 event reports that some aspect of XKB map for a keyboard has changed. Map 7710notify events can be generated whenever some aspect of the keyboard map is 7711changed by an XKB or core protocol request. 7712</para> 7713 7714 7715<para> 7716The <emphasis> 7717deviceID</emphasis> 7718 field reports the keyboard for which some map component has changed and the 7719<emphasis> 7720changed</emphasis> 7721 field reports the components with new values, and can contain any of the 7722values that are legal for the <emphasis> 7723full</emphasis> 7724 and <emphasis> 7725partial</emphasis> 7726 fields of the <emphasis> 7727XkbGetMap</emphasis> 7728 request. The server sends an <emphasis> 7729XkbMapNotify</emphasis> 7730 event to a client only if at least one of the bits that is set in the 7731<emphasis> 7732changed</emphasis> 7733 field of the event is also set in the appropriate event details mask for the 7734client. 7735</para> 7736 7737 7738<para> 7739The <emphasis> 7740minKeyCode</emphasis> 7741 and <emphasis> 7742maxKeyCode</emphasis> 7743 fields report the range of keycodes that are legal on the keyboard for which 7744the change is being reported. 7745</para> 7746 7747 7748<para> 7749If <emphasis> 7750XkbKeyTypesMask</emphasis> 7751 is set in <emphasis> 7752changed</emphasis> 7753, the <emphasis> 7754firstType</emphasis> 7755 and <emphasis> 7756nTypes</emphasis> 7757 fields report a range of key types that includes all changed types. Otherwise, 7758both fields are <emphasis> 77590</emphasis> 7760. 7761</para> 7762 7763 7764<para> 7765If <emphasis> 7766XkbKeySymsMask</emphasis> 7767 is set in <emphasis> 7768changed</emphasis> 7769, the <emphasis> 7770firstKeySym</emphasis> 7771 and <emphasis> 7772nKeySyms</emphasis> 7773 fields report a range of keycodes that includes all keys with new symbols. 7774Otherwise, both fields are <emphasis> 77750</emphasis> 7776. 7777</para> 7778 7779 7780<para> 7781If <emphasis> 7782XkbKeyActionsMask</emphasis> 7783 is set in <emphasis> 7784changed</emphasis> 7785, the <emphasis> 7786firstKeyAction</emphasis> 7787 and <emphasis> 7788nKeyActions</emphasis> 7789 fields report a range of keycodes that includes all keys with new actions. 7790Otherwise, both fields are <emphasis> 77910</emphasis> 7792. 7793</para> 7794 7795 7796<para> 7797If <emphasis> 7798XkbKeyBehaviorsMask</emphasis> 7799 is set in <emphasis> 7800changed</emphasis> 7801, the <emphasis> 7802firstKeyBehavior </emphasis> 7803and <emphasis> 7804nKeyBehaviors</emphasis> 7805 fields report a range of keycodes that includes all keys with new key 7806behavior. Otherwise, both fields are <emphasis> 78070</emphasis> 7808. 7809</para> 7810 7811 7812<para> 7813If <emphasis> 7814XkbVirtualModsMask</emphasis> 7815 is set in <emphasis> 7816changed</emphasis> 7817, <emphasis> 7818virtualMods</emphasis> 7819 contains all virtual modifiers to which a new set of real modifiers is bound. 7820Otherwise, <emphasis> 7821virtualMods</emphasis> 7822 is <emphasis> 78230</emphasis> 7824. 7825</para> 7826 7827 7828<para> 7829If <emphasis> 7830XkbExplicitComponentsMask</emphasis> 7831 is set in <emphasis> 7832changed</emphasis> 7833, the <emphasis> 7834firstKeyExplicit</emphasis> 7835 and <emphasis> 7836nKeyExplicit</emphasis> 7837 fields report a range of keycodes that includes all keys with changed explicit 7838components. Otherwise, both fields are <emphasis> 78390</emphasis> 7840. 7841</para> 7842 7843 7844<para> 7845If <emphasis> 7846XkbModifierMapMask</emphasis> 7847 is set in <emphasis> 7848changed</emphasis> 7849, the <emphasis> 7850firstModMapKey</emphasis> 7851 and <emphasis> 7852nModMapKeys</emphasis> 7853 fields report a range of keycodes that includes all keys with changed modifier 7854bindings. Otherwise, both fields are <emphasis> 78550</emphasis> 7856. 7857</para> 7858 7859 7860<para> 7861If <emphasis> 7862XkbVirtualModMapMask</emphasis> 7863 is set in <emphasis> 7864changed</emphasis> 7865, the <emphasis> 7866firstVModMapKey</emphasis> 7867 and <emphasis> 7868nVModMapKeys</emphasis> 7869 fields report a range of keycodes that includes all keys with changed virtual 7870modifier mappings. Otherwise, both fields are <emphasis> 78710</emphasis> 7872. 7873</para> 7874 7875 7876</sect2> 7877<sect2 id='Tracking_Keyboard_State_Changes'> 7878<title>Tracking Keyboard State Changes</title> 7879 7880 7881<informaltable frame='none' tabstyle='proto'> 7882<?dbfo keep-together="always" ?> 7883<tgroup cols='1' align='left' colsep='0' rowsep='0'> 7884<colspec colname='c1' colwidth='1.0*'/> 7885 <thead> 7886 <row> 7887 <entry role='protoname'>XkbStateNotify</entry> 7888 </row> 7889 </thead> 7890 <tbody> 7891 <row> 7892 <entry role='protoargs'>time: TIMESTAMP</entry> 7893 </row> 7894 <row> 7895 <entry role='protoname'> 7896deviceID: CARD8</entry> 7897 </row> 7898 <row> 7899 <entry role='protoname'> 7900mods, baseMods, latchedMods, lockedMods: KEYMASK</entry> 7901 </row> 7902 <row> 7903 <entry role='protoname'> 7904group, lockedGroup: CARD8</entry> 7905 </row> 7906 <row> 7907 <entry role='protoname'> 7908baseGroup, latchedGroup: INT16</entry> 7909 </row> 7910 <row> 7911 <entry role='protoname'> 7912compatState: KEYMASK</entry> 7913 </row> 7914 <row> 7915 <entry role='protoname'> 7916grabMods, compatGrabMods: KEYMASK</entry> 7917 </row> 7918 <row> 7919 <entry role='protoname'> 7920lookupMods, compatLookupMods: KEYMASK</entry> 7921 </row> 7922 <row> 7923 <entry role='protoname'> 7924ptrBtnState: BUTMASK</entry> 7925 </row> 7926 <row> 7927 <entry role='protoname'> 7928changed: KB_STATEPARTMASK</entry> 7929 </row> 7930 <row> 7931 <entry role='protoname'> 7932keycode: KEYCODE</entry> 7933 </row> 7934 <row> 7935 <entry role='protoname'> 7936eventType: CARD8</entry> 7937 </row> 7938 <row> 7939 <entry role='protoname'> 7940requestMajor, requestMinor: CARD8</entry> 7941 </row> 7942 7943 </tbody> 7944 </tgroup> 7945</informaltable> 7946 7947<para> 7948An <emphasis>XkbStateNotify</emphasis> 7949event reports that some component of the XKB state (see 7950<link linkend='Keyboard_State'>Keyboard State</link>) has changed. 7951State notify events are usually caused by key or pointer activity, but they can 7952also result from explicit state changes requested by the <emphasis> 7953XkbLatchLockState</emphasis> 7954 request or by other extensions. 7955</para> 7956 7957 7958<para> 7959The <emphasis> 7960deviceID</emphasis> 7961 field reports the keyboard on which some state component changed. The 7962<emphasis> 7963changed</emphasis> 7964 field reports the XKB state components (see 7965<link linkend='Keyboard_State'>Keyboard State</link>) that have changed 7966and contain any combination of: 7967</para> 7968 7969<informaltable frame='none'> 7970<?dbfo keep-together="always" ?> 7971<tgroup cols='3' align='left' colsep='0' rowsep='0'> 7972<colspec colname='c1' colwidth='1.0*'/> 7973<colspec colname='c2' colwidth='1.0*'/> 7974<colspec colname='c3' colwidth='2.0*'/> 7975<thead> 7976 <row rowsep='1'> 7977 <entry>Bit in changed</entry> 7978 <entry>Event field</entry> 7979 <entry>Changed component</entry> 7980 </row> 7981</thead> 7982<tbody> 7983 <row> 7984 <entry><emphasis> 7985ModifierState</emphasis> 7986</entry> 7987 <entry><emphasis> 7988mods</emphasis> 7989</entry> 7990 <entry>The effective modifiers</entry> 7991 </row> 7992 <row> 7993 <entry><emphasis> 7994ModifierBase</emphasis> 7995</entry> 7996 <entry><emphasis> 7997baseMods</emphasis> 7998</entry> 7999 <entry>The base modifiers</entry> 8000 </row> 8001 <row> 8002 <entry><emphasis> 8003ModifierLatch</emphasis> 8004</entry> 8005 <entry><emphasis> 8006latchedMods</emphasis> 8007</entry> 8008 <entry>The latched modifiers</entry> 8009 </row> 8010 <row> 8011 <entry><emphasis> 8012ModifierLock</emphasis> 8013</entry> 8014 <entry><emphasis> 8015lockedMods</emphasis> 8016</entry> 8017 <entry>The locked modifiers</entry> 8018 </row> 8019 <row> 8020 <entry><emphasis> 8021GroupState</emphasis> 8022</entry> 8023 <entry><emphasis> 8024group</emphasis> 8025</entry> 8026 <entry>The effective keyboard group</entry> 8027 </row> 8028 <row> 8029 <entry><emphasis> 8030GroupBase</emphasis> 8031</entry> 8032 <entry><emphasis> 8033baseGroup</emphasis> 8034</entry> 8035 <entry>The base keyboard group</entry> 8036 </row> 8037 <row> 8038 <entry><emphasis> 8039GroupLatch</emphasis> 8040</entry> 8041 <entry><emphasis> 8042latchedGroup</emphasis> 8043</entry> 8044 <entry>The latched keyboard group</entry> 8045 </row> 8046 <row> 8047 <entry><emphasis> 8048GroupLock</emphasis> 8049</entry> 8050 <entry><emphasis> 8051lockedGroup</emphasis> 8052</entry> 8053 <entry>The locked keyboard group</entry> 8054 </row> 8055 <row> 8056 <entry><emphasis> 8057PointerButtons</emphasis> 8058</entry> 8059 <entry><emphasis> 8060ptrBtnState</emphasis> 8061</entry> 8062 <entry>The state of the core pointer buttons</entry> 8063 </row> 8064 <row> 8065 <entry><emphasis> 8066GrabMods</emphasis> 8067</entry> 8068 <entry><emphasis> 8069grabMods</emphasis> 8070</entry> 8071 <entry>The XKB state used to compute grabs</entry> 8072 </row> 8073 <row> 8074 <entry><emphasis> 8075LookupMods</emphasis> 8076</entry> 8077 <entry><emphasis> 8078lookupMods</emphasis> 8079</entry> 8080 <entry>The XKB state used to look up symbols</entry> 8081 </row> 8082 <row> 8083 <entry><emphasis> 8084CompatState</emphasis> 8085</entry> 8086 <entry><emphasis> 8087compatState</emphasis> 8088</entry> 8089 <entry>Default state for non-XKB clients</entry> 8090 </row> 8091 <row> 8092 <entry><emphasis> 8093CompatGrabMods</emphasis> 8094</entry> 8095 <entry><emphasis> 8096compatGrabMods</emphasis> 8097</entry> 8098 <entry>The core state used to compute grabs</entry> 8099 </row> 8100 <row> 8101 <entry><emphasis> 8102CompatLookupMods</emphasis> 8103</entry> 8104 <entry><emphasis> 8105compatLookupMods</emphasis> 8106</entry> 8107 <entry>The core state used to look up symbols</entry> 8108 </row> 8109</tbody> 8110</tgroup> 8111</informaltable> 8112 8113<para> 8114The server sends an <emphasis> 8115XkbStateNotify</emphasis> 8116 event to a client only if at least one of the bits that is set in the 8117<emphasis> 8118changed</emphasis> 8119 field of the event is also set in the appropriate event details mask for the 8120client. 8121</para> 8122 8123 8124<para> 8125A state notify event reports current values for all state components, even 8126those with unchanged values. 8127</para> 8128 8129 8130<para> 8131The <emphasis> 8132keycode</emphasis> 8133 field reports the key or button which caused the change in state while the 8134<emphasis> 8135eventType</emphasis> 8136 field reports the exact type of event (e.g. <emphasis> 8137KeyPress</emphasis> 8138). If the change in state was not caused by key or button activity, both fields 8139have the value <emphasis> 81400</emphasis> 8141. 8142</para> 8143 8144 8145<para> 8146The <emphasis> 8147requestMajor</emphasis> 8148 and <emphasis> 8149requestMinor</emphasis> 8150 fields report the major and minor opcodes of the request that caused the 8151change in state and have the value <emphasis> 81520</emphasis> 8153 if it was resulted from key or button activity. 8154</para> 8155 8156 8157</sect2> 8158<sect2 id='Tracking_Keyboard_Control_Changes'> 8159<title>Tracking Keyboard Control Changes</title> 8160 8161 8162<informaltable frame='none' tabstyle='proto'> 8163<?dbfo keep-together="always" ?> 8164<tgroup cols='1' align='left' colsep='0' rowsep='0'> 8165<colspec colname='c1' colwidth='1.0*'/> 8166 <thead> 8167 <row> 8168 <entry role='protoname'>XkbControlsNotify</entry> 8169 </row> 8170 </thead> 8171 <tbody> 8172 <row> 8173 <entry role='protoargs'>time: TIMESTAMP</entry> 8174 </row> 8175 <row> 8176 <entry role='protoname'> 8177deviceID: CARD8</entry> 8178 </row> 8179 <row> 8180 <entry role='protoname'> 8181numGroups: CARD8</entry> 8182 </row> 8183 <row> 8184 <entry role='protoname'> 8185changedControls: KB_CONTROLMASK</entry> 8186 </row> 8187 <row> 8188 <entry role='protoname'> 8189enabledControls,enabledControlChanges: KB_BOOLCTRLMASK</entry> 8190 </row> 8191 <row> 8192 <entry role='protoname'> 8193keycode: KEYCODE</entry> 8194 </row> 8195 <row> 8196 <entry role='protoname'> 8197eventType: CARD8</entry> 8198 </row> 8199 <row> 8200 <entry role='protoname'> 8201requestMajor: CARD8</entry> 8202 </row> 8203 <row> 8204 <entry role='protoname'> 8205requestMinor: CARD8</entry> 8206 </row> 8207 8208 </tbody> 8209 </tgroup> 8210</informaltable> 8211 8212<para> 8213An <emphasis> 8214XkbControlsNotify</emphasis> 8215 event reports a change in one or more of the global keyboard controls (see 8216<link linkend='Global_Keyboard_Controls'>Global Keyboard Controls</link>) 8217or in the internal modifiers or ignore locks masks (see 8218<link linkend='Server_Internal_Modifiers_and_Ignore_Locks_Behavior'> 8219Server Internal Modifiers and Ignore 8220Locks Behavior</link>). Controls notify events are usually caused by and 8221<emphasis> 8222XkbSetControls</emphasis> 8223 request, but they can also be caused by keyboard activity or certain core 8224protocol and input extension requests. 8225</para> 8226 8227 8228<para> 8229The <emphasis> 8230deviceID</emphasis> 8231 field reports the keyboard for which some control has changed, and the 8232<emphasis> 8233changed</emphasis> 8234 field reports the controls that have new values. 8235</para> 8236 8237 8238<para> 8239The <emphasis> 8240changed</emphasis> 8241 field can contain any of the values that are permitted for the <emphasis> 8242changeControls</emphasis> 8243 field of the <emphasis> 8244XkbSetControls</emphasis> 8245 request. The server sends an <emphasis> 8246XkbControlsNotify</emphasis> 8247 event to a client only if at least one of the bits that is set in the 8248<emphasis> 8249changed</emphasis> 8250 field of the event is also set in the appropriate event details mask for the 8251client. 8252</para> 8253 8254 8255<para> 8256The <emphasis> 8257numGroups</emphasis> 8258 field reports the total number of groups defined for the keyboard, whether or 8259not the number of groups has changed. 8260</para> 8261 8262 8263<para> 8264The <emphasis> 8265enabledControls</emphasis> 8266 field reports the current status of all of the boolean controls, whether or 8267not any boolean controls changed state. If <emphasis> 8268EnabledControls</emphasis> 8269 is set in <emphasis> 8270changed</emphasis> 8271, the <emphasis> 8272enabledControlChanges</emphasis> 8273 field reports the boolean controls that were enabled or disabled; if a control 8274is specified in <emphasis> 8275enabledControlChanges</emphasis> 8276, the value that is reported for that control in <emphasis> 8277enabledControls</emphasis> 8278 represents a change in state. 8279</para> 8280 8281 8282<para> 8283The <emphasis> 8284keycode</emphasis> 8285 field reports the key or button which caused the change in state while the 8286<emphasis> 8287eventType</emphasis> 8288 field reports the exact type of event (e.g. <emphasis> 8289KeyPress</emphasis> 8290). If the change in state was not caused by key or button activity, both fields 8291have the value <emphasis> 82920</emphasis> 8293. 8294</para> 8295 8296 8297<para> 8298The <emphasis> 8299requestMajor</emphasis> 8300 and <emphasis> 8301requestMinor</emphasis> 8302 fields report the major and minor opcodes of the request that caused the 8303change in state and have the value <emphasis> 83040</emphasis> 8305 if it was resulted from key or button activity. 8306</para> 8307 8308 8309</sect2> 8310<sect2 id='Tracking_Keyboard_Indicator_State_Changes'> 8311<title>Tracking Keyboard Indicator State Changes</title> 8312 8313 8314<informaltable frame='none' tabstyle='proto'> 8315<?dbfo keep-together="always" ?> 8316<tgroup cols='1' align='left' colsep='0' rowsep='0'> 8317<colspec colname='c1' colwidth='1.0*'/> 8318 <thead> 8319 <row> 8320 <entry role='protoname'>XkbIndicatorStateNotify</entry> 8321 </row> 8322 </thead> 8323 <tbody> 8324 <row> 8325 <entry role='protoargs'>time: TIMESTAMP</entry> 8326 </row> 8327 <row> 8328 <entry role='protoname'> 8329deviceID: CARD8</entry> 8330 </row> 8331 <row> 8332 <entry role='protoname'> 8333stateChanged, state: KB_INDICATORMASK</entry> 8334 </row> 8335 8336 </tbody> 8337 </tgroup> 8338</informaltable> 8339 8340<para> 8341An <emphasis> 8342XkbIndicatorStateNotify</emphasis> 8343 event indicates that one or more of the indicators on a keyboard have changed 8344state. Indicator state notify events can be caused by: 8345</para> 8346 8347<itemizedlist> 8348<listitem> 8349 <para>Automatic update to reflect changes in keyboard state (keyboard 8350activity, <emphasis> 8351XkbLatchLockState</emphasis> 8352 requests). 8353 </para> 8354</listitem> 8355<listitem> 8356 <para>Automatic update to reflect changes in keyboard controls (<emphasis> 8357XkbSetControls</emphasis> 8358, keyboard activity, certain core protocol and input extension requests). 8359 </para> 8360</listitem> 8361<listitem> 8362 <para>Explicit attempts to change indicator state (core protocol and input 8363extension requests, <emphasis> 8364XkbSetNamedIndicator</emphasis> 8365 requests). 8366 </para> 8367</listitem> 8368<listitem> 8369 <para>Changes to indicator maps (<emphasis> 8370XkbSetIndicatorMap</emphasis> 8371 and <emphasis> 8372XkbSetNamedIndicator</emphasis> 8373 requests). 8374 </para> 8375</listitem> 8376</itemizedlist> 8377 8378<para> 8379The <emphasis> 8380deviceID</emphasis> 8381 field reports the keyboard for which some indicator has changed, and the 8382<emphasis> 8383state</emphasis> 8384 field reports the new state for all indicators on the specified keyboard. The 8385<emphasis> 8386stateChanged</emphasis> 8387 field specifies which of the values in <emphasis> 8388state</emphasis> 8389 represent a new state for the corresponding indicator. The server sends an 8390<emphasis> 8391XkbIndicatorStateNotify</emphasis> 8392 event to a client only if at least one of the bits that is set in the 8393<emphasis> 8394stateChanged</emphasis> 8395 field of the event is also set in the appropriate event details mask for the 8396client. 8397</para> 8398 8399 8400</sect2> 8401<sect2 id='Tracking_Keyboard_Indicator_Map_Changes'> 8402<title>Tracking Keyboard Indicator Map Changes</title> 8403 8404 8405<informaltable frame='none' tabstyle='proto'> 8406<?dbfo keep-together="always" ?> 8407<tgroup cols='1' align='left' colsep='0' rowsep='0'> 8408<colspec colname='c1' colwidth='1.0*'/> 8409 <thead> 8410 <row> 8411 <entry role='protoname'>XkbIndicatorMapNotify</entry> 8412 </row> 8413 </thead> 8414 <tbody> 8415 <row> 8416 <entry role='protoargs'>time: TIMESTAMP</entry> 8417 </row> 8418 <row> 8419 <entry role='protoname'> 8420deviceID: CARD8</entry> 8421 </row> 8422 <row> 8423 <entry role='protoname'> 8424state: KB_INDICATORMASK</entry> 8425 </row> 8426 <row> 8427 <entry role='protoname'> 8428mapChanged: KB_INDICATORMASK</entry> 8429 </row> 8430 8431 </tbody> 8432 </tgroup> 8433</informaltable> 8434 8435<para> 8436An <emphasis> 8437XkbIndicatorMapNotify</emphasis> 8438 event indicates that the maps for one or more keyboard indicators have been 8439changed. Indicator map notify events can be caused by <emphasis> 8440XkbSetIndicatorMap</emphasis> 8441 and <emphasis> 8442XkbSetNamedIndicator</emphasis> 8443 requests. 8444</para> 8445 8446 8447<para> 8448The <emphasis> 8449deviceID</emphasis> 8450 field reports the keyboard for which some indicator map has changed, and the 8451<emphasis> 8452mapChanged</emphasis> 8453 field reports the indicators with changed maps. The server sends an <emphasis> 8454XkbIndicatorMapNotify</emphasis> 8455 event to a client only if at least one of the bits that is set in the 8456<emphasis> 8457mapChanged</emphasis> 8458 field of the event is also set in the appropriate event details mask for the 8459client. 8460</para> 8461 8462 8463<para> 8464The <emphasis> 8465state</emphasis> 8466 field reports the current state of all indicators on the specified keyboard. 8467</para> 8468 8469 8470</sect2> 8471<sect2 id='Tracking_Keyboard_Name_Changes'> 8472<title>Tracking Keyboard Name Changes</title> 8473 8474 8475<informaltable frame='none' tabstyle='proto'> 8476<?dbfo keep-together="always" ?> 8477<tgroup cols='1' align='left' colsep='0' rowsep='0'> 8478<colspec colname='c1' colwidth='1.0*'/> 8479 <thead> 8480 <row> 8481 <entry role='protoname'>XkbNamesNotify</entry> 8482 </row> 8483 </thead> 8484 <tbody> 8485 <row> 8486 <entry role='protoargs'>time: TIMESTAMP</entry> 8487 </row> 8488 <row> 8489 <entry role='protoname'> 8490deviceID: CARD8</entry> 8491 </row> 8492 <row> 8493 <entry role='protoname'> 8494changed: KB_NAMEDETAILMASK</entry> 8495 </row> 8496 <row> 8497 <entry role='protoname'> 8498firstType, nTypes: CARD8</entry> 8499 </row> 8500 <row> 8501 <entry role='protoname'> 8502firstLevelName, nLevelNames: CARD8</entry> 8503 </row> 8504 <row> 8505 <entry role='protoname'> 8506firstKey: KEYCODE</entry> 8507 </row> 8508 <row> 8509 <entry role='protoname'> 8510nKeys, nKeyAliases, nRadioGroups: CARD8</entry> 8511 </row> 8512 <row> 8513 <entry role='protoname'> 8514changedGroupNames: KB_GROUPMASK</entry> 8515 </row> 8516 <row> 8517 <entry role='protoname'> 8518changedVirtualMods: KB_VMODMASK</entry> 8519 </row> 8520 <row> 8521 <entry role='protoname'> 8522changedIndicators: KB_INDICATORMASK</entry> 8523 </row> 8524 8525 </tbody> 8526 </tgroup> 8527</informaltable> 8528 8529<para> 8530An <emphasis> 8531XkbNamesNotify</emphasis> 8532 event reports a change to one or more of the symbolic names associated with a 8533keyboard. Symbolic names can change when: 8534</para> 8535 8536<itemizedlist> 8537<listitem> 8538 <para> Some client explicitly changes them using <emphasis> 8539XkbSetNames</emphasis> 8540. 8541 </para> 8542</listitem> 8543<listitem> 8544 <para>The list of key types or radio groups is resized 8545 </para> 8546</listitem> 8547<listitem> 8548 <para>The group width of some key type is changed 8549 </para> 8550</listitem> 8551</itemizedlist> 8552 8553<para> 8554The <emphasis> 8555deviceID</emphasis> 8556 field reports the keyboard on which names were changed. The <emphasis> 8557changed</emphasis> 8558 mask lists the components for which some names have changed and can have any 8559combination of the values permitted for the <emphasis> 8560which</emphasis> 8561 field of the <emphasis> 8562XkbGetNames</emphasis> 8563 request. The server sends an <emphasis> 8564XkbNamesNotify</emphasis> 8565 event to a client only if at least one of the bits that is set in the 8566<emphasis> 8567changed</emphasis> 8568 field of the event is also set in the appropriate event details mask for the 8569client. 8570</para> 8571 8572 8573<para> 8574If <emphasis> 8575KeyTypeNames</emphasis> 8576 is set in <emphasis> 8577changed</emphasis> 8578, the <emphasis> 8579firstType</emphasis> 8580 and <emphasis> 8581nTypes</emphasis> 8582 fields report a range of types that includes all types with changed names. 8583Otherwise, both fields are <emphasis> 85840</emphasis> 8585. 8586</para> 8587 8588 8589<para> 8590If <emphasis> 8591KTLevelNames</emphasis> 8592 is set in <emphasis> 8593changed</emphasis> 8594, the <emphasis> 8595firstLevelName</emphasis> 8596 and <emphasis> 8597nLevelNames</emphasis> 8598 fields report a range of types that includes all types with changed level 8599names. Otherwise, both fields are <emphasis> 86000</emphasis> 8601. 8602</para> 8603 8604 8605<para> 8606If <emphasis> 8607IndicatorNames</emphasis> 8608 is set in <emphasis> 8609changed</emphasis> 8610, the <emphasis> 8611changedIndicators</emphasis> 8612 field reports the indicators with changed names. Otherwise, <emphasis> 8613changedIndicators</emphasis> 8614 is <emphasis> 86150</emphasis> 8616. 8617</para> 8618 8619 8620<para> 8621If <emphasis> 8622VirtualModNames</emphasis> 8623 is set in <emphasis> 8624changed</emphasis> 8625, the <emphasis> 8626changedVirtualMods</emphasis> 8627 field reports the virtual modifiers with changed names. Otherwise, <emphasis> 8628changedVirtualMods</emphasis> 8629 is <emphasis> 86300</emphasis> 8631. 8632</para> 8633 8634 8635<para> 8636If <emphasis> 8637GroupNames</emphasis> 8638 is set in <emphasis> 8639changed</emphasis> 8640, the <emphasis> 8641changedGroupNames</emphasis> 8642 field reports the groups with changed names. Otherwise, <emphasis> 8643changedGroupNames</emphasis> 8644 is <emphasis> 86450</emphasis> 8646. 8647</para> 8648 8649 8650<para> 8651If <emphasis> 8652KeyNames</emphasis> 8653 is set in <emphasis> 8654changed</emphasis> 8655, the <emphasis> 8656firstKey</emphasis> 8657 and <emphasis> 8658nKeys</emphasis> 8659 fields report a range of keycodes that includes all keys with changed names. 8660Otherwise, both fields are <emphasis> 86610</emphasis> 8662. 8663</para> 8664 8665 8666<para> 8667The <emphasis> 8668nKeyAliases</emphasis> 8669 field reports the total number of key aliases associated with the keyboard, 8670regardless of whether <emphasis> 8671KeyAliases</emphasis> 8672 is set in <emphasis> 8673changed</emphasis> 8674. 8675</para> 8676 8677 8678<para> 8679The <emphasis> 8680nRadioGroups</emphasis> 8681 field reports the total number of radio group names associated with the 8682keyboard, regardless of whether <emphasis> 8683RGNames</emphasis> 8684 is set in <emphasis> 8685changed</emphasis> 8686. 8687</para> 8688 8689 8690</sect2> 8691<sect2 id='Tracking_Compatibility_Map_Changes'> 8692<title>Tracking Compatibility Map Changes</title> 8693 8694 8695<informaltable frame='none' tabstyle='proto'> 8696<?dbfo keep-together="always" ?> 8697<tgroup cols='1' align='left' colsep='0' rowsep='0'> 8698<colspec colname='c1' colwidth='1.0*'/> 8699 <thead> 8700 <row> 8701 <entry role='protoname'>XkbCompatMapNotify</entry> 8702 </row> 8703 </thead> 8704 <tbody> 8705 <row> 8706 <entry role='protoargs'>time: TIMESTAMP</entry> 8707 </row> 8708 <row> 8709 <entry role='protoname'> 8710deviceID: CARD8</entry> 8711 </row> 8712 <row> 8713 <entry role='protoname'> 8714changedGroups: KB_GROUPMASK</entry> 8715 </row> 8716 <row> 8717 <entry role='protoname'> 8718firstSI, nSI: CARD16</entry> 8719 </row> 8720 <row> 8721 <entry role='protoname'> 8722nTotalSI: CARD16</entry> 8723 </row> 8724 8725 </tbody> 8726 </tgroup> 8727</informaltable> 8728 8729<para> 8730An <emphasis> 8731XkbCompatMapNotify</emphasis> 8732 event indicates that some component of the compatibility map for a keyboard 8733has been changed. Compatibility map notify events can be caused by <emphasis> 8734XkbSetCompatMap</emphasis> 8735 and <emphasis> 8736XkbGetMapByName</emphasis> 8737 requests. 8738</para> 8739 8740 8741<para> 8742The <emphasis> 8743deviceID</emphasis> 8744 field reports the keyboard for which the compatibility map has changed; if the 8745server does not support the X input extension, <emphasis> 8746deviceID</emphasis> 8747 is <emphasis> 87480</emphasis> 8749. 8750</para> 8751 8752 8753<para> 8754The <emphasis> 8755changedGroups</emphasis> 8756 field reports the keyboard groups, if any, with a changed entry in the group 8757compatibility map. The <emphasis> 8758firstSI</emphasis> 8759 and <emphasis> 8760nSI</emphasis> 8761 fields specify a range of symbol interpretations in the symbol compatibility 8762map that includes all changed symbol interpretations; if the symbol 8763compatibility map is unchanged, both fields are <emphasis> 87640</emphasis> 8765. The <emphasis> 8766nTotalSI</emphasis> 8767 field always reports the total number of symbol interpretations present in the 8768symbol compatibility map, regardless of whether any symbol interpretations have 8769been changed. 8770</para> 8771 8772 8773<para> 8774The server sends an <emphasis> 8775XkbCompatMapNotify</emphasis> 8776 event to a client only if at least one of the following conditions is met: 8777</para> 8778 8779<itemizedlist> 8780<listitem> 8781 <para>The <emphasis> 8782nSI</emphasis> 8783 field of the event is non-zero, and the <emphasis> 8784XkbSymInterpMask</emphasis> 8785 bit is set in the appropriate event details mask for the client. 8786 </para> 8787</listitem> 8788<listitem> 8789 <para>The <emphasis> 8790changedGroups</emphasis> 8791 field of the event contains at least one group, and the <emphasis> 8792XkbGroupCompatMask</emphasis> 8793 bit is set in the appropriate event details mask for the client. 8794 </para> 8795</listitem> 8796</itemizedlist> 8797 8798</sect2> 8799<sect2 id='Tracking_Application_Bell_Requests'> 8800<title>Tracking Application Bell Requests</title> 8801 8802 8803<informaltable frame='none' tabstyle='proto'> 8804<?dbfo keep-together="always" ?> 8805<tgroup cols='1' align='left' colsep='0' rowsep='0'> 8806<colspec colname='c1' colwidth='1.0*'/> 8807 <thead> 8808 <row> 8809 <entry role='protoname'>XkbBellNotify</entry> 8810 </row> 8811 </thead> 8812 <tbody> 8813 <row> 8814 <entry role='protoargs'>time: TIMESTAMP</entry> 8815 </row> 8816 <row> 8817 <entry role='protoname'> 8818deviceID: CARD8</entry> 8819 </row> 8820 <row> 8821 <entry role='protoname'> 8822bellClass: { KbdFeedbackClass, BellFeedbackClass }</entry> 8823 </row> 8824 <row> 8825 <entry role='protoname'> 8826bellID: CARD8</entry> 8827 </row> 8828 <row> 8829 <entry role='protoname'> 8830percent: CARD8</entry> 8831 </row> 8832 <row> 8833 <entry role='protoname'> 8834pitch: CARD16</entry> 8835 </row> 8836 <row> 8837 <entry role='protoname'> 8838duration: CARD16</entry> 8839 </row> 8840 <row> 8841 <entry role='protoname'> 8842eventOnly: BOOL</entry> 8843 </row> 8844 <row> 8845 <entry role='protoname'> 8846name: ATOM</entry> 8847 </row> 8848 <row> 8849 <entry role='protoname'> 8850window: WINDOW</entry> 8851 </row> 8852 8853 </tbody> 8854 </tgroup> 8855</informaltable> 8856 8857<para> 8858An <emphasis> 8859XkbBellNotify</emphasis> 8860 event indicates that some client has requested a keyboard bell. Bell notify 8861events are usually caused by <emphasis> 8862Bell</emphasis> 8863, <emphasis> 8864DeviceBell</emphasis> 8865, or <emphasis> 8866XkbBell</emphasis> 8867 requests, but they can also be generated by the server (e.g. if the <emphasis> 8868AccessXFeedback</emphasis> 8869 control is active). 8870</para> 8871 8872 8873<para> 8874The server sends an <emphasis> 8875XkbBellNotify</emphasis> 8876 event to a client if the appropriate event details field for the client has 8877the value <emphasis> 8878True</emphasis> 8879. 8880</para> 8881 8882 8883<para> 8884The <emphasis> 8885deviceID</emphasis> 8886 field specifies the device for which a bell was requested, while the <emphasis> 8887bellClass</emphasis> 8888 and <emphasis> 8889bellID</emphasis> 8890 fields specify the input extension class and identifier of the feedback for 8891which the bell was requested. If the reporting server does not support the 8892input extension, all three fields have the value 0. 8893</para> 8894 8895 8896<para> 8897The <emphasis> 8898percent</emphasis> 8899, <emphasis> 8900pitch</emphasis> 8901 and <emphasis> 8902duration</emphasis> 8903 fields report the volume, tone and duration requested for the bell as 8904specified by the <emphasis> 8905XkbBell</emphasis> 8906 request. Bell notify events caused by core protocol or input extension 8907requests use the pitch and duration specified in the corresponding bell or 8908keyboard feedback control. 8909</para> 8910 8911 8912<para> 8913If the bell was caused by an <emphasis> 8914XkbBell</emphasis> 8915 request or by the X server, <emphasis> 8916name</emphasis> 8917 reports an optional symbolic name for the bell and the <emphasis> 8918window</emphasis> 8919 field optionally reports the window for which the bell was generated. 8920Otherwise, both fields have the value <emphasis> 8921None</emphasis> 8922. 8923</para> 8924 8925 8926<para> 8927If the <emphasis> 8928eventOnly</emphasis> 8929 field is <emphasis> 8930True</emphasis> 8931, the server did not generate a sound in response to the request, otherwise the 8932server issues the beep before sending the event. The eventOnly field can be 8933<emphasis> 8934True</emphasis> 8935 if the <emphasis> 8936AudibleBell</emphasis> 8937 control is disabled or if a client explicitly requests <emphasis> 8938eventOnly</emphasis> 8939 when it issues an <emphasis> 8940XkbBell</emphasis> 8941 request. 8942</para> 8943 8944 8945</sect2> 8946<sect2 id='Tracking_Messages_Generated_by_Key_Actions'> 8947<title>Tracking Messages Generated by Key Actions</title> 8948 8949 8950<informaltable frame='none' tabstyle='proto'> 8951<?dbfo keep-together="always" ?> 8952<tgroup cols='1' align='left' colsep='0' rowsep='0'> 8953<colspec colname='c1' colwidth='1.0*'/> 8954 <thead> 8955 <row> 8956 <entry role='protoname'>XkbActionMessage</entry> 8957 </row> 8958 </thead> 8959 <tbody> 8960 <row> 8961 <entry role='protoargs'>time: TIMESTAMP</entry> 8962 </row> 8963 <row> 8964 <entry role='protoname'> 8965deviceID: CARD8</entry> 8966 </row> 8967 <row> 8968 <entry role='protoname'> 8969keycode: KEYCODE</entry> 8970 </row> 8971 <row> 8972 <entry role='protoname'> 8973press: BOOL</entry> 8974 </row> 8975 <row> 8976 <entry role='protoname'> 8977mods: KEYMASK</entry> 8978 </row> 8979 <row> 8980 <entry role='protoname'> 8981group: KB_GROUP</entry> 8982 </row> 8983 <row> 8984 <entry role='protoname'> 8985keyEventFollows: BOOL</entry> 8986 </row> 8987 <row> 8988 <entry role='protoname'> 8989message: LISTofCARD8</entry> 8990 </row> 8991 8992 </tbody> 8993 </tgroup> 8994</informaltable> 8995 8996<para> 8997An <emphasis> 8998XkbActionMessage</emphasis> 8999 event is generated when the user operates a key to which an <emphasis> 9000SA_ActionMessage</emphasis> 9001 message is bound under the appropriate state and group. The server sends an 9002<emphasis> 9003XkbActionMessage</emphasis> 9004 event to a client if the appropriate event details field for the client has 9005the value <emphasis> 9006True</emphasis> 9007. 9008</para> 9009 9010 9011<para> 9012The <emphasis> 9013deviceID</emphasis> 9014 field specifies the keyboard device that contains the key which activated the 9015event. The <emphasis> 9016keycode</emphasis> 9017 field specifies the key whose operation caused the message and press is 9018<emphasis> 9019True</emphasis> 9020 if the message was caused by the user pressing the key. The <emphasis> 9021mods</emphasis> 9022 and <emphasis> 9023group</emphasis> 9024 fields report the effective keyboard modifiers and group in effect at the time 9025the key was pressed or released. 9026</para> 9027 9028 9029<para> 9030If <emphasis> 9031keyEventFollows</emphasis> 9032 is <emphasis> 9033True</emphasis> 9034, the server will also send a key press or release event, as appropriate, for 9035the key that generated the message. If it is <emphasis> 9036False</emphasis> 9037, the key causes only a message. Note that the key event is delivered normally 9038with respect to passive grabs, keyboard focus, and cursor position, so that 9039<emphasis> 9040keyEventFollows</emphasis> 9041 does not guarantee that any particular client which receives the <emphasis> 9042XkbActionMessage</emphasis> 9043 notify event will also receive a key press or release event. 9044</para> 9045 9046 9047<para> 9048The <emphasis> 9049message</emphasis> 9050 field is <emphasis> 9051NULL</emphasis> 9052-terminated string of up to <emphasis> 9053ActionMessageLength</emphasis> 9054 (<emphasis> 90556</emphasis> 9056) bytes, which reports the contents of the <emphasis> 9057message</emphasis> 9058 field in the action that caused the message notify event. 9059</para> 9060 9061 9062</sect2> 9063<sect2 id='Tracking_Changes_to_AccessX_State_and_Keys'> 9064<title>Tracking Changes to AccessX State and Keys</title> 9065 9066 9067<informaltable frame='none' tabstyle='proto'> 9068<?dbfo keep-together="always" ?> 9069<tgroup cols='1' align='left' colsep='0' rowsep='0'> 9070<colspec colname='c1' colwidth='1.0*'/> 9071 <thead> 9072 <row> 9073 <entry role='protoname'>XkbAccessXNotify</entry> 9074 </row> 9075 </thead> 9076 <tbody> 9077 <row> 9078 <entry role='protoargs'>time: TIMESTAMP</entry> 9079 </row> 9080 <row> 9081 <entry role='protoname'> 9082deviceID: CARD8</entry> 9083 </row> 9084 <row> 9085 <entry role='protoname'> 9086detail: KB_AXNDETAILMASK</entry> 9087 </row> 9088 <row> 9089 <entry role='protoname'> 9090keycode: KEYCODE</entry> 9091 </row> 9092 <row> 9093 <entry role='protoname'> 9094slowKeysDelay: CARD16</entry> 9095 </row> 9096 <row> 9097 <entry role='protoname'> 9098debounceDelay: CARD16</entry> 9099 </row> 9100 9101 </tbody> 9102 </tgroup> 9103</informaltable> 9104 9105<para> 9106An <emphasis> 9107XkbAccessXNotify</emphasis> 9108 event reports on some kinds of keyboard activity when any of the <emphasis> 9109SlowKeys</emphasis> 9110, <emphasis> 9111BounceKeys</emphasis> 9112 or <emphasis> 9113AccessXKeys</emphasis> 9114 controls are active. Compatibility map notify events can only be caused by 9115keyboard activity. 9116</para> 9117 9118 9119<para> 9120The <emphasis> 9121deviceID</emphasis> 9122 and <emphasis> 9123keycode</emphasis> 9124 fields specify the keyboard and key for which the event occurred. The 9125<emphasis> 9126detail</emphasis> 9127 field describes the event that occurred and has one of the following values: 9128</para> 9129 9130<informaltable frame='topbot'> 9131<?dbfo keep-together="always" ?> 9132<tgroup cols='3' align='left' colsep='0' rowsep='0'> 9133<colspec colname='c1' colwidth='1.0*'/> 9134<colspec colname='c2' colwidth='1.0*'/> 9135<colspec colname='c3' colwidth='2.0*'/> 9136<thead> 9137 <row rowsep='1'> 9138 <entry>Detail</entry> 9139 <entry>Control</entry> 9140 <entry>Meaning</entry> 9141 </row> 9142</thead> 9143<tbody> 9144 <row> 9145 <entry><emphasis> 9146AXN_SKPress</emphasis> 9147</entry> 9148 <entry><emphasis> 9149SlowKeys</emphasis> 9150</entry> 9151 <entry>Key pressed</entry> 9152 </row> 9153 <row> 9154 <entry><emphasis> 9155AXN_SKAccept</emphasis> 9156</entry> 9157 <entry><emphasis> 9158SlowKeys</emphasis> 9159</entry> 9160 <entry><emphasis> 9161K</emphasis> 9162ey held until it was accepted.</entry> 9163 </row> 9164 <row> 9165 <entry><emphasis> 9166AXN_SKReject</emphasis> 9167</entry> 9168 <entry><emphasis> 9169SlowKeys</emphasis> 9170</entry> 9171 <entry>Key released before it was accepted.</entry> 9172 </row> 9173 <row> 9174 <entry><emphasis> 9175AXN_SKRelease</emphasis> 9176</entry> 9177 <entry><emphasis> 9178SlowKeys</emphasis> 9179</entry> 9180 <entry>Key released after it was accepted.</entry> 9181 </row> 9182 <row> 9183 <entry><emphasis> 9184AXN_BKAccept</emphasis> 9185</entry> 9186 <entry><emphasis> 9187BounceKeys</emphasis> 9188</entry> 9189 <entry>Key pressed while it was active.</entry> 9190 </row> 9191 <row> 9192 <entry><emphasis> 9193AXN_BKReject</emphasis> 9194</entry> 9195 <entry><emphasis> 9196BounceKeys</emphasis> 9197</entry> 9198 <entry>Key pressed while it was still disabled.</entry> 9199 </row> 9200 <row> 9201 <entry><emphasis> 9202AXN_AXKWarning</emphasis> 9203</entry> 9204 <entry><emphasis> 9205AccessXKeys</emphasis> 9206</entry> 9207 <entry>Shift key held down for four seconds</entry> 9208 </row> 9209</tbody> 9210</tgroup> 9211</informaltable> 9212 9213<para> 9214Each subclass of the AccessX notify event is generated only when the control 9215specified in the table above is enabled. The server sends an <emphasis> 9216XkbAccessXNotify</emphasis> 9217 event to a client only if the bit which corresponds to the value of the 9218<emphasis> 9219detail</emphasis> 9220 field for the event is set in the appropriate event details mask for the 9221client. 9222</para> 9223 9224 9225<para> 9226Regardless of the value of <emphasis> 9227detail</emphasis> 9228, the <emphasis> 9229slowKeysDelay</emphasis> 9230 and <emphasis> 9231debounceDelay</emphasis> 9232 fields always reports the current slow keys acceptance delay (see 9233<link linkend='The_SlowKeys_Control'>The SlowKeys Control</link>) and 9234debounce delay (see <link linkend='The_BounceKeys_Control'>The BounceKeys 9235Control</link>) for the specified keyboard. 9236</para> 9237 9238 9239</sect2> 9240<sect2 id='Tracking_Changes_To_Extension_Devices'> 9241<title>Tracking Changes To Extension Devices</title> 9242 9243 9244<informaltable frame='none' tabstyle='proto'> 9245<?dbfo keep-together="always" ?> 9246<tgroup cols='1' align='left' colsep='0' rowsep='0'> 9247<colspec colname='c1' colwidth='1.0*'/> 9248 <thead> 9249 <row> 9250 <entry role='protoname'>XkbExtensionDeviceNotify</entry> 9251 </row> 9252 </thead> 9253 <tbody> 9254 <row> 9255 <entry role='protoargs'>time: TIMESTAMP</entry> 9256 </row> 9257 <row> 9258 <entry role='protoname'> 9259deviceID: CARD16</entry> 9260 </row> 9261 <row> 9262 <entry role='protoname'> 9263ledClass: { KbdFeedbackClass, LedFeedbackClass }</entry> 9264 </row> 9265 <row> 9266 <entry role='protoname'> 9267ledID: CARD16</entry> 9268 </row> 9269 <row> 9270 <entry role='protoname'> 9271reason: KB_XIDETAILMASK</entry> 9272 </row> 9273 <row> 9274 <entry role='protoname'> 9275supported: KB_XIFEATUREMASK</entry> 9276 </row> 9277 <row> 9278 <entry role='protoname'> 9279unsupported: KB_XIFEATUREMASK</entry> 9280 </row> 9281 <row> 9282 <entry role='protoname'> 9283ledsDefined: KB_INDICATORMASK</entry> 9284 </row> 9285 <row> 9286 <entry role='protoname'> 9287ledState: KB_INDICATORMASK</entry> 9288 </row> 9289 <row> 9290 <entry role='protoname'> 9291firstButton, nButtons: CARD8</entry> 9292 </row> 9293 9294 </tbody> 9295 </tgroup> 9296</informaltable> 9297 9298<para> 9299An <emphasis> 9300XkbExtensionDeviceNotify</emphasis> 9301 event reports: 9302</para> 9303 9304<itemizedlist> 9305<listitem> 9306 <para>A change to some part of the XKB information for an extension device. 9307 </para> 9308</listitem> 9309<listitem> 9310 <para>An attempt to use an XKB extension device feature that is not supported 9311for the specified device by the current implementation. 9312 </para> 9313</listitem> 9314</itemizedlist> 9315 9316<para> 9317The <emphasis> 9318deviceID</emphasis> 9319 field specifies the X Input Extension device identifier of some device on 9320which an XKB feature was requested, or <emphasis> 9321XkbUseCorePtr</emphasis> 9322 if the request affected the core pointer device. The <emphasis> 9323reason</emphasis> 9324 field explains why the event was generated in response to the request, and can 9325contain any combination of <emphasis> 9326XkbXI_UnsupportedFeature</emphasis> 9327 and the values permitted for the change field of the <emphasis> 9328XkbSetDeviceInfo</emphasis> 9329 request. 9330</para> 9331 9332 9333<para> 9334If <emphasis> 9335XkbXI_ButtonActions</emphasis> 9336 is set in <emphasis> 9337reason</emphasis> 9338, this event reports a successful change to the XKB actions bound to one or 9339more buttons on the core pointer or an extension device. The <emphasis> 9340firstButton</emphasis> 9341 and <emphasis> 9342nButtons</emphasis> 9343 fields report a range of device buttons that include all of the buttons for 9344which actions were changed. 9345</para> 9346 9347 9348<para> 9349If any combination of <emphasis> 9350XkbXI_IndicatorNames</emphasis> 9351, <emphasis> 9352XkbXI_IndicatorMaps</emphasis> 9353, or <emphasis> 9354XkbXI_IndicatorState</emphasis> 9355 is set in either <emphasis> 9356reason</emphasis> 9357 or <emphasis> 9358unsupported</emphasis> 9359, the <emphasis> 9360ledClass</emphasis> 9361 and <emphasis> 9362ledID</emphasis> 9363 fields specify the X Input Extension feedback class and identifier of the 9364feedback for which the change is reported. If this event reports any changes to 9365an indicator feedback, the <emphasis> 9366ledsDefined</emphasis> 9367 field reports all indicators on that feedback for which either a name or a 9368indicator map are defined, and <emphasis> 9369ledState</emphasis> 9370 reports the current state of all of the indicators on the specified feedback. 9371</para> 9372 9373 9374<para> 9375If <emphasis> 9376XkbXI_IndicatorNames</emphasis> 9377 is set in <emphasis> 9378reason</emphasis> 9379, this event reports a successful change to the symbolic names bound to one or 9380more extension device indicators by XKB. If <emphasis> 9381XkbXI_IndicatorMaps</emphasis> 9382 is set in <emphasis> 9383reason</emphasis> 9384, this event reports a successful change to the indicator maps bound to one or 9385more extension device indicators by XKB. If <emphasis> 9386XkbXI_IndicatorState</emphasis> 9387 is set in reason, this event reports that one or more indicators in the 9388specified device and feedback have changed state. 9389</para> 9390 9391 9392<para> 9393If <emphasis> 9394XkbXI_UnsupportedFeature</emphasis> 9395 is set in reason, this event reports an unsuccessful attempt to use some XKB 9396extension device feature that is not supported by the XKB implementation in the 9397server for the specified device. The <emphasis> 9398unsupported</emphasis> 9399 mask reports the requested features that are not available on the specified 9400device. See <link linkend='Interactions_Between_XKB_and_the_X_Input_Extension'>Interactions Between 9401XKB and the X Input Extension</link> for more information about possible XKB 9402interactions with the X Input Extension. 9403</para> 9404 9405 9406<para> 9407The server sends an <emphasis> 9408XkbExtensionDeviceNotify</emphasis> 9409 event to a client only if at least one of the bits that is set in the 9410<emphasis> 9411reason</emphasis> 9412 field of the event is also set in the appropriate event details mask for the 9413client. 9414</para> 9415 9416 9417<para> 9418Events that report a successful change to some extension device feature are 9419reported to all clients that have expressed interest in the event; events that 9420report an attempt to use an unsupported feature are reported only to the client 9421which issued the request. Events which report a partial success are reported to 9422all interested clients, but only the client that issued the request is informed 9423of the attempt to use unsupported features. 9424</para> 9425</sect2> 9426</sect1> 9427</chapter> 9428