specs/ch09.xml

   1 <chapter id='Keyboard_Indicators'>
   2 <title>Keyboard Indicators</title>
   3
   4 <para>
   5 Although the core X protocol supports thirty-two LEDs on a keyboard, it does
   6 not provide any way to link the state of the LEDs and the logical state of the
   7 keyboard. For example, most keyboards have a "Caps Lock" LED, but X does not
   8 provide any standard way to make the LED automatically follow the logical state
   9 of the modifier bound to the <emphasis>
  10 Caps Lock</emphasis>
  11  key.
  12 </para>
  13
  14
  15 <para>
  16 The core protocol also gives no way to determine which bits in the <emphasis>
  17 led_mask</emphasis>
  18  field of the keyboard state map to the particular LEDs on the keyboard. For
  19 example, X does not provide a method for a client to determine which bit to set
  20 in the <emphasis>
  21 led_mask</emphasis>
  22  to turn on the "Scroll Lock" LED, or even if the keyboard has a "Scroll Lock"
  23 LED.
  24 </para>
  25
  26
  27 <para>
  28 Most X servers implement some kind of automatic behavior for one or more of the
  29 keyboard LEDs, but the details of that automatic behavior are
  30 implementation-specific and can be difficult or impossible to control.
  31 </para>
  32
  33
  34 <para>
  35 XKB provides indicator names and programmable indicators to help solve these
  36 problems. Using XKB, clients can determine the names of the various indicators,
  37 determine and control the way that the individual indicators should be updated
  38 to reflect keyboard changes, and determine which of the 32 keyboard indicators
  39 reported by the protocol are actually present on the keyboard. Clients may also
  40 request immediate notification of changes to the state of any subset of the
  41 keyboard indicators, which makes it straightforward to provide an on-screen
  42 "virtual" LED panel.
  43 </para>
  44
  45 <sect1 id='Global_Information_About_Indicators'>
  46 <title>Global Information About Indicators</title>
  47
  48 <para>
  49 XKB provides only two pieces of information about the indicators as a group.
  50 </para>
  51
  52
  53 <para>
  54 The <emphasis>
  55 physical indicators</emphasis>
  56  mask reports which of the 32 logical keyboard indicators supported by the core
  57 protocol and XKB corresponds to some actual indicator on the keyboard itself.
  58 Because the physical indicators mask describes a physical characteristic of the
  59 keyboard, it cannot be directly changed under program control. It is possible,
  60 however, for the set of physical indicators to be change if a new keyboard is
  61 attached or if a completely new keyboard description is loaded by the <emphasis>
  62 XkbGetKeyboardByName</emphasis>
  63  request (see <link linkend='Using_the_Servers_Database_of_Keyboard_Components'>Using the Server’s
  64 Database of Keyboard Components</link>).
  65 </para>
  66
  67
  68 <para>
  69 The <emphasis>
  70 indicator state</emphasis>
  71  mask reports the current state of the 32 logical keyboard indicators. This
  72 field and the core protocol indicator state (as reported by the <emphasis>
  73 led-mask</emphasis>
  74  field of the core protocol <emphasis>
  75 GetKeyboardControl</emphasis>
  76  request) are always identical.
  77 </para>
  78
  79
  80 </sect1>
  81 <sect1 id='Per_Indicator_Information'>
  82 <title>Per-Indicator Information</title>
  83
  84 <para>
  85 Each of the thirty-two keyboard indicators has a symbolic name, of type ATOM.
  86 The <emphasis>
  87 XkbGetNames</emphasis>
  88  request reports the symbolic names for all keyboard components, including the
  89 indicators. Use the <emphasis>
  90 XkbSetNames</emphasis>
  91  request to change symbolic names. Both requests are described in <link linkend='Querying_and_Changing_Symbolic_Names'>Querying and Changing Symbolic
  92 Names</link>.
  93 </para>
  94
  95
  96 <sect2 id='Indicator_Maps'>
  97 <title>Indicator Maps</title>
  98
  99 <para>
 100 XKB also provides an <emphasis>
 101 indicator map</emphasis>
 102  for each of the thirty-two keyboard indicators; an indicator map specifies:
 103 </para>
 104
 105 <itemizedlist>
 106 <listitem>
 107   <para>The conditions under which the keyboard modifier state affects the
 108 indicator.
 109   </para>
 110 </listitem>
 111 <listitem>
 112   <para>The conditions under which the keyboard group state affects the
 113 indicator.
 114   </para>
 115 </listitem>
 116 <listitem>
 117   <para>The conditions under which the state of the boolean controls affects
 118 the indicator.
 119   </para>
 120 </listitem>
 121 <listitem>
 122   <para>The effect (if any) of attempts to explicitly change the state of the
 123 indicator using the core protocol <emphasis>
 124 SetKeyboardControl</emphasis>
 125  request.
 126   </para>
 127 </listitem>
 128 </itemizedlist>
 129
 130 <para>
 131 If <emphasis>
 132 IM_NoAutomatic</emphasis>
 133  is set in the <emphasis>
 134 flags</emphasis>
 135  field of an indicator map, that indicator never changes in response to changes
 136 in keyboard state or controls, regardless of the values for the other fields of
 137 the indicator map. If <emphasis>
 138 IM_NoAutomatic</emphasis>
 139  is not set in <emphasis>
 140 flags</emphasis>
 141 , the other fields of the indicator map specify the automatic changes to the
 142 indicator in response to changes in the keyboard state or controls.
 143 </para>
 144
 145
 146 <para>
 147 The <emphasis>
 148 which_groups</emphasis>
 149  and the <emphasis>
 150 groups</emphasis>
 151  fields of an indicator map determine how the keyboard group state affects the
 152 corresponding indicator. The <emphasis>
 153 which_groups</emphasis>
 154  field controls the interpretation of <emphasis>
 155 groups</emphasis>
 156  and may contain any one of the following values:
 157 </para>
 158
 159 <informaltable frame='topbot'>
 160 <?dbfo keep-together="always" ?>
 161 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 162 <colspec colname='c1' colwidth='1.0*'/>
 163 <colspec colname='c2' colwidth='3.0*'/>
 164 <thead>
 165   <row rowsep='1'>
 166     <entry>Value</entry>
 167     <entry>Interpretation of the Groups Field</entry>
 168   </row>
 169 </thead>
 170 <tbody>
 171   <row>
 172     <entry><emphasis>
 173 IM_UseNone</emphasis>
 174 </entry>
 175     <entry>The <emphasis>
 176 groups</emphasis>
 177  field and the current keyboard group state are ignored.</entry>
 178   </row>
 179   <row>
 180     <entry><emphasis>
 181 IM_UseBase</emphasis>
 182 </entry>
 183     <entry>If <emphasis>
 184 groups</emphasis>
 185  is non-zero, the indicator is lit whenever the base keyboard group is
 186 non-zero. If <emphasis>
 187 groups</emphasis>
 188  is zero, the indicator is lit whenever the base keyboard group is zero.</entry>
 189   </row>
 190   <row>
 191     <entry><emphasis>
 192 IM_UseLatched</emphasis>
 193 </entry>
 194     <entry>If <emphasis>
 195 groups</emphasis>
 196  is non-zero, the indicator is lit whenever the latched keyboard group is
 197 non-zero. If <emphasis>
 198 groups</emphasis>
 199  is zero, the indicator is lit whenever the latched keyboard group is
 200 zero.</entry>
 201   </row>
 202   <row>
 203     <entry><emphasis>
 204 IM_UseLocked</emphasis>
 205 </entry>
 206     <entry>The <emphasis>
 207 groups</emphasis>
 208  field is interpreted as a mask. The indicator is lit when the current locked
 209 keyboard group matches one of the bits that are set in <emphasis>
 210 groups</emphasis>
 211 .</entry>
 212   </row>
 213   <row>
 214     <entry><emphasis>
 215 IM_UseEffective</emphasis>
 216 </entry>
 217     <entry>The <emphasis>
 218 groups</emphasis>
 219  field is interpreted as a mask. The indicator is lit when the current
 220 effective keyboard group matches one of the bits that are set in <emphasis>
 221 groups</emphasis>
 222 .</entry>
 223   </row>
 224 </tbody>
 225 </tgroup>
 226 </informaltable>
 227
 228 <para>
 229 The <emphasis>
 230 which_mods</emphasis>
 231  and <emphasis>
 232 mods</emphasis>
 233  fields of an indicator map determine how the state of the keyboard modifiers
 234 affect the corresponding indicator. The <emphasis>
 235 mods</emphasis>
 236  field is an XKB modifier definition, as described in <link linkend='Modifier_Definitions'>Modifier Definitions</link>, which can
 237 specify both real and virtual modifiers. The mods field takes effect even if
 238 some or all of the virtual indicators specified in <emphasis>
 239 mods</emphasis>
 240  are unbound.
 241 </para>
 242
 243
 244 <para>
 245 The <emphasis>
 246 which_mods</emphasis>
 247  field can specify one or more components of the XKB keyboard state. The
 248 corresponding indicator is lit whenever any of the real modifiers specified in
 249 the <emphasis>
 250 mask</emphasis>
 251  field of the <emphasis>
 252 mods</emphasis>
 253  modifier definition are also set in any of the current keyboard state
 254 components specified by the <emphasis>
 255 which_mods</emphasis>
 256 . The <emphasis>
 257 which_mods</emphasis>
 258  field may have any combination of the following values:
 259 </para>
 260
 261 <informaltable frame='topbot'>
 262 <?dbfo keep-together="always" ?>
 263 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 264 <colspec colname='c1' colwidth='1.0*'/>
 265 <colspec colname='c2' colwidth='3.0*'/>
 266 <thead>
 267   <row rowsep='1'>
 268     <entry>Value</entry>
 269     <entry>Keyboard State Component To Be Considered</entry>
 270   </row>
 271 </thead>
 272 <tbody>
 273   <row>
 274     <entry><emphasis>
 275 IM_UseBase</emphasis>
 276 </entry>
 277     <entry>Base modifier state</entry>
 278   </row>
 279   <row>
 280     <entry><emphasis>
 281 IM_UseLatched</emphasis>
 282 </entry>
 283     <entry>Latched modifier state</entry>
 284   </row>
 285   <row>
 286     <entry><emphasis>
 287 IM_UseLocked</emphasis>
 288 </entry>
 289     <entry>Locked modifier state</entry>
 290   </row>
 291   <row>
 292     <entry><emphasis>
 293 IM_UseEffective</emphasis>
 294 </entry>
 295     <entry>Effective modifier state</entry>
 296   </row>
 297   <row>
 298     <entry><emphasis>
 299 IM_UseCompat</emphasis>
 300 </entry>
 301     <entry>Modifier compatibility state</entry>
 302   </row>
 303 </tbody>
 304 </tgroup>
 305 </informaltable>
 306
 307 <para>
 308 The <emphasis>
 309 controls</emphasis>
 310  field specifies a subset of the boolean keyboard controls (see <link linkend='Boolean_Controls_and_The_EnabledControls_Control'>"Boolean" Controls and The
 311 EnabledControls Control</link>). The indicator is lit whenever any of the
 312 boolean controls specified in <emphasis>
 313 controls</emphasis>
 314  are enabled.
 315 </para>
 316
 317
 318 <para>
 319 An indicator is lit whenever any of the conditions specified by its indicator
 320 map are met, unless overridden by the <emphasis>
 321 IM_NoAutomatic</emphasis>
 322  flag (described above) or an explicit indicator change (described below).
 323 </para>
 324
 325
 326 <sect3 id='Effects_of_Explicit_Changes_on_Indicators'>
 327 <title>Effects of Explicit Changes on Indicators</title>
 328
 329 <para>
 330 If the <emphasis>
 331 IM_NoExplicit</emphasis>
 332  flag is set in an indicator map, attempts to change the state of the indicator
 333 are ignored.
 334 </para>
 335
 336
 337 <para>
 338 If both <emphasis>
 339 IM_NoExplicit</emphasis>
 340  and <emphasis>
 341 IM_NoAutomatic</emphasis>
 342  are both absent from an indicator map, requests to change the state of the
 343 indicator are honored but might be immediately superseded by automatic changes
 344 to the indicator state which reflect changes to keyboard state or controls.
 345 </para>
 346
 347
 348 <para>
 349 If the <emphasis>
 350 IM_LEDDrivesKB</emphasis>
 351  flag is set and the <emphasis>
 352 IM_NoExplicit</emphasis>
 353  flag is not, the keyboard state and controls are changed to reflect the other
 354 fields of the indicator map, as described in the remainder of this section.
 355 Attempts to explicitly change the value of an indicator for which <emphasis>
 356 IM_LEDDrivesKB</emphasis>
 357  is absent or for which <emphasis>
 358 IM_NoExplicit</emphasis>
 359  is present do not affect keyboard state or controls.
 360 </para>
 361
 362
 363 <para>
 364 The effect on group state of changing an explicit indicator which drives the
 365 keyboard is determined by the value of <emphasis>
 366 which_groups</emphasis>
 367  and <emphasis>
 368 groups</emphasis>
 369 , as follows:
 370 </para>
 371
 372 <informaltable frame='topbot'>
 373 <?dbfo keep-together="always" ?>
 374 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 375 <colspec colname='c1' colwidth='2.0*'/>
 376 <colspec colname='c2' colwidth='1.0*'/>
 377 <colspec colname='c3' colwidth='2.0*'/>
 378 <thead>
 379   <row rowsep='1'>
 380     <entry> which_groups</entry>
 381     <entry>New State</entry>
 382     <entry>Effect on Keyboard Group State</entry>
 383   </row>
 384 </thead>
 385 <tbody>
 386   <row>
 387     <entry><emphasis>
 388 IM_UseNone</emphasis>
 389 , or <emphasis>
 390 IM_UseBase</emphasis>
 391 </entry>
 392     <entry>On or Off</entry>
 393     <entry>No Effect</entry>
 394   </row>
 395   <row>
 396     <entry><emphasis>
 397 IM_UseLatched</emphasis>
 398 </entry>
 399     <entry>On</entry>
 400     <entry>The <emphasis>
 401 groups</emphasis>
 402  field is treated as a group mask. The keyboard group latch is changed to the
 403 lowest numbered group specified in <emphasis>
 404 groups</emphasis>
 405 ; if <emphasis>
 406 groups</emphasis>
 407  is empty, the keyboard group latch is changed to zero.</entry>
 408   </row>
 409   <row>
 410     <entry>IM_UseLatched</entry>
 411     <entry>Off</entry>
 412     <entry>The <emphasis>
 413 groups</emphasis>
 414  field is treated as a group mask. If the indicator is explicitly extinguished,
 415 keyboard group latch is changed to the lowest numbered group not specified in
 416 <emphasis>
 417 groups</emphasis>
 418 ; if <emphasis>
 419 groups</emphasis>
 420  is zero, the keyboard group latch is set to the index of the highest legal
 421 keyboard group.</entry>
 422   </row>
 423   <row>
 424     <entry><emphasis>
 425 IM_UseLocked</emphasis>
 426 , or <emphasis>
 427 IM_UseEffective</emphasis>
 428 </entry>
 429     <entry>On</entry>
 430     <entry>If the <emphasis>
 431 groups</emphasis>
 432  mask is empty, group is not changed, otherwise the locked keyboard group is
 433 changed to the lowest numbered group specified in <emphasis>
 434 groups</emphasis>
 435 .</entry>
 436   </row>
 437   <row>
 438     <entry><emphasis>
 439 IM_UseLocked</emphasis>
 440 , or <emphasis>
 441 IM_UseEffective</emphasis>
 442 </entry>
 443     <entry>Off</entry>
 444     <entry>Locked keyboard group is changed to the lowest numbered group that
 445 is not specified in the <emphasis>
 446 groups</emphasis>
 447  mask, or to <emphasis>
 448 Group1</emphasis>
 449  if the <emphasis>
 450 groups</emphasis>
 451  mask contains all keyboard groups.</entry>
 452   </row>
 453 </tbody>
 454 </tgroup>
 455 </informaltable>
 456
 457 <para>
 458 The effect on the keyboard modifiers of changing an explicit indicator which
 459 drives the keyboard is determined by the values that are set in of <emphasis>
 460 which_mods</emphasis>
 461  and <emphasis>
 462 mods</emphasis>
 463 , as follows:
 464 </para>
 465
 466 <informaltable frame='topbot'>
 467 <?dbfo keep-together="always" ?>
 468 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 469 <colspec colname='c1' colwidth='1.0*'/>
 470 <colspec colname='c2' colwidth='1.0*'/>
 471 <colspec colname='c3' colwidth='3.0*'/>
 472 <thead>
 473   <row rowsep='1'>
 474     <entry>Set in which_mods</entry>
 475     <entry>New State</entry>
 476     <entry>Effect on Keyboard Modifiers</entry>
 477   </row>
 478 </thead>
 479 <tbody>
 480   <row>
 481     <entry><emphasis>
 482 IM_UseBase</emphasis>
 483 </entry>
 484     <entry>On or Off</entry>
 485     <entry>No Effect</entry>
 486   </row>
 487   <row>
 488     <entry><emphasis>
 489 IM_UseLatched</emphasis>
 490 </entry>
 491     <entry>On</entry>
 492     <entry>Any modifiers specified in the <emphasis>
 493 mask</emphasis>
 494  field of <emphasis>
 495 mods</emphasis>
 496  are added to the latched modifiers.</entry>
 497   </row>
 498   <row>
 499     <entry><emphasis>
 500 IM_UseLatched</emphasis>
 501 </entry>
 502     <entry>Off</entry>
 503     <entry>Any modifiers specified in the <emphasis>
 504 mask</emphasis>
 505  field of <emphasis>
 506 mods</emphasis>
 507  are removed from the latched modifiers.</entry>
 508   </row>
 509   <row>
 510     <entry><emphasis>
 511 IM_UseLocked</emphasis>
 512 , <emphasis>
 513 IM_UseCompat</emphasis>
 514 , or <emphasis>
 515 IM_UseEffective</emphasis>
 516 </entry>
 517     <entry>On</entry>
 518     <entry>Any modifiers specified in the <emphasis>
 519 mask</emphasis>
 520  field of <emphasis>
 521 mods</emphasis>
 522  are added to the locked modifiers.</entry>
 523   </row>
 524   <row>
 525     <entry><emphasis>
 526 IM_UseLocked</emphasis>
 527 </entry>
 528     <entry>Off</entry>
 529     <entry>Any modifiers specified in the <emphasis>
 530 mask</emphasis>
 531  field of <emphasis>
 532 mods</emphasis>
 533  are removed from the locked modifiers.</entry>
 534   </row>
 535   <row>
 536     <entry><emphasis>
 537 IM_UseCompat</emphasis>
 538 , or <emphasis>
 539 IM_UseEffective</emphasis>
 540 </entry>
 541     <entry>Off</entry>
 542     <entry>Any modifiers specified in the <emphasis>
 543 mask</emphasis>
 544  field of <emphasis>
 545 mods</emphasis>
 546  are removed from both the locked and latched modifiers.</entry>
 547   </row>
 548 </tbody>
 549 </tgroup>
 550 </informaltable>
 551
 552 <para>
 553 Lighting an explicit indicator which drives the keyboard also enables all of
 554 the boolean controls specified in the <emphasis>
 555 controls</emphasis>
 556  field of its indicator map. Explicitly extinguishing such an indicator
 557 disables all of the boolean controls specified in <emphasis>
 558 controls</emphasis>
 559 .
 560 </para>
 561
 562
 563 <para>
 564 The effects of changing an indicator which drives the keyboard are cumulative;
 565 it is possible for a single change to affect keyboard group, modifiers and
 566 controls simultaneously.
 567 </para>
 568
 569
 570 <para>
 571 If an indicator for which both the <emphasis>
 572 IM_LEDDrivesKB</emphasis>
 573  and <emphasis>
 574 IM_NoAutomatic</emphasis>
 575  flags are specified is changed, the keyboard changes specified above are
 576 applied and the indicator is changed to reflect the state that was explicitly
 577 requested. The indicator will remain in the new state until it is explicitly
 578 changed again.
 579 </para>
 580
 581
 582 <para>
 583 If the <emphasis>
 584 IM_NoAutomatic</emphasis>
 585  flag is not set for an indicator which drives the keyboard, the changes
 586 specified above are applied and the state of the indicator is set to the values
 587 specified by the indicator map. Note that it is possible in this case for the
 588 indicator to end up in a different state than the one that was explicitly
 589 requested. For example, an indicator with <emphasis>
 590 which_mods</emphasis>
 591  of <emphasis>
 592 IM_UseBase</emphasis>
 593  and <emphasis>
 594 mods</emphasis>
 595  of <emphasis>
 596 Shift</emphasis>
 597  is not extinguished if one of the <emphasis>
 598 Shift</emphasis>
 599  keys is physically depressed when the request to extinguish the indicator is
 600 processed.
 601 </para>
 602 </sect3>
 603 </sect2>
 604 </sect1>
 605 </chapter>