specs/XKB/ch08.xml

   1 <chapter id='Indicators'>
   2 <title>Indicators</title>
   3
   4 <para>
   5 Although the core X implementation supports up to 32 LEDs on an input device,
   6 it does not provide any linkage between the state of the LEDs and the logical
   7 state of the input device. For example, most keyboards have a <emphasis>
   8 CapsLock</emphasis>
   9  LED, but X does not provide a mechanism to make the LED automatically follow
  10 the logical state of the <emphasis>
  11 CapsLock</emphasis>
  12  key.
  13 </para>
  14
  15
  16 <para>
  17 Furthermore, the core X implementation does not provide clients with the
  18 ability to determine what bits in the <emphasis>
  19 led_mask</emphasis>
  20  field of the <emphasis>
  21 XKeyboardState</emphasis>
  22  map to the particular LEDs on the keyboard. For example, X does not provide a
  23 method for a client to determine what bit to set in the <emphasis>
  24 led_mask</emphasis>
  25  field to turn on the <emphasis>
  26 Scroll Lock </emphasis>
  27 LED or whether the keyboard even has a <emphasis>
  28 Scroll Lock</emphasis>
  29  LED.
  30 </para>
  31
  32
  33 <para>
  34 Xkb provides indicator names and programmable indicators to help solve these
  35 problems. Using Xkb, clients can determine the names of the various indicators,
  36 determine and control the way that the individual indicators should be updated
  37 to reflect keyboard changes, and determine which of the 32 keyboard indicators
  38 reported by the protocol are actually present on the keyboard. Clients may also
  39 request immediate notification of changes to the state of any subset of the
  40 keyboard indicators, which makes it straightforward to provide an on-screen
  41 "virtual" LED panel. This chapter describes Xkb indicators and the functions
  42 used for manipulating them.
  43 </para>
  44
  45 <sect1 id='Indicator_Names'>
  46 <title>Indicator Names</title>
  47
  48 <para>
  49 Xkb provides the capability of symbolically naming indicators. Xkb itself
  50 doesn’t use these symbolic names for anything; they are there only to help
  51 make the keyboard description comprehensible to humans. To set the names of
  52 specific indicators, use <emphasis>
  53 XkbSetNames</emphasis>
  54  as discussed in Chapter 18. Then set the map using <emphasis> <!-- xref -->
  55 XkbSetMap</emphasis>
  56  (see section 14.3) or <emphasis> <!-- xref -->
  57 XkbSetNamedIndicator</emphasis>
  58  (below). To retrieve indicator names, use <emphasis>
  59 XkbGetNames</emphasis>
  60  (Chapter 18). <!-- xref -->
  61 </para>
  62
  63
  64 </sect1>
  65 <sect1 id='Indicator_Data_Structures'>
  66 <title>Indicator Data Structures</title>
  67
  68 <para>
  69 Use the indicator description record, <emphasis>
  70 XkbIndicatorRec</emphasis>
  71 , and its indicator map, <emphasis>
  72 XkbIndicatorMapRec</emphasis>
  73 , to inquire about and control most indicator properties and behaviors.
  74 </para>
  75
  76
  77 <sect2 id='XkbIndicatorRec'>
  78 <title>XkbIndicatorRec</title>
  79
  80 <para>
  81 The description for all the Xkb indicators is held in the <emphasis>
  82 indicators</emphasis>
  83  field of the complete keyboard description (see Chapter 6), which is defined  <!-- xref -->
  84 as follows:
  85 </para>
  86
  87 <para><programlisting>
  88 #define      XkbNumIndicators      32
  89 </programlisting></para>
  90 <para><programlisting>
  91 typedef struct {
  92       unsigned long                   phys_indicators;        /* LEDs existence */
  93       XkbIndicatorMapRec              maps[XkbNumIndicators]; /* indicator maps */
  94 } <emphasis>XkbIndicatorRec</emphasis>,*XkbIndicatorPtr;
  95 </programlisting></para>
  96
  97 <para>
  98 This structure contains the <emphasis>
  99 phys_indicators</emphasis>
 100  field, which relates some information about the correspondence between
 101 indicators and physical LEDs on the keyboard, and an array of indicator
 102 <emphasis>
 103 maps</emphasis>
 104 , one map per indicator.
 105 </para>
 106
 107 <para>
 108 The <emphasis>
 109 phys_indicators</emphasis>
 110  field indicates which indicators are bound to physical LEDs on the keyboard;
 111 if a bit is set in <emphasis>
 112 phys_indicators</emphasis>
 113 , then the associated indicator has a physical LED associated with it. This
 114 field is necessary because some indicators may not have corresponding physical
 115 LEDs on the keyboard. For example, most keyboards have an LED for indicating
 116 the state of <emphasis>
 117 CapsLock</emphasis>
 118 , but most keyboards do not have an LED that indicates the current group.
 119 Because <emphasis>
 120 phys_indicators</emphasis>
 121  describes a physical characteristic of the keyboard, you cannot directly
 122 change it under program control. However, if a client program loads a
 123 completely new keyboard description via <emphasis>
 124 XkbGetKeyboardByName</emphasis>
 125 , or if a new keyboard is attached and the X implementation notices, <emphasis>
 126 phys_indicators</emphasis>
 127  changes if the indicators for the new keyboard are different.
 128 </para>
 129
 130
 131 </sect2>
 132 <sect2 id='XkbIndicatorMapRec'>
 133 <title>XkbIndicatorMapRec</title>
 134
 135 <para>
 136 Each indicator has its own set of attributes that specify whether clients can
 137 explicitly set its state and whether it tracks the keyboard state. The
 138 attributes of each indicator are held in the <emphasis>
 139 maps</emphasis>
 140  array, which is an array of <emphasis>
 141 XkbIndicatorRec</emphasis>
 142  structures:
 143 </para>
 144
 145 <para><programlisting>
 146 typedef struct {
 147       unsigned char    flags;         /* how the indicator can be changed */
 148       unsigned char    which_groups;  /* match criteria for groups */
 149       unsigned char    groups;        /* which keyboard groups the indicator watches */
 150       unsigned char    which_mods;    /* match criteria for modifiers */
 151       XkbModsRec       mods;          /* which modifiers the indicator watches */
 152       unsigned int     ctrls;         /* which controls the indicator watches */
 153 } <emphasis>XkbIndicatorMapRec</emphasis>, *XkbIndicatorMapPtr;
 154 </programlisting></para>
 155
 156 <para>
 157 This indicator map specifies for each indicator:
 158 </para>
 159
 160 <itemizedlist>
 161 <listitem>
 162   <para>
 163 The conditions under which the keyboard modifier state affects the indicator
 164   </para>
 165 </listitem>
 166 <listitem>
 167   <para>
 168 The conditions under which the keyboard group state affects the indicator
 169   </para>
 170 </listitem>
 171 <listitem>
 172   <para>
 173 The conditions under which the state of the boolean controls affects the
 174 indicator
 175   </para>
 176 </listitem>
 177 <listitem>
 178   <para>
 179 The effect (if any) of attempts to explicitly change the state of the indicator
 180 using the functions <emphasis>
 181 XkbSetControls</emphasis>
 182  or <emphasis>
 183 XChangeKeyboardControl</emphasis>
 184
 185   </para>
 186 </listitem>
 187 </itemizedlist>
 188
 189 <para>
 190 For more information on the effects of explicit changes to indicators and the
 191 relationship to the indicator map, see section 8.4.1. <!-- xref -->
 192 </para>
 193
 194 <sect3 id='XkbIndicatorMapRec_flags_field'>
 195 <title>XkbIndicatorMapRec flags field</title>
 196
 197 <para>
 198 The <emphasis>
 199 flags</emphasis>
 200  field specifies the conditions under which the indicator can be changed and
 201 the effects of changing the indicator. The valid values for <emphasis>
 202 flags</emphasis>
 203  and their effects are shown in Table 8.1. <!-- xref -->
 204 </para>
 205
 206 <table frame='topbot'>
 207 <title>XkbIndicatorMapRec flags Field</title>
 208 <?dbfo keep-together="always" ?>
 209 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 210 <colspec colname='c1' colwidth='2.0*'/>
 211 <colspec colname='c2' colwidth='1.0*'/>
 212 <colspec colname='c3' colwidth='3.0*'/>
 213 <thead>
 214 <row rowsep='1'>
 215   <entry>Value</entry>
 216   <entry></entry>
 217   <entry>Effect</entry>
 218   </row>
 219 </thead>
 220 <tbody>
 221   <row>
 222     <entry>XkbIM_NoExplicit</entry>
 223     <entry>(1L&lt;&lt;7)</entry>
 224     <entry>Client applications cannot change the state of the indicator.</entry>
 225   </row>
 226   <row>
 227     <entry>XkbIM_NoAutomatic</entry>
 228     <entry>(1L&lt;&lt;6)</entry>
 229     <entry>Xkb does not automatically change the value of the indicator based
 230 upon a change in the keyboard state, regardless of the values for the other
 231 fields of the indicator map.</entry>
 232   </row>
 233   <row>
 234     <entry>XkbIM_LEDDrivesKB</entry>
 235     <entry>(1L&lt;&lt;5)</entry>
 236     <entry>A client application changing the state of the indicator causes the
 237 state of the keyboard to change.</entry>
 238   </row>
 239 </tbody>
 240 </tgroup>
 241 </table>
 242
 243 <para>
 244 Note that if <emphasis>
 245 XkbIM_NoAutomatic</emphasis>
 246  is not set, by default the indicator follows the keyboard state.
 247 </para>
 248
 249
 250 <para>
 251 If <emphasis>
 252 XkbIM_LEDDrivesKB</emphasis>
 253  is set and <emphasis>
 254 XkbIM_NoExplicit</emphasis>
 255  is not, and if you call a function which updates the server’s image of the
 256 indicator map (such as <emphasis>
 257 XkbSetIndicatorMap</emphasis>
 258  or <emphasis>
 259 XkbSetNamedIndicator</emphasis>
 260 ), Xkb changes the keyboard state and controls to reflect the other fields of
 261 the indicator map, as described in the remainder of this section. If you
 262 attempt to explicitly change the value of an indicator for which <emphasis>
 263 XkbIM_LEDDrivesKB</emphasis>
 264  is absent or for which <emphasis>
 265 XkbIM_NoExplicit</emphasis>
 266  is present, keyboard state or controls are unaffected.
 267 </para>
 268
 269
 270 <para>
 271 For example, a keyboard designer may want to make the <emphasis>
 272 CapsLock</emphasis>
 273  LED controllable only by the server, but allow the <emphasis>
 274 Scroll Lock</emphasis>
 275  LED to be controlled by client applications. To do so, the keyboard designer
 276 could set the <emphasis>
 277 XkbIM_NoExplicit</emphasis>
 278  flag for the <emphasis>
 279 CapsLock</emphasis>
 280 <emphasis>
 281  </emphasis>
 282 LED, but not set it for the <emphasis>
 283 Scroll Lock</emphasis>
 284  LED. Or the keyboard designer may wish to allow the <emphasis>
 285 CapsLock</emphasis>
 286  LED to be controlled by both the server and client applications and also have
 287 the server to automatically change the <emphasis>
 288 CapsLock</emphasis>
 289 <emphasis>
 290  </emphasis>
 291 modifier state whenever a client application changes the <emphasis>
 292 CapsLock</emphasis>
 293  LED. To do so, the keyboard designer would not set the <emphasis>
 294 XkbIM_NoExplicit</emphasis>
 295  flag, but would instead set the <emphasis>
 296 XkbIM_LEDDrivesKB</emphasis>
 297  flag.
 298 </para>
 299
 300 <para>
 301 The remaining fields in the indicator map specify the conditions under which
 302 Xkb automatically turns an indicator on or off (only if <emphasis>
 303 XkbIM_NoAutomatic</emphasis>
 304  is not set). If these conditions match the keyboard state, Xkb turns the
 305 indicator on. If the conditions do not match, Xkb turns the indicator off.
 306 </para>
 307
 308 </sect3>
 309
 310 <sect3 id='XkbIndicatorMapRec_which_groups_and_groups_fields'>
 311 <title>XkbIndicatorMapRec which_groups and groups fields</title>
 312
 313 <para>
 314 The <emphasis>
 315 which_groups</emphasis>
 316  and the <emphasis>
 317 groups</emphasis>
 318  fields of an indicator map determine how the keyboard group state affects the
 319 corresponding indicator. The <emphasis>
 320 which_groups</emphasis>
 321  field controls the interpretation of <emphasis>
 322 groups</emphasis>
 323  and may contain any one of the following values:
 324 </para>
 325
 326 <para><programlisting>
 327 #define XkbIM_UseNone             0
 328 #define XkbIM_UseBase             (1L &lt;&lt; 0)
 329 #define XkbIM_UseLatched          (1L &lt;&lt; 1)
 330 #define XkbIM_UseLocked           (1L &lt;&lt; 2)
 331 #define XkbIM_UseEffective        (1L &lt;&lt; 3)
 332 #define XkbIM_UseAnyGroup         XkbIM_UseLatched | XkbIM_UseLocked |
 333                                   XkbIM_UseEffective
 334 </programlisting></para>
 335
 336 <para>
 337 The <emphasis>
 338 groups </emphasis>
 339 field specifies what keyboard groups an indicator watches and is the bitwise
 340 inclusive OR of the following valid values:
 341 </para>
 342
 343 <para><programlisting>
 344 #define XkbGroup1Mask            (1&lt;&lt;0)
 345 #define XkbGroup2Mask            (1&lt;&lt;1)
 346 #define XkbGroup3Mask            (1&lt;&lt;2)
 347 #define XkbGroup4Mask            (1&lt;&lt;3)
 348 #define XkbAnyGroupMask          (1&lt;&lt;7)
 349 #define XkbAllGroupsMask         (0xf)
 350 </programlisting></para>
 351
 352 <para>
 353 If <emphasis>
 354 XkbIM_NoAutomatic</emphasis>
 355  is not set (the keyboard drives the indicator), the effect of <emphasis>
 356 which_groups</emphasis>
 357  and <emphasis>
 358 groups</emphasis>
 359  is shown in Table 8.2. <!-- xref -->
 360 </para>
 361
 362 <table frame='topbot'>
 363 <title>XkbIndicatorMapRec which_groups and groups, Keyboard Drives
 364 Indicator</title>
 365 <?dbfo keep-together="always" ?>
 366 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 367 <colspec colname='c1' colwidth='1.0*'/>
 368 <colspec colname='c2' colwidth='2.0*'/>
 369 <thead>
 370 <row rowsep='1'>
 371   <entry>which_groups</entry>
 372   <entry>Effect</entry>
 373   </row>
 374 </thead>
 375 <tbody>
 376   <row>
 377     <entry>XkbIM_UseNone</entry>
 378     <entry>
 379 The <emphasis>
 380 groups</emphasis>
 381  field and the current keyboard group state are ignored.
 382     </entry>
 383   </row>
 384   <row>
 385     <entry>XkbIM_UseBase</entry>
 386     <entry>
 387 If <emphasis>
 388 groups</emphasis>
 389  is nonzero, the indicator is lit whenever the base keyboard group is nonzero.
 390 If <emphasis>
 391 groups</emphasis>
 392  is zero, the indicator is lit whenever the base keyboard group is zero.
 393     </entry>
 394   </row>
 395   <row>
 396     <entry>XkbIM_UseLatched</entry>
 397     <entry>
 398 If <emphasis>
 399 groups</emphasis>
 400  is nonzero, the indicator is lit whenever the latched keyboard group is
 401 nonzero. If <emphasis>
 402 groups</emphasis>
 403  is zero, the indicator is lit whenever the latched keyboard group is zero.
 404     </entry>
 405   </row>
 406   <row>
 407     <entry>XkbIM_UseLocked</entry>
 408     <entry>
 409 The <emphasis>
 410 groups</emphasis>
 411  field is interpreted as a mask. The indicator is lit when the current locked
 412 keyboard group matches one of the bits that are set in <emphasis>
 413 groups</emphasis>.
 414     </entry>
 415   </row>
 416   <row>
 417     <entry>XkbIM_UseEffective</entry>
 418     <entry>
 419 The <emphasis>
 420 groups</emphasis>
 421  field is interpreted as a mask. The indicator is lit when the current
 422 effective keyboard group matches one of the bits that are set in <emphasis>
 423 groups</emphasis>
 424 .
 425     </entry>
 426   </row>
 427 </tbody>
 428 </tgroup>
 429 </table>
 430
 431 <para>
 432 The effect of <emphasis>
 433 which_groups</emphasis>
 434  and <emphasis>
 435 groups</emphasis>
 436  when you change an indicator for which <emphasis>
 437 XkbIM_LEDDrivesKB</emphasis>
 438  is set (the indicator drives the keyboard) is shown in Table 8.3. The "New
 439 State" column refers to the new state to which you set the indicator.
 440 </para>
 441
 442 <table frame='topbot'>
 443 <title>XkbIndicatorMapRec which_groups and groups, Indicator Drives
 444 Keyboard</title>
 445 <?dbfo keep-together="always" ?>
 446 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 447 <colspec colname='c1' colwidth='2.0*'/>
 448 <colspec colname='c2' colwidth='1.0*'/>
 449 <colspec colname='c3' colwidth='3.0*'/>
 450 <thead>
 451 <row rowsep='1'>
 452   <entry>which_groups</entry>
 453   <entry>New State</entry>
 454   <entry>Effect on Keyboard Group State</entry>
 455   </row>
 456 </thead>
 457 <tbody>
 458   <row>
 459     <entry>XkbIM_UseNone </entry>
 460     <entry>On or Off</entry>
 461     <entry>No effect</entry>
 462   </row>
 463   <row>
 464     <entry>XkbIM_UseBase</entry>
 465     <entry>On or Off</entry>
 466     <entry>No effect</entry>
 467   </row>
 468   <row>
 469     <entry>XkbIM_UseLatched</entry>
 470     <entry>On</entry>
 471     <entry>
 472 The <emphasis>
 473 groups</emphasis>
 474  field is treated as a group mask. The keyboard group latch is changed to the
 475 lowest numbered group specified in <emphasis>
 476 groups</emphasis>
 477 ; if <emphasis>
 478 groups</emphasis>
 479  is empty, the keyboard group latch is changed to zero.
 480     </entry>
 481   </row>
 482   <row>
 483     <entry>XkbIM_UseLatched</entry>
 484     <entry>Off</entry>
 485     <entry>
 486 The <emphasis>
 487 groups</emphasis>
 488  field is treated as a group mask. If the indicator is explicitly extinguished,
 489 keyboard group latch is changed to the lowest numbered group not specified in
 490 <emphasis>
 491 groups</emphasis>
 492 ; if <emphasis>
 493 groups</emphasis>
 494  is zero, the keyboard group latch is set to the index of the highest legal
 495 keyboard group.
 496     </entry>
 497   </row>
 498   <row>
 499     <entry>XkbIM_UseLocked or XkbIM_UseEffective</entry>
 500     <entry>On</entry>
 501     <entry>
 502 If the <emphasis>
 503 groups</emphasis>
 504  mask is empty, group is not changed; otherwise, the locked keyboard group is
 505 changed to the lowest numbered group specified in <emphasis>
 506 groups</emphasis>.
 507     </entry>
 508   </row>
 509   <row>
 510     <entry>XkbIM_UseLocked or XkbIM_UseEffective</entry>
 511     <entry>Off</entry>
 512     <entry>
 513 Locked keyboard group is changed to the lowest numbered group that is not
 514 specified in the <emphasis>
 515 groups</emphasis>
 516  mask, or to <emphasis>
 517 Group1</emphasis>
 518  if the <emphasis>
 519 groups</emphasis>
 520  mask contains all keyboard groups.
 521     </entry>
 522   </row>
 523 </tbody>
 524 </tgroup>
 525 </table>
 526
 527 </sect3>
 528 <sect3 id='XkbIndicatorMapRec_which_mods_and_mods_fields'>
 529 <title>XkbIndicatorMapRec which_mods and mods fields</title>
 530
 531 <para>
 532 The <emphasis>
 533 mods </emphasis>
 534 field specifies what modifiers an indicator watches. The <emphasis>
 535 mods</emphasis>
 536  field is an Xkb modifier definition, <emphasis>
 537 XkbModsRec</emphasis>
 538 , as described in section 7.2, which can specify both real and virtual  <!-- xref -->
 539 modifiers. The <emphasis>
 540 mods</emphasis>
 541  field takes effect even if some or all of the virtual indicators specified in
 542 <emphasis>
 543 mods</emphasis>
 544  are unbound. To specify the mods field, in general, assign the modifiers of
 545 interest to <emphasis>
 546 mods.real_mods</emphasis>
 547  and the virtual modifiers of interest to <emphasis>
 548 mods.vmods</emphasis>
 549 . You can disregard the <emphasis>
 550 mods.mask</emphasis>
 551  field unless your application needs to interpret the indicator map directly
 552 (that is, to simulate automatic indicator behavior on its own). Relatively few
 553 applications need to do so, but if you find it necessary, you can either read
 554 the indicator map back from the server after you update it (the server
 555 automatically updates the mask field whenever any of the real or virtual
 556 modifiers are changed in the modifier definition) or you can use <emphasis>
 557 XkbVirtualModsToReal</emphasis>
 558  to determine the proper contents for the mask field, assuming that the
 559 <emphasis>
 560 XkbDescRec</emphasis>
 561  contains the virtual modifier definitions.
 562 </para>
 563
 564 <para>
 565 <emphasis>
 566 which_mods</emphasis>
 567  specifies what criteria Xkb uses to determine a match with the corresponding
 568 <emphasis>
 569 mods</emphasis>
 570  field by specifying one or more components of the Xkb keyboard state. If
 571 <emphasis>
 572 XkbIM_NoAutomatic</emphasis>
 573  is not set (the keyboard drives the indicator), the indicator is lit whenever
 574 any of the modifiers specified in the <emphasis>
 575 mask</emphasis>
 576  field of the<emphasis>
 577  mods</emphasis>
 578  modifier definition are also set in any of the current keyboard state
 579 components specified by <emphasis>
 580 which_mods</emphasis>
 581 . Remember that the <emphasis>
 582 mask</emphasis>
 583  field is comprised of all of the real modifiers specified in the definition
 584 plus any real modifiers that are bound to the virtual modifiers specified in
 585 the definition. (See Chapter 5 for more information on the keyboard state and  <!-- xref -->
 586 Chapter 7 for more information on virtual modifiers.) Use a bitwise inclusive
 587 OR of the following values to compose a value for <emphasis>
 588 which_mods</emphasis>:
 589 </para>
 590
 591 <para><programlisting>
 592 #define XkbIM_UseNone             0
 593 #define XkbIM_UseBase             (1L &lt;&lt; 0)
 594 #define XkbIM_UseLatched          (1L &lt;&lt; 1)
 595 #define XkbIM_UseLocked           (1L &lt;&lt; 2)
 596 #define XkbIM_UseEffective        (1L &lt;&lt; 3)
 597 #define XkbIM_UseCompat           (1L &lt;&lt; 4)
 598 #define XkbIM_UseAnyMods          XkbIM_UseBase | XkbIM_UseLatched |
 599                                   XkbIM_UseLocked | XkbIM_UseEffective |
 600                                   XkbIM_UseCompat
 601 </programlisting></para>
 602
 603 <para>
 604 If <emphasis>
 605 XkbIM_NoAutomatic</emphasis>
 606  is not set (the keyboard drives the indicator), the effect of <emphasis>
 607 which_mods</emphasis>
 608  and <emphasis>
 609 mods</emphasis>
 610  is shown in Table 8.4 <!-- xref -->
 611 </para>
 612
 613 <table frame='topbot'>
 614 <title>XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator</title>
 615 <?dbfo keep-together="always" ?>
 616 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 617 <colspec colname='c1' colwidth='1.0*'/>
 618 <colspec colname='c2' colwidth='2.0*'/>
 619 <thead>
 620 <row rowsep='1'>
 621   <entry>which_mods</entry>
 622   <entry>Effect on Keyboard Modifiers</entry>
 623   </row>
 624 </thead>
 625 <tbody>
 626   <row>
 627     <entry>XkbIM_UseNone</entry>
 628     <entry>The mods field and the current keyboard modifier state are
 629 ignored.</entry>
 630   </row>
 631   <row>
 632     <entry>XkbIM_UseBase</entry>
 633     <entry>
 634 The indicator is lit when any of the modifiers specified in the <emphasis>
 635 mask</emphasis>
 636  field of <emphasis>
 637 mods</emphasis>
 638  are on in the keyboard base state. If both <emphasis>
 639 mods.real_mods</emphasis>
 640  and <emphasis>
 641 mods.vmods</emphasis>
 642  are zero, the indicator is lit when the base keyboard state contains no
 643 modifiers.
 644     </entry>
 645   </row>
 646   <row>
 647     <entry>XkbIM_UseLatched</entry>
 648     <entry>
 649 The indicator is lit when any of the modifiers specified in the <emphasis>
 650 mask</emphasis>
 651  field of <emphasis>
 652 mods</emphasis>
 653  are latched. If both <emphasis>
 654 mods.real_mods</emphasis>
 655  and <emphasis>
 656 mods.vmods</emphasis>
 657  are zero, the indicator is lit when none of the modifier keys are latched.
 658     </entry>
 659   </row>
 660   <row>
 661     <entry>XkbIM_UseLocked</entry>
 662     <entry>
 663 The indicator is lit when any of the modifiers specified in the <emphasis>
 664 mask</emphasis>
 665  field of <emphasis>
 666 mods</emphasis>
 667  are locked. If both <emphasis>
 668 mods.real_mods</emphasis>
 669  and <emphasis>
 670 mods.vmods</emphasis>
 671  are zero, the indicator is lit when none of the modifier keys are locked.
 672     </entry>
 673   </row>
 674   <row>
 675     <entry>XkbIM_UseEffective</entry>
 676     <entry>
 677 The indicator is lit when any of the modifiers specified in the <emphasis>
 678 mask</emphasis>
 679  field of <emphasis>
 680 mods</emphasis>
 681  are in the effective keyboard state. If both <emphasis>
 682 mods.real_mods</emphasis>
 683  and <emphasis>
 684 mods.vmods</emphasis>
 685  are zero, the indicator is lit when the effective keyboard state contains no
 686 modifiers.
 687     </entry>
 688   </row>
 689   <row>
 690     <entry>XkbIM_UseCompat</entry>
 691     <entry>
 692 The indicator is lit when any of the modifiers specified in the <emphasis>
 693 mask</emphasis>
 694  field of <emphasis>
 695 mods</emphasis>
 696  are in the keyboard compatibility state. If both <emphasis>
 697 mods.real_mods</emphasis>
 698  and <emphasis>
 699 mods.vmods</emphasis>
 700  are zero, the indicator is lit when the keyboard compatibility state contains
 701 no modifiers.
 702     </entry>
 703   </row>
 704 </tbody>
 705 </tgroup>
 706 </table>
 707
 708 <para>
 709 The effect on the keyboard modifiers of <emphasis>
 710 which_mods</emphasis>
 711  and <emphasis>
 712 mods</emphasis>
 713  when you change an indicator for which <emphasis>
 714 XkbIM_LEDDrivesKB</emphasis>
 715  is set (the indicator drives the keyboard) is shown in Table 8.5. The "New
 716 State" column refers to the new state to which you set the indicator.
 717 </para> <!-- xref -->
 718
 719 <table frame='topbot'>
 720 <title>XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard</title>
 721 <?dbfo keep-together="always" ?>
 722 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 723 <colspec colname='c1' colwidth='2.0*'/>
 724 <colspec colname='c2' colwidth='1.0*'/>
 725 <colspec colname='c3' colwidth='3.0*'/>
 726 <thead>
 727 <row rowsep='1'>
 728   <entry>which_mods</entry>
 729   <entry>New State</entry>
 730   <entry>Effect on Keyboard Modifiers</entry>
 731   </row>
 732 </thead>
 733 <tbody>
 734   <row>
 735     <entry>XkbIM_UseNone or XkbIM_UseBase</entry>
 736     <entry>On or Off</entry>
 737     <entry>No Effect</entry>
 738   </row>
 739   <row>
 740     <entry>XkbIM_UseLatched</entry>
 741     <entry>On</entry>
 742     <entry>
 743 Any modifiers specified in the <emphasis>
 744 mask</emphasis>
 745  field of <emphasis>
 746 mods</emphasis>
 747  are added to the latched modifiers.
 748     </entry>
 749   </row>
 750   <row>
 751     <entry>XkbIM_UseLatched</entry>
 752     <entry>Off</entry>
 753     <entry>
 754 Any modifiers specified in the <emphasis>
 755 mask</emphasis>
 756  field of <emphasis>
 757 mods</emphasis>
 758  are removed from the latched modifiers.
 759     </entry>
 760   </row>
 761   <row>
 762     <entry>XkbIM_UseLocked, XkbIM_UseCompat, or XkbIM_UseEffective</entry>
 763     <entry>On</entry>
 764     <entry>
 765 Any modifiers specified in the <emphasis>
 766 mask</emphasis>
 767  field of <emphasis>
 768 mods</emphasis>
 769  are added to the locked modifiers.
 770     </entry>
 771   </row>
 772   <row>
 773     <entry>XkbIM_UseLocked</entry>
 774     <entry>Off</entry>
 775     <entry>
 776 Any modifiers specified in the <emphasis>
 777 mask</emphasis>
 778  field of <emphasis>
 779 mods</emphasis>
 780  are removed from the locked modifiers.
 781     </entry>
 782   </row>
 783   <row>
 784     <entry>XkbIM_UseCompat or XkbIM_UseEffective</entry>
 785     <entry>Off</entry>
 786     <entry>
 787 Any modifiers specified in the <emphasis>
 788 mask</emphasis>
 789  field of <emphasis>
 790 mods</emphasis>
 791  are removed from both the locked and latched modifiers.
 792     </entry>
 793   </row>
 794 </tbody>
 795 </tgroup>
 796 </table>
 797
 798 </sect3>
 799 <sect3 id='XkbIndicatorMapRec_ctrls_field'>
 800 <title>XkbIndicatorMapRec ctrls field</title>
 801
 802 <para>
 803 The <emphasis>
 804 ctrls</emphasis>
 805  field specifies what controls (see Chapter 10) the indicator watches and is
 806 composed using the bitwise inclusive OR of the following values:
 807 </para> <!-- xref -->
 808
 809 <para><programlisting>
 810 #define XkbRepeatKeysMask           (1L &lt;&lt; 0)
 811 #define XkbSlowKeysMask             (1L &lt;&lt; 1)
 812 #define XkbBounceKeysMask           (1L &lt;&lt; 2)
 813 #define XkbStickyKeysMask           (1L &lt;&lt; 3)
 814 #define XkbMouseKeysMask            (1L &lt;&lt; 4)
 815 #define XkbMouseKeysAccelMask       (1L &lt;&lt; 5)
 816 #define XkbAccessXKeysMask          (1L &lt;&lt; 6)
 817 #define XkbAccessXTimeoutMask       (1L &lt;&lt; 7)
 818 #define XkbAccessXFeedbackMask      (1L &lt;&lt; 8)
 819 #define XkbAudibleBellMask          (1L &lt;&lt; 9)
 820 #define XkbOverlay1Mask             (1L &lt;&lt; 10)
 821 #define XkbOverlay2Mask             (1L &lt;&lt; 11)
 822 #define XkbAllBooleanCtrlsMask      (0x00001FFF)
 823 </programlisting></para>
 824
 825 <para>
 826 Xkb lights the indicator whenever any of the boolean controls specified in
 827 <emphasis>
 828 ctrls</emphasis>
 829  is enabled.
 830 </para>
 831
 832
 833 </sect3>
 834 </sect2>
 835 </sect1>
 836 <sect1 id='Getting_Information_About_Indicators'>
 837 <title>Getting Information About Indicators</title>
 838
 839 <para>
 840 Xkb allows applications to obtain information about indicators using two
 841 different methods. The first method, which is similar to the core X
 842 implementation, uses a mask to specify the indicators. The second method, which
 843 is more suitable for applications concerned with interoperability, uses
 844 indicator names. The correspondence between the indicator name and the bit
 845 position in masks is as follows: one of the parameters returned from <emphasis>
 846 XkbGetNamedIndicators</emphasis>
 847  is an index that is the bit position to use in any function call that requires
 848 a mask of indicator bits, as well as the indicator’s index into the <emphasis>
 849 XkbIndicatorRec</emphasis>
 850  array of indicator maps.
 851 </para>
 852
 853
 854 <sect2 id='Getting_Indicator_State'>
 855 <title>Getting Indicator State</title>
 856
 857 <para>
 858 Because the state of the indicators is relatively volatile, the keyboard
 859 description does not hold the current state of the indicators. To obtain the
 860 current state of the keyboard indicators, use <emphasis>
 861 XkbGetIndicatorState</emphasis>.
 862 </para>
 863
 864 <informaltable frame='none'>
 865 <?dbfo keep-together="always" ?>
 866 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 867 <colspec colname='c1' colwidth='1.0*'/>
 868 <tbody>
 869   <row>
 870     <entry role='functiondecl'>
 871 Status <emphasis>
 872 XkbGetIndicatorState</emphasis>
 873 (<emphasis>
 874 display</emphasis>
 875 , <emphasis>
 876 device_spec</emphasis>
 877 , <emphasis>
 878 state_return</emphasis>
 879 )
 880     </entry>
 881   </row>
 882   <row>
 883     <entry role='functionargdecl'>
 884 Display *      <emphasis>
 885 display</emphasis>
 886 ;            /* connection to the X server */
 887     </entry>
 888   </row>
 889   <row>
 890     <entry role='functionargdecl'>
 891 unsigned int      <emphasis>
 892 device_spec</emphasis>
 893 ;            /* device ID, or <emphasis>
 894 XkbUseCoreKbd</emphasis>
 895  */
 896     </entry>
 897   </row>
 898   <row>
 899     <entry role='functionargdecl'>
 900 unsigned int *      <emphasis>
 901 state_return</emphasis>
 902 ;            /* backfilled with a mask of the indicator state */
 903     </entry>
 904 </row>
 905 </tbody>
 906 </tgroup>
 907 </informaltable>
 908
 909 <para>
 910 <emphasis>
 911 XkbGetIndicatorState</emphasis>
 912  queries the <emphasis>
 913 display</emphasis>
 914  for the state of the indicators on the device specified by the <emphasis>
 915 device_spec</emphasis>
 916 . For each indicator that is "turned on" on the device, the associated bit is
 917 set in <emphasis>
 918 state_return</emphasis>
 919 . If a compatible version of the Xkb extension is not available in the server,
 920 <emphasis>
 921 XkbGetIndicatorState</emphasis>
 922  returns a <emphasis>
 923 BadMatch</emphasis>
 924  error. Otherwise, it sends the request to the X server, places the state of
 925 the indicators into <emphasis>
 926 state_return,</emphasis>
 927  and returns <emphasis>
 928 Success</emphasis>
 929 . Thus the value reported by <emphasis>
 930 XkbGetIndicatorState</emphasis>
 931  is identical to the value reported by the core protocol.
 932 </para>
 933
 934
 935 </sect2>
 936 <sect2 id='Getting_Indicator_Information_by_Index'>
 937 <title>Getting Indicator Information by Index</title>
 938
 939 <para>
 940 To get the map for one or more indicators, using a mask to specify the
 941 indicators, use <emphasis>
 942 XkbGetIndicatorMap</emphasis>.
 943 </para>
 944
 945 <informaltable frame='none'>
 946 <?dbfo keep-together="always" ?>
 947 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 948 <colspec colname='c1' colwidth='1.0*'/>
 949 <tbody>
 950   <row>
 951     <entry role='functiondecl'>
 952 Status <emphasis>
 953 XkbGetIndicatorMap</emphasis>
 954 (<emphasis>
 955 dpy</emphasis>
 956 ,<emphasis>
 957  which</emphasis>
 958 ,<emphasis>
 959  desc</emphasis>
 960 )
 961     </entry>
 962   </row>
 963   <row>
 964     <entry role='functionargdecl'>
 965 Display *      <emphasis>
 966 dpy</emphasis>
 967 ;      /* connection to the X server */
 968     </entry>
 969   </row>
 970   <row>
 971     <entry role='functionargdecl'>
 972 unsigned int      <emphasis>
 973 which</emphasis>
 974 ;      /* mask of indicators for which maps should be returned */
 975     </entry>
 976   </row>
 977   <row>
 978     <entry role='functionargdecl'>
 979 XkbDescPtr      <emphasis>
 980 desc</emphasis>
 981 ;      /* keyboard description to be updated */
 982     </entry>
 983 </row>
 984 </tbody>
 985 </tgroup>
 986 </informaltable>
 987
 988 <para>
 989 <emphasis>
 990 XkbGetIndicatorMap</emphasis>
 991  obtains the maps from the server for only those indicators specified by the
 992 <emphasis>
 993 which</emphasis>
 994  mask and copies the values into the keyboard description specified by
 995 <emphasis>
 996 desc</emphasis>
 997 . If the <emphasis>
 998 indicators</emphasis>
 999  field of the <emphasis>
1000 desc</emphasis>
1001  parameter is <emphasis>
1002 NULL</emphasis>
1003 , <emphasis>
1004 XkbGetIndicatorMap</emphasis>
1005  allocates and initializes it.
1006 </para>
1007
1008
1009 <para>
1010 <emphasis>
1011 XkbGetIndicatorMap</emphasis>
1012  can generate <emphasis>
1013 BadAlloc</emphasis>
1014 , <emphasis>
1015 BadLength</emphasis>
1016 , <emphasis>
1017 BadMatch</emphasis>
1018 , and <emphasis>
1019 BadImplementation</emphasis>
1020  errors.
1021 </para>
1022
1023
1024 <para>
1025 To free the indicator maps, use <emphasis>
1026 XkbFreeIndicatorMaps</emphasis>
1027  (see section 8.6).
1028 </para>
1029
1030
1031 </sect2>
1032 <sect2 id='Getting_Indicator_Information_by_Name'>
1033 <title>Getting Indicator Information by Name</title>
1034
1035 <para>
1036 Xkb also allows applications to refer to indicators by name. Use <emphasis>
1037 XkbGetNames</emphasis>
1038  to get the indicator names (see Chapter 18). Using names eliminates the need
1039 for hard-coding bitmask values for particular keyboards. For example, instead
1040 of using vendor-specific constants such as <emphasis>
1041 WSKBLed_ScrollLock</emphasis>
1042  mask on Digital workstations or <emphasis>
1043 XLED_SCROLL_LOCK</emphasis>
1044  on Sun workstations, you can instead use <emphasis>
1045 XkbGetNamedIndicator</emphasis>
1046  to look up information on the indicator named "Scroll Lock."
1047 </para>
1048
1049 <para>
1050 Use <emphasis>
1051 XkbGetNamedIndicator</emphasis>
1052  to look up the indicator map and other information for an indicator by name.
1053 </para>
1054
1055 <informaltable frame='none'>
1056 <?dbfo keep-together="always" ?>
1057 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1058 <colspec colname='c1' colwidth='1.0*'/>
1059 <tbody>
1060   <row>
1061     <entry role='functiondecl'>
1062 Bool <emphasis>
1063 XkbGetNamedIndicator</emphasis>
1064 (<emphasis>
1065 dpy</emphasis>
1066 ,<emphasis>
1067  dev_spec</emphasis>
1068 ,<emphasis>
1069  name</emphasis>
1070 ,<emphasis>
1071  ndx_rtrn</emphasis>
1072 ,<emphasis>
1073  state_rtrn</emphasis>
1074 ,<emphasis>
1075  map_rtrn</emphasis>
1076 , <emphasis>
1077 real_rtrn</emphasis>
1078 )
1079     </entry>
1080   </row>
1081   <row>
1082     <entry role='functionargdecl'>
1083 Display *            <emphasis>
1084 dpy</emphasis>
1085 ;            /* connection to the X server */
1086     </entry>
1087   </row>
1088   <row>
1089     <entry role='functionargdecl'>
1090 unsigned int      <emphasis>
1091       device_spec</emphasis>
1092 ;            /* keyboard device ID, or <emphasis>
1093 XkbUseCoreKbd</emphasis>
1094  */
1095     </entry>
1096   </row>
1097   <row>
1098     <entry role='functionargdecl'>
1099 Atom      <emphasis>
1100       name</emphasis>
1101 ;            /* name of the indicator to be retrieved */
1102     </entry>
1103   </row>
1104   <row>
1105     <entry role='functionargdecl'>
1106 int *            <emphasis>
1107 ndx_rtrn</emphasis>
1108 ;            /* backfilled with the index of the retrieved indicator */
1109     </entry>
1110   </row>
1111   <row>
1112     <entry role='functionargdecl'>
1113 Bool *            <emphasis>
1114 state_rtrn</emphasis>
1115 ;            /* backfilled with the current state of the retrieved indicator */
1116     </entry>
1117   </row>
1118   <row>
1119     <entry role='functionargdecl'>
1120 XkbIndicatorMapPtr      <emphasis>
1121       map_rtrn</emphasis>
1122 ;            /* backfilled with the mapping for the retrieved indicator */
1123     </entry>
1124   </row>
1125   <row>
1126     <entry role='functionargdecl'>
1127 Bool *            <emphasis>
1128 real_rtrn</emphasis>
1129 ;            /* backfilled with <emphasis>
1130 True</emphasis>
1131  if the named indicator is real (physical) */
1132     </entry>
1133 </row>
1134 </tbody>
1135 </tgroup>
1136 </informaltable>
1137
1138 <para>
1139 If the device specified by <emphasis>
1140 device_spec</emphasis>
1141  has an indicator named <emphasis>
1142 name</emphasis>
1143 ,<emphasis>
1144  XkbGetNamedIndicator</emphasis>
1145  returns <emphasis>
1146 True</emphasis>
1147  and populates the rest of the parameters with information about the indicator.
1148 Otherwise, <emphasis>
1149 XkbGetNamedIndicator</emphasis>
1150  returns <emphasis>
1151 False</emphasis>
1152 .
1153 </para>
1154
1155
1156 <para>
1157 The <emphasis>
1158 ndx_rtrn</emphasis>
1159  field returns the zero-based index of the named indicator. This index is the
1160 bit position to use in any function call that requires a mask of indicator
1161 bits, as well as the indicator’s index into the <emphasis>
1162 XkbIndicatorRec</emphasis>
1163  array of indicator maps. <emphasis>
1164 state_rtrn</emphasis>
1165  returns the current state of the named indicator (<emphasis>
1166 True</emphasis>
1167  = on, <emphasis>
1168 False</emphasis>
1169  = off). <emphasis>
1170 map_rtrn</emphasis>
1171  returns the indicator map for the named indicator. In addition, if the
1172 indicator is mapped to a physical LED, the <emphasis>
1173 real_rtrn</emphasis>
1174  parameter is set to <emphasis>
1175 True</emphasis>
1176 .
1177 </para>
1178
1179
1180 <para>
1181 Each of the "<emphasis>
1182 _rtrn</emphasis>
1183 " arguments is optional; you can pass <emphasis>
1184 NULL</emphasis>
1185  for any unneeded "<emphasis>
1186 _rtrn</emphasis>
1187 " arguments.
1188 </para>
1189
1190
1191 <para>
1192 <emphasis>
1193 XkbGetNamedIndicator</emphasis>
1194  can generate <emphasis>
1195 BadAtom</emphasis>
1196  and <emphasis>
1197 BadImplementation</emphasis>
1198  errors.
1199 </para>
1200
1201
1202 </sect2>
1203 </sect1>
1204 <sect1 id='Changing_Indicator_Maps_and_State'>
1205 <title>Changing Indicator Maps and State</title>
1206
1207 <para>
1208 Just as you can get the indicator map using a mask or using an indicator name,
1209 so you can change it using a mask or a name.
1210 </para>
1211
1212 <note><para>You cannot change the <emphasis>
1213 phys_indicators</emphasis>
1214  field of the indicators structure. The only way to change the <emphasis>
1215 phys_indicators</emphasis>
1216  field is to change the keyboard map.</para></note>
1217
1218 <para>
1219 There are two ways to make changes to indicator maps and state: either change a
1220 local copy of the indicator maps and use <emphasis>
1221 XkbSetIndicatorMap</emphasis>
1222  or <emphasis>
1223 XkbSetNamedIndicator</emphasis>
1224 , or, to reduce network traffic, use an<emphasis>
1225  XkbIndicatorChangesRec</emphasis>
1226  structure and use <emphasis>
1227 XkbChangeIndicators</emphasis>.
1228 </para>
1229
1230
1231 <sect2 id='Effects_of_Explicit_Changes_on_Indicators'>
1232 <title>Effects of Explicit Changes on Indicators</title>
1233
1234 <para>
1235 This section discusses the effects of explicitly changing indicators depending
1236 upon different settings in the indicator map. See Tables 8.3 and Table 8.5 for
1237 information on the effects of the indicator map fields when explicit changes
1238 are made.
1239 </para>
1240
1241
1242 <para>
1243 If <emphasis>
1244 XkbIM_LEDDrivesKB</emphasis>
1245  is set and <emphasis>
1246 XkbIM_NoExplicit</emphasis>
1247  is not, and if you call a function that updates the server’s image of the
1248 indicator map (such as <emphasis>
1249 XkbSetIndicatorMap</emphasis>
1250  or <emphasis>
1251 XkbSetNamedIndicator</emphasis>
1252 ), Xkb changes the keyboard state and controls to reflect the other fields of
1253 the indicator map. If you attempt to explicitly change the value of an
1254 indicator for which <emphasis>
1255 XkbIM_LEDDrivesKB</emphasis>
1256  is absent or for which <emphasis>
1257 XkbIM_NoExplicit</emphasis>
1258  is present, keyboard state or controls are unaffected.
1259 </para>
1260
1261
1262 <para>
1263 If neither <emphasis>
1264 XkbIM_NoAutomatic</emphasis>
1265  nor <emphasis>
1266 XkbIM_NoExplicit</emphasis>
1267  is set in an indicator map, Xkb honors any request to change the state of the
1268 indicator, but the new state might be immediately superseded by automatic
1269 changes to the indicator state if the keyboard state or controls change.
1270 </para>
1271
1272
1273 <para>
1274 The effects of changing an indicator that drives the keyboard are cumulative;
1275 it is possible for a single change to affect keyboard group, modifiers, and
1276 controls simultaneously.
1277 </para>
1278
1279
1280 <para>
1281 If you change an indicator for which both the <emphasis>
1282 XkbIM_LEDDrivesKB</emphasis>
1283  and <emphasis>
1284 XkbIM_NoAutomatic</emphasis>
1285  flags are specified, Xkb applies the keyboard changes specified in the other
1286 indicator map fields and changes the indicator to reflect the state that was
1287 explicitly requested. The indicator remains in the new state until it is
1288 explicitly changed again.
1289 </para>
1290
1291
1292 <para>
1293 If the <emphasis>
1294 XkbIM_NoAutomatic</emphasis>
1295  flag is not set and <emphasis>
1296 XkbIM_LEDDrivesKB</emphasis>
1297  is set, Xkb applies the changes specified in the other indicator map fields
1298 and sets the state of the indicator to the values specified by the indicator
1299 map. Note that it is possible in this case for the indicator to end up in a
1300 different state than the one that was explicitly requested. For example, Xkb
1301 does not extinguish an indicator with <emphasis>
1302 which_mods</emphasis>
1303  of <emphasis>
1304 XkbIM_UseBase</emphasis>
1305  and <emphasis>
1306 mods</emphasis>
1307  of <emphasis>
1308 Shift</emphasis>
1309  if, at the time Xkb processes the request to extinguish the indicator, one of
1310 the <emphasis>
1311 Shift</emphasis>
1312  keys is physically depressed.
1313 </para>
1314
1315
1316 <para>
1317 If you explicitly light an indicator for which <emphasis>
1318 XkbIM_LEDDrivesKB</emphasis>
1319  is set, Xkb enables all of the boolean controls specified in the <emphasis>
1320 ctrls</emphasis>
1321  field of its indicator map. Explicitly extinguishing such an indicator causes
1322 Xkb to disable all of the boolean controls specified in <emphasis>
1323 ctrls</emphasis>
1324 .
1325 </para>
1326
1327
1328 </sect2>
1329 <sect2 id='Changing_Indicator_Maps_by_Index'>
1330 <title>Changing Indicator Maps by Index</title>
1331
1332 <para>
1333 To update the maps for one or more indicators, first modify a local copy of the
1334 keyboard description, then use <emphasis>
1335 XkbSetIndicatorMap</emphasis>
1336  to download the changes to the server:
1337 </para>
1338
1339 <informaltable frame='none'>
1340 <?dbfo keep-together="always" ?>
1341 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1342 <colspec colname='c1' colwidth='1.0*'/>
1343 <tbody>
1344   <row>
1345     <entry role='functiondecl'>
1346 Bool<emphasis>
1347  XkbSetIndicatorMap</emphasis>
1348 (<emphasis>
1349 dpy</emphasis>
1350 ,<emphasis>
1351  which</emphasis>
1352 ,<emphasis>
1353  desc</emphasis>
1354 )
1355     </entry>
1356   </row>
1357   <row>
1358     <entry role='functionargdecl'>
1359 Display *      <emphasis>
1360 dpy</emphasis>
1361 ;      /* connection to the X server */
1362     </entry>
1363   </row>
1364   <row>
1365     <entry role='functionargdecl'>
1366 unsigned int      <emphasis>
1367 which</emphasis>
1368 ;      /* mask of indicators to change */
1369     </entry>
1370   </row>
1371   <row>
1372     <entry role='functionargdecl'>
1373 XkbDescPtr      <emphasis>
1374 desc</emphasis>
1375 ;      /* keyboard description from which the maps are taken */
1376     </entry>
1377 </row>
1378 </tbody>
1379 </tgroup>
1380 </informaltable>
1381
1382 <para>
1383 For each<emphasis>
1384  </emphasis>
1385 bit set in the <emphasis>
1386 which </emphasis>
1387 parameter,<emphasis>
1388  XkbSetIndicatorMap</emphasis>
1389  sends the corresponding indicator map from the <emphasis>
1390 desc</emphasis>
1391  parameter to the server.
1392 </para>
1393
1394
1395 </sect2>
1396 <sect2 id='Changing_Indicator_Maps_by_Name'>
1397 <title>Changing Indicator Maps by Name</title>
1398
1399 <para>
1400 <emphasis>
1401 XkbSetNamedIndicator</emphasis>
1402  can do several related things:
1403 </para>
1404
1405 <itemizedlist>
1406 <listitem>
1407   <para>
1408 Name an indicator if it is not already named
1409   </para>
1410 </listitem>
1411 <listitem>
1412   <para>
1413 Toggle the state of the indicator
1414   </para>
1415 </listitem>
1416 <listitem>
1417   <para>
1418 Set the indicator to a specified state
1419   </para>
1420 </listitem>
1421 <listitem>
1422   <para>
1423 Set the indicator map for the indicator
1424   </para>
1425 </listitem>
1426 </itemizedlist>
1427
1428 <informaltable frame='none'>
1429 <?dbfo keep-together="always" ?>
1430 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1431 <colspec colname='c1' colwidth='1.0*'/>
1432 <tbody>
1433   <row>
1434     <entry role='functiondecl'>
1435 Bool<emphasis>
1436  XkbSetNamedIndicator</emphasis>
1437 (<emphasis>
1438 dpy</emphasis>
1439 ,<emphasis>
1440  device_spec</emphasis>
1441 ,<emphasis>
1442  name</emphasis>
1443 ,<emphasis>
1444  change_state, state</emphasis>
1445 ,<emphasis>
1446  create_new</emphasis>
1447 ,<emphasis>
1448  map</emphasis>
1449 )
1450     </entry>
1451   </row>
1452   <row>
1453     <entry role='functionargdecl'>
1454 Display *      <emphasis>
1455       dpy</emphasis>
1456 ;            /* connection to the X server */
1457     </entry>
1458   </row>
1459   <row>
1460     <entry role='functionargdecl'>
1461 unsigned int      <emphasis>
1462       device_spec</emphasis>
1463 ;            /* device ID, or <emphasis>
1464 XkbUseCoreKbd</emphasis>
1465  */
1466     </entry>
1467   </row>
1468   <row>
1469     <entry role='functionargdecl'>
1470 Atom      <emphasis>
1471       name</emphasis>
1472 ;            /* name of the indicator to change */
1473     </entry>
1474   </row>
1475   <row>
1476     <entry role='functionargdecl'>
1477 Bool      <emphasis>
1478       change_state</emphasis>
1479 ;            /* whether to change the indicator state or not */
1480     </entry>
1481   </row>
1482   <row>
1483     <entry role='functionargdecl'>
1484 Bool      <emphasis>
1485       state</emphasis>
1486 ;            /* desired new state for the indicator */
1487     </entry>
1488   </row>
1489   <row>
1490     <entry role='functionargdecl'>
1491 Bool            <emphasis>
1492 create_new</emphasis>
1493 ;            /* whether a new indicator with the specified name should be
1494 created when necessary */
1495     </entry>
1496   </row>
1497   <row>
1498     <entry role='functionargdecl'>
1499 XkbIndicatorMapPtr            <emphasis>
1500 map</emphasis>
1501 ;            /* new map for the indicator */
1502     </entry>
1503 </row>
1504 </tbody>
1505 </tgroup>
1506 </informaltable>
1507
1508 <para>
1509 If a compatible version of the Xkb extension is not available in the server,
1510 <emphasis>
1511 XkbSetNamedIndicator</emphasis>
1512  returns <emphasis>
1513 False</emphasis>
1514 . Otherwise, it sends a request to the X server to change the indicator
1515 specified by <emphasis>
1516 name</emphasis>
1517  and returns <emphasis>
1518 True</emphasis>.
1519 </para>
1520
1521
1522 <para>
1523 If <emphasis>
1524 change_state</emphasis>
1525  is <emphasis>
1526 True</emphasis>
1527 , and the optional parameter, <emphasis>
1528 state</emphasis>
1529 , is not <emphasis>
1530 NULL</emphasis>
1531 , <emphasis>
1532 XkbSetNamedIndicator</emphasis>
1533  tells the server to change the state of the named indicator to the value
1534 specified by <emphasis>
1535 state</emphasis>.
1536 </para>
1537
1538
1539 <para>
1540 If an indicator with the name specified by <emphasis>
1541 name</emphasis>
1542  does not already exist, the <emphasis>
1543 create_new</emphasis>
1544  parameter tells the server whether it should create a new named indicator. If
1545 <emphasis>
1546 create_new</emphasis>
1547  is <emphasis>
1548 True</emphasis>
1549 , the server finds the first indicator that doesn’t have a name and gives it
1550 the name specified by <emphasis>
1551 name</emphasis>.
1552 </para>
1553
1554
1555 <para>
1556 If the optional parameter, <emphasis>
1557 map</emphasis>
1558 , is not <emphasis>
1559 NULL</emphasis>
1560 , <emphasis>
1561 XkbSetNamedIndicator</emphasis>
1562  tells the server to change the indicator’s map to the values specified
1563 in <emphasis>map</emphasis>.
1564 </para>
1565
1566 <para>
1567 <emphasis>
1568 XkbSetNamedIndicator</emphasis>
1569  can generate <emphasis>
1570 BadAtom</emphasis>
1571  and <emphasis>
1572 BadImplementation</emphasis>
1573  errors. In addition, it can also generate <emphasis>
1574 XkbIndicatorStateNotify</emphasis>
1575  (see section 8.5), <emphasis> <!-- xref -->
1576 XkbIndicatorMapNotify</emphasis>
1577 , and <emphasis>
1578 XkbNamesNotify</emphasis>
1579  events (see section 18.5). <!-- xref -->
1580 </para>
1581
1582
1583 </sect2>
1584 <sect2 id='The_XkbIndicatorChangesRec_Structure'>
1585 <title>The XkbIndicatorChangesRec Structure</title>
1586
1587 <para>
1588 The <emphasis>
1589 XkbIndicatorChangesRec</emphasis>
1590  identifies small modifications to the indicator map. Use it with the function
1591 <emphasis>
1592 XkbChangeIndicators</emphasis>
1593  to reduce the amount of traffic sent to the server.
1594 </para>
1595
1596 <para><programlisting>
1597 typedef struct _XkbIndicatorChanges {
1598       unsigned int             state_changes;
1599       unsigned int             map_changes;
1600 }<emphasis>
1601 XkbIndicatorChangesRec</emphasis>,*XkbIndicatorChangesPtr;
1602 </programlisting></para>
1603
1604 <para>
1605 The <emphasis>
1606 state_changes</emphasis>
1607  field is a mask that specifies the indicators that have changed state, and
1608 <emphasis>
1609 map_changes</emphasis>
1610  is a mask that specifies the indicators whose maps have changed.
1611 </para>
1612
1613
1614 <para>
1615 To change indicator maps or state without passing the entire keyboard
1616 description, use <emphasis>
1617 XkbChangeIndicators</emphasis>
1618 .
1619 </para>
1620
1621 <informaltable frame='none'>
1622 <?dbfo keep-together="always" ?>
1623 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1624 <colspec colname='c1' colwidth='1.0*'/>
1625 <tbody>
1626   <row>
1627     <entry role='functiondecl'>
1628 Bool <emphasis>
1629 XkbChangeIndicators</emphasis>
1630 (<emphasis>
1631 dpy, xkb, changes, state</emphasis>
1632 )
1633     </entry>
1634   </row>
1635   <row>
1636     <entry role='functionargdecl'>
1637 Display *                  <emphasis>
1638 dpy</emphasis>
1639 ;      /* connection to the X server */
1640     </entry>
1641   </row>
1642   <row>
1643     <entry role='functionargdecl'>
1644 XkbDescPtr                  <emphasis>
1645 xkb</emphasis>
1646 ;      /* keyboard description from which names are to be
1647     </entry>
1648   </row>
1649   <row>
1650     <entry role='functionargdecl'>
1651                         taken. */
1652     </entry>
1653   </row>
1654   <row>
1655     <entry role='functionargdecl'>
1656 XkbIndicatorChangesPtr                  <emphasis>
1657 changes</emphasis>
1658 ;      /* indicators to be updated on the server */
1659     </entry>
1660   </row>
1661   <row>
1662     <entry role='functionargdecl'>
1663 unsigned int                  <emphasis>
1664 state</emphasis>
1665 ;      /* new state of indicators listed in
1666     </entry>
1667   </row>
1668   <row>
1669     <entry role='functionargdecl'>
1670 <emphasis>
1671                         changes</emphasis>
1672 -&gt;<emphasis>
1673 state_changes</emphasis>
1674  */
1675     </entry>
1676 </row>
1677 </tbody>
1678 </tgroup>
1679 </informaltable>
1680
1681 <para>
1682 <emphasis>
1683 XkbChangeIndicators</emphasis>
1684  copies any maps specified by <emphasis>
1685 changes</emphasis>
1686  from the keyboard description, <emphasis>
1687 xkb</emphasis>
1688 , to the server specified by <emphasis>
1689 dpy</emphasis>
1690 . If any bits are set in the <emphasis>
1691 state_changes</emphasis>
1692  field of <emphasis>
1693 changes</emphasis>
1694 , <emphasis>
1695 XkbChangeIndicators</emphasis>
1696  also sets the state of those indicators to the values specified in the
1697 <emphasis>
1698 state</emphasis>
1699  mask. A 1 bit in <emphasis>
1700 state</emphasis>
1701  turns the corresponding indicator on, a 0 bit turns it off.
1702 </para>
1703
1704
1705 <para>
1706 <emphasis>
1707 XkbChangeIndicator</emphasis>
1708 s can generate <emphasis>
1709 BadAtom</emphasis>
1710  and <emphasis>
1711 BadImplementation</emphasis>
1712  errors. In addition, it can also generate <emphasis>
1713 XkbIndicatorStateNotify</emphasis>
1714  and <emphasis>
1715 XkbIndicatorMapNotify</emphasis>
1716  events (see section 8.5). <!-- xref -->
1717 </para>
1718
1719
1720 </sect2>
1721 </sect1>
1722 <sect1 id='Tracking_Changes_to_Indicator_State_or_Map'>
1723 <title>Tracking Changes to Indicator State or Map</title>
1724
1725 <para>
1726 Whenever an indicator changes state, the server sends <emphasis>
1727 XkbIndicatorStateNotify</emphasis>
1728  events to all interested clients. Similarly, whenever an indicator’s map
1729 changes, the server sends <emphasis>
1730 XkbIndicatorMapNotify</emphasis>
1731  events to all interested clients.
1732 </para>
1733
1734
1735 <para>
1736 To receive <emphasis>
1737 XkbIndicatorStateNotify</emphasis>
1738  events, use <emphasis>
1739 XkbSelectEvents</emphasis>
1740  (see section 4.3) with both the <emphasis> <!-- xref -->
1741 bits_to_change </emphasis>
1742 and<emphasis>
1743  values_for_bits</emphasis>
1744  parameters containing <emphasis>
1745 XkbIndicatorStateNotifyMask</emphasis>
1746 . To receive <emphasis>
1747 XkbIndicatorMapNotify</emphasis>
1748  events, use <emphasis>
1749 XkbSelectEvents</emphasis>
1750  with <emphasis>
1751 XkbIndicatorMapNotifyMask</emphasis>
1752 .
1753 </para>
1754
1755
1756 <para>
1757 To receive events for only specific indicators, use <emphasis>
1758 XkbSelectEventDetails</emphasis>
1759 . Set the <emphasis>
1760 event_type</emphasis>
1761  parameter<emphasis>
1762  to XkbIndicatorStateNotify</emphasis>
1763  or <emphasis>
1764 XkbIndicatorMapNotify</emphasis>
1765 , and set both the <emphasis>
1766 bits_to_change </emphasis>
1767 and<emphasis>
1768  values_for_bits</emphasis>
1769  detail parameters to a mask where each bit specifies one indicator, turning on
1770 those bits that specify the indicators for which you want to receive events.
1771 </para>
1772
1773
1774 <para>
1775 Both types of indicator events use the same structure:
1776 </para>
1777
1778 <para><programlisting>
1779 typedef struct _XkbIndicatorNotify {
1780       int            type;        /* Xkb extension base event code */
1781       unsigned long  serial;      /* X server serial number for event */
1782       Bool           send_event;  /* <emphasis> True</emphasis> =&gt; synthetically generated */
1783       Display *      display;     /* server connection where event generated */
1784       Time           time;        /* server time when event generated */
1785       int            xkb_type;    /* specifies state or map notify */
1786       int            device;      /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */
1787       unsigned int   changed;     /* mask of indicators with new state or map */
1788       unsigned int   state;       /* current state of all indicators */
1789 } <emphasis>XkbIndicatorNotifyEvent</emphasis>;
1790 </programlisting></para>
1791
1792 <para>
1793 <emphasis>
1794 xkb_type</emphasis>
1795  is either <emphasis>
1796 XkbIndicatorStateNotify</emphasis>
1797  or <emphasis>
1798 XkbIndicatorMapNotify</emphasis>
1799 , depending on whether the event is a <emphasis>
1800 kbIndicatorStateNotify</emphasis>
1801  event or <emphasis>
1802 kbIndicatorMapNotify</emphasis>
1803  event.
1804 </para>
1805
1806 <para>
1807 The <emphasis>
1808 changed</emphasis>
1809  parameter is a mask that is the bitwise inclusive OR of the indicators that
1810 have changed. If the event is of type <emphasis>
1811 XkbIndicatorMapNotify</emphasis>
1812 , <emphasis>
1813 changed</emphasis>
1814  reports the maps that changed. If the event is of type <emphasis>
1815 XkbIndicatorStateNotify</emphasis>
1816 , <emphasis>
1817 changed</emphasis>
1818  reports the indicators that have changed state. <emphasis>
1819 state</emphasis>
1820  is a mask that specifies the current state of all indicators, whether they
1821 have changed or not, for both <emphasis>
1822 XkbIndicatorStateNotify</emphasis>
1823  and <emphasis>IndicatorMapNotify</emphasis> events.
1824 </para>
1825
1826 <para>
1827 When your client application receives either a <emphasis>
1828 XkbIndicatorStateNotify</emphasis>
1829  event or <emphasis>
1830 XkbIndicatorMapNotify</emphasis>
1831  event, you can note the changes in a changes structure by calling <emphasis>
1832 XkbNoteIndicatorChanges</emphasis>.
1833 </para>
1834
1835 <informaltable frame='none'>
1836 <?dbfo keep-together="always" ?>
1837 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1838 <colspec colname='c1' colwidth='1.0*'/>
1839 <tbody>
1840   <row>
1841     <entry role='functiondecl'>
1842 void <emphasis>
1843 XkbNoteIndicatorChanges</emphasis>
1844 (<emphasis>
1845 old</emphasis>
1846 ,<emphasis>
1847  new</emphasis>
1848 ,<emphasis>
1849  wanted</emphasis>
1850 )
1851     </entry>
1852   </row>
1853   <row>
1854     <entry role='functionargdecl'>
1855 XkbIndicatorChangesPtr            <emphasis>
1856       old</emphasis>
1857 ;      /* XkbIndicatorChanges structure to be updated */
1858     </entry>
1859   </row>
1860   <row>
1861     <entry role='functionargdecl'>
1862 XkbIndicatorNotifyEvent *                  <emphasis>
1863 new</emphasis>
1864 ;      /* event from which changes are to be copied */
1865     </entry>
1866   </row>
1867   <row>
1868     <entry role='functionargdecl'>
1869 unsigned int            <emphasis>
1870       wanted</emphasis>
1871 ;      /* which changes are to be noted */
1872     </entry>
1873 </row>
1874 </tbody>
1875 </tgroup>
1876 </informaltable>
1877
1878 <para>
1879 The <emphasis>
1880 wanted</emphasis>
1881  parameter is the bitwise inclusive OR of <emphasis>
1882 XkbIndicatorMapMask</emphasis>
1883  and <emphasis>
1884 XkbIndicatorStateMask</emphasis>
1885 . <emphasis>
1886 XkbNoteIndicatorChanges</emphasis>
1887  copies any changes reported in <emphasis>
1888 new</emphasis>
1889  and specified in <emphasis>
1890 wanted</emphasis>
1891  into the changes record specified by <emphasis>
1892 old</emphasis>.
1893 </para>
1894
1895
1896 <para>
1897 To update a local copy of the keyboard description with the actual values, pass
1898 the results of one or more calls to <emphasis>
1899 XkbNoteIndicatorChanges</emphasis>
1900  to <emphasis>
1901 XkbGetIndicatorChanges</emphasis>:
1902 </para>
1903
1904
1905 <informaltable frame='none'>
1906 <?dbfo keep-together="always" ?>
1907 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1908 <colspec colname='c1' colwidth='1.0*'/>
1909 <tbody>
1910   <row>
1911     <entry role='functiondecl'>
1912 Status <emphasis>
1913 XkbGetIndicatorChanges</emphasis>
1914 (<emphasis>
1915 dpy</emphasis>
1916 ,<emphasis>
1917  xkb</emphasis>
1918 ,<emphasis>
1919  changes</emphasis>
1920 ,<emphasis>
1921  state</emphasis>
1922 )
1923     </entry>
1924   </row>
1925   <row>
1926     <entry role='functionargdecl'>
1927 Display *            <emphasis>
1928 dpy</emphasis>
1929 ;            /* connection to the X server */
1930     </entry>
1931   </row>
1932   <row>
1933     <entry role='functionargdecl'>
1934 XkbDescPtr            <emphasis>
1935 xkb</emphasis>
1936 ;            /* keyboard description to hold the new values */
1937     </entry>
1938   </row>
1939   <row>
1940     <entry role='functionargdecl'>
1941 XkbIndicatorChangesPtr            <emphasis>
1942 changes</emphasis>
1943 ;            /* indicator maps/state to be obtained from the server */
1944     </entry>
1945   </row>
1946   <row>
1947     <entry role='functionargdecl'>
1948 unsigned int *            <emphasis>
1949 state</emphasis>
1950 ;            /* backfilled with the state of the indicators */
1951     </entry>
1952 </row>
1953 </tbody>
1954 </tgroup>
1955 </informaltable>
1956
1957 <para>
1958 <emphasis>
1959 XkbGetIndicatorChanges</emphasis>
1960  examines the <emphasis>
1961 changes</emphasis>
1962  parameter, pulls over the necessary information from the server, and copies
1963 the results into the <emphasis>
1964 xkb</emphasis>
1965  keyboard description. If any bits are set in the <emphasis>
1966 state_changes</emphasis>
1967  field of <emphasis>
1968 changes</emphasis>
1969 , <emphasis>
1970 XkbGetIndicatorChanges</emphasis>
1971  also places the state of those indicators in <emphasis>
1972 state</emphasis>
1973 . If the <emphasis>
1974 indicators</emphasis>
1975  field of <emphasis>
1976 xkb</emphasis>
1977  is <emphasis>
1978 NULL</emphasis>
1979 , <emphasis>
1980 XkbGetIndicatorChanges</emphasis>
1981  allocates and initializes it. To free the <emphasis>
1982 indicators</emphasis>
1983  field, use <emphasis>
1984 XkbFreeIndicators</emphasis>
1985  (see section 8.6). <!-- xref -->
1986 </para>
1987
1988
1989 <para>
1990 <emphasis>
1991 XkbGetIndicatorChanges</emphasis>
1992  can generate <emphasis>
1993 BadAlloc</emphasis>
1994 , <emphasis>
1995 BadImplementation,</emphasis>
1996  and <emphasis>
1997 BadMatch</emphasis>
1998  errors.
1999 </para>
2000
2001
2002 </sect1>
2003 <sect1 id='Allocating_and_Freeing_Indicator_Maps'>
2004 <title>Allocating and Freeing Indicator Maps</title>
2005
2006 <para>
2007 Most applications do not need to directly allocate the <emphasis>
2008 indicators</emphasis>
2009  member of the keyboard description record (the keyboard description record is
2010 described in Chapter 6). If the need arises, however, use <emphasis>
2011 XkbAllocIndicatorMaps.</emphasis>
2012 </para>
2013
2014 <informaltable frame='none'>
2015 <?dbfo keep-together="always" ?>
2016 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2017 <colspec colname='c1' colwidth='1.0*'/>
2018 <tbody>
2019   <row>
2020     <entry role='functiondecl'>
2021 Status <emphasis>
2022 XkbAllocIndicatorMaps</emphasis>
2023 (<emphasis>
2024 xkb</emphasis>
2025 )
2026     </entry>
2027   </row>
2028   <row>
2029     <entry role='functionargdecl'>
2030 XkbDescPtr      <emphasis>
2031 xkb</emphasis>
2032 ;      /* keyboard description structure */
2033     </entry>
2034 </row>
2035 </tbody>
2036 </tgroup>
2037 </informaltable>
2038
2039 <para>
2040 The <emphasis>
2041 xkb</emphasis>
2042  parameter must point to a valid keyboard description. If it doesn’t,
2043 <emphasis>
2044 XkbAllocIndicatorMaps</emphasis>
2045  returns a <emphasis>
2046 BadMatch</emphasis>
2047  error. Otherwise, <emphasis>
2048 XkbAllocIndicatorMaps</emphasis>
2049  allocates and initializes the <emphasis>
2050 indicators</emphasis>
2051  member of the keyboard description record and returns <emphasis>
2052 Success</emphasis>
2053 . If <emphasis>
2054 XkbAllocIndicatorMaps</emphasis>
2055  was unable to allocate the indicators record, it reports a Bad<emphasis>
2056 Alloc</emphasis>
2057  error.
2058 </para>
2059
2060 <para>
2061 To free memory used by the <emphasis>
2062 indicators</emphasis>
2063  member of an <emphasis>
2064 XkbDescRec</emphasis>
2065  structure, use <emphasis>
2066 XkbFreeIndicatorMaps.</emphasis>
2067 </para>
2068
2069 <informaltable frame='none'>
2070 <?dbfo keep-together="always" ?>
2071 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2072 <colspec colname='c1' colwidth='1.0*'/>
2073 <tbody>
2074   <row>
2075     <entry role='functiondecl'>
2076 void <emphasis>
2077 XkbFreeIndicatorMaps</emphasis>
2078 (<emphasis>
2079 xkb</emphasis>
2080 )
2081     </entry>
2082   </row>
2083   <row>
2084     <entry role='functionargdecl'>
2085 XkbDescPtr      <emphasis>
2086 xkb</emphasis>
2087 ;      /* keyboard description structure */
2088     </entry>
2089 </row>
2090 </tbody>
2091 </tgroup>
2092 </informaltable>
2093
2094 <para>
2095 If the <emphasis>indicators</emphasis>
2096  member of the keyboard description record
2097 pointed to by <emphasis>xkb</emphasis>
2098 is not <emphasis>NULL</emphasis>
2099 , <emphasis>XkbFreeIndicatorMaps</emphasis>
2100 frees the memory associated with
2101 the <emphasis>indicators</emphasis>
2102 member of <emphasis>xkb</emphasis>.
2103 </para>
2104
2105 </sect1>
2106 </chapter>