specs/ch16.xml

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