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