1<chapter id='Keyboard_State'> 2<title>Keyboard State</title> 3<para> 4The core protocol description of 5keyboard state consists of eight <emphasis> 6modifiers</emphasis> 7(<emphasis> 8Shift</emphasis> 9, <emphasis> 10Lock</emphasis> 11, <emphasis> 12Control</emphasis> 13, and <emphasis> 14Mod1</emphasis> 15-<emphasis> 16Mod5</emphasis> 17). A modifier reports the state of one or modifier keys, which are similar to 18qualifier keys as defined by the ISO9995 standard: 19</para> 20 21<variablelist> 22 <varlistentry> 23 <term>Qualifier key</term> 24 <listitem> 25 <para> 26A key whose operation 27has no immediate effect, but which, for as long as it is held down, modifies 28the effect of other keys. A qualifier key may be, for example, a shift key or a 29control key. 30 </para> 31 </listitem> 32 </varlistentry> 33</variablelist> 34 35<para> 36Whenever a modifier key is physically or logically depressed, the modifier it 37controls is set in the keyboard state. The protocol implies that certain 38modifier keys lock (i.e. affect modifier state after they have been physically 39released) but does not explicitly discuss locking keys or their behavior. The 40current modifier state is reported to clients in a number of core protocol 41events and can be determined using the <emphasis> 42QueryPointer</emphasis> 43 request. 44</para> 45 46<para> 47The XKB extension retains the eight "real" modifiers defined by the core 48protocol but extends the core protocol notion of <emphasis> 49keyboard state</emphasis> 50 to include up to four <emphasis> 51keysym groups</emphasis> 52, as defined by the ISO9995 standard: 53</para> 54 55 56<variablelist> 57 <varlistentry> 58 <term>Group:</term> 59 <listitem> 60 <para> 61A logical state of a keyboard providing 62access to a collection of characters. A group usually contains a set of 63characters which logically belong together and which may be arranged on several 64shift levels within that group. 65 </para> 66 </listitem> 67 </varlistentry> 68</variablelist> 69 70<para> 71For example, keyboard group can be used to select between multiple alphabets on 72a single keyboard, or to access less-commonly used symbols within a character 73set. 74</para> 75 76<sect1 id='Locking_and_Latching_Modifiers_and_Groups'> 77<title>Locking and Latching Modifiers and Groups</title> 78<para> 79With the core protocol, there is no way to 80tell whether a modifier is set due to a lock or because the user is actually 81holding down a key; this can make for a clumsy user-interface as locked 82modifiers or group state interfere with accelerators and translations. 83</para> 84<para> 85XKB adds explicit support for locking 86and latching modifiers and groups. Locked modifiers or groups apply to all 87future key events until they are explicitly changed. Latched modifiers or 88groups apply only to the next key event that does not change keyboard state. 89</para> 90 91</sect1> 92<sect1 id='Fundamental_Components_of_XKB_Keyboard_State'> 93<title>Fundamental Components of XKB Keyboard State</title> 94<para> 95The fundamental components of XKB keyboard state include: 96</para> 97 98<itemizedlist> 99<listitem> 100 <para>The locked modifiers and group</para> 101</listitem> 102<listitem> 103 <para>The latched modifiers and group</para> 104</listitem> 105<listitem> 106 <para>The base modifiers and group (for which keys are physically or 107logically down) 108 </para> 109</listitem> 110<listitem> 111 <para>The effective modifiers and group (the cumulative effect of the base, 112locked and latched modifier and group states). 113 </para> 114</listitem> 115<listitem> 116 <para>State of the core pointer buttons.</para> 117</listitem> 118</itemizedlist> 119 120<para> 121The latched and locked state of modifiers and groups can be changed in response 122to keyboard activity or under application control using the <emphasis> 123XkbLatchLockState</emphasis> 124 request. The base modifier, base group 125and pointer button states always reflect the logical state of the keyboard and 126pointer and change <emphasis> 127only</emphasis> 128 in response to keyboard or pointer activity. 129</para> 130 131<sect2 id='Computing_Effective_Modifier_and_Group'> 132<title>Computing Effective Modifier and Group</title> 133<para> 134The effective modifiers and group 135report the cumulative effects of the base, latched and locked modifiers and 136group respectively, and cannot be directly changed. Note that the effective 137modifiers and effective group are computed differently. 138</para> 139 140<para> 141The effective modifiers are simply the bitwise union of the base, latched and 142locked modifiers. 143</para> 144 145 146<para> 147The effective group is the arithmetic sum of the base, latched and locked 148groups. The locked and effective keyboard group must fall in the range 149<emphasis> 150Group1</emphasis> 151-<emphasis> 152Group4</emphasis> 153, so they are adjusted into range as specified by the global <emphasis> 154GroupsWrap </emphasis> 155control as follows: 156</para> 157 158<itemizedlist> 159 <listitem> 160 <para> 161If the <emphasis> 162RedirectIntoRange</emphasis> 163 flag is set, the four least significant 164bits of the groups wrap control specify the index of a group to which all 165illegal groups correspond. If the specified group is also out of range, all 166illegal groups map to <emphasis> 167Group1</emphasis>. 168 </para> 169 </listitem> 170 <listitem> 171 <para> 172If the <emphasis> 173ClampIntoRange</emphasis> 174 flag is set, out-of-range groups 175correspond to the nearest legal group. Effective groups larger than the highest 176supported group are mapped to the highest supported group; effective groups 177less than <emphasis> 178Group1</emphasis> 179 are mapped to <emphasis> 180Group1</emphasis> 181. For example, a key with two groups of symbols uses <emphasis> 182Group2</emphasis> 183 type and symbols if the global effective group is either <emphasis> 184Group3</emphasis> 185 or <emphasis> 186Group4</emphasis>. 187 </para> 188 </listitem> 189 <listitem> 190 <para> 191If neither flag is set, group is 192wrapped into range using integer modulus. For example, a key with two groups of 193symbols for which groups wrap uses <emphasis> 194Group1</emphasis> 195 symbols if the global effective group is <emphasis> 196Group3</emphasis> 197 or <emphasis> 198Group2</emphasis> 199 symbols if the global effective group is <emphasis> 200Group4</emphasis>. 201 </para> 202 </listitem> 203</itemizedlist> 204 205<para> 206The base and latched keyboard groups are unrestricted eight-bit integer values 207and are not affected by the <emphasis> 208GroupsWrap</emphasis> 209 control. 210</para> 211 212</sect2> 213 214<sect2 id='Computing_A_State_Field_from_an_XKB_State'> 215<title>Computing A State Field from an XKB State</title> 216<para> 217Many events report the keyboard state 218in a single <emphasis> 219state</emphasis> 220 field. Using XKB, a state field combines modifiers, group and the pointer 221button state into a single sixteen bit value as follows: 222</para> 223 224<itemizedlist> 225<listitem> 226 <para>Bits 0 through 7 (the least significant eight bits) of the effective 227state comprise a mask of type KEYMASK which reports the state modifiers. 228 </para> 229</listitem> 230<listitem> 231 <para>Bits 8 through 12 comprise a mask of type BUTMASK which reports pointer 232button state. 233 </para> 234</listitem> 235<listitem> 236 <para>Bits 13 and 14 are interpreted as a two-bit unsigned numeric value and 237report the state keyboard group. 238 </para> 239</listitem> 240<listitem> 241 <para>Bit 15 (the most significant bit) is reserved and must be zero. 242 </para> 243</listitem> 244</itemizedlist> 245 246<para> 247It is possible to assemble a state field from any of the components of the XKB 248keyboard state. For example, the effective keyboard state would be assembled as 249described above using the effective keyboard group, the effective keyboard 250modifiers and the pointer button state. 251</para> 252 253</sect2> 254</sect1> 255 256<sect1 id='Derived_Components_of_XKB_Keyboard_State'> 257<title>Derived Components of XKB Keyboard State</title> 258<para> 259In addition to the fundamental state 260components, XKB keeps track of and reports a number of state components which 261are derived from the fundamental components but stored and reported separately 262to make it easier to track changes in the keyboard state. These derived 263components are updated automatically whenever any of the fundamental components 264change but cannot be changed directly. 265</para> 266 267<para> 268The first pair of derived state components control the way that passive grabs 269are activated and the way that modifiers are reported in core protocol events 270that report state. The server uses the <emphasis> 271ServerInternalModifiers</emphasis> 272, <emphasis> 273IgnoreLocksModifiers</emphasis> 274 and <emphasis> 275IgnoreGroupLock</emphasis> 276 controls, described in <link linkend='Server_Internal_Modifiers_and_Ignore_Locks_Behavior'>Server 277Internal Modifiers and Ignore Locks Behavior</link>, to derive these two 278states as follows: 279</para> 280 281<itemizedlist> 282<listitem> 283 <para>The lookup state is the state used to determine the symbols associated 284with a key event and consists of the effective state minus any server internal 285modifiers. 286 </para> 287</listitem> 288<listitem> 289 <para>The grab state is the state used to decide whether a particular event 290triggers a passive grab and consists of the lookup state minus any members of 291the ignore locks modifiers that are not either latched or logically depressed. 292If the ignore group locks control is set, the grab state does not include the 293effects of any locked groups. 294 </para> 295</listitem> 296</itemizedlist> 297 298<sect2 id='Server_Internal_Modifiers_and_Ignore_Locks_Behavior'> 299<title>Server Internal Modifiers and Ignore Locks Behavior</title> 300<para> 301The core protocol does not provide any 302way to exclude certain modifiers from client events, so there is no way to set 303up a modifier which affects only the server. 304</para> 305 306<para> 307The modifiers specified in the mask of the <emphasis> 308InternalMods</emphasis> 309 control are not reported in any core 310protocol events, are not used to determine grabs and are not used to calculate 311compatibility state for XKB-unaware clients. Server internal modifiers affect 312only the action applied when a key is pressed. 313</para> 314 315 316<para> 317The core protocol does not provide any way to exclude certain modifiers from 318grab calculations, so locking modifiers often have unanticipated and 319unfortunate side-effects. XKB provides another mask which can help avoid some 320of these problems. 321</para> 322 323 324<para> 325The locked state of the modifiers specified in mask of the <emphasis> 326IgnoreLockMods</emphasis> 327 control is not reported in most core 328protocol events and is not used to activate grabs. The only core events which 329include the locked state of the modifiers in the ignore locks mask are key 330press and release events that do not activate a passive grab and which do not 331occur while a grab is active. If the <emphasis> 332IgnoreGroupLock</emphasis> 333 control is set, the locked state of the 334keyboard group is not considered when activating passive grabs. 335</para> 336 337 338<para> 339Without XKB, the passive grab set by a translation (e.g. <emphasis> 340Alt<KeyPress>space</emphasis> 341) does not trigger if any modifiers other than those specified by the 342translation are set, with the result that many user interface components do not 343react when either Num Lock or when the secondary keyboard group are active. The 344ignore locks mask and the ignore group locks control make it possible to avoid 345this behavior without exhaustively grabbing every possible modifier combination. 346</para> 347 348 349</sect2> 350</sect1> 351<sect1 id='Compatibility_Components_of_Keyboard_State'> 352<title>Compatibility Components of Keyboard State</title> 353<para> 354The core protocol interpretation of 355keyboard modifiers does not include direct support for multiple groups, so XKB 356reports the effective keyboard group to XKB-aware clients using some of the 357reserved bits in the state field of some core protocol events, as described in 358<link linkend='Computing_A_State_Field_from_an_XKB_State'>Computing A State Field from an 359XKB State</link>. 360</para> 361 362<para> 363This modified state field would not be interpreted correctly by XKB-unaware 364clients, so XKB provides a <emphasis> 365group compatibility mapping</emphasis> 366(see <link linkend='Group_Compatibility_Map'>Group Compatibility Map</link>) which 367remaps the keyboard group into a core modifier mask that has similar effects, 368when possible. XKB maintains three compatibility state components that are used 369to make non-XKB clients work as well as possible: 370</para> 371 372<itemizedlist> 373 <listitem> 374 <para> 375The <emphasis> 376compatibility state</emphasis> 377 corresponds to the effective modifier 378and effective group state. 379 </para> 380 </listitem> 381 <listitem> 382 <para> 383The <emphasis> 384compatibility lookup state</emphasis> 385 is the core-protocol equivalent of the 386lookup state. 387 </para> 388 </listitem> 389 <listitem> 390 <para> 391The <emphasis> 392compatibility grab state</emphasis> 393 is the nearest core-protocol equivalent 394of the grab state. 395 </para> 396 </listitem> 397</itemizedlist> 398 399<para> 400Compatibility states are essentially the corresponding XKB state, but with 401keyboard group possibly encoded as one or more modifiers; <link linkend='Group_Compatibility_Map'>Group Compatibility Map</link> describes 402the group compatibility map, which specifies the modifier(s) that correspond to 403each keyboard group. 404</para> 405 406 407<para> 408The compatibility state reported to XKB-unaware 409 clients for any given core protocol event 410is computed from the modifier state that XKB-capable clients would see for that 411same event. For example, if the ignore group locks control is set and group 2 412is locked, the modifier bound to <emphasis> 413Mode_switch</emphasis> 414 is not reported in any event except (Device)KeyPress and (Device)KeyRelease 415events that do not trigger a passive grab. 416</para> 417 418<note> 419<para> 420Referring to clients as "XKB-capable 421 is somewhat misleading in this context. 422The sample implementation of XKB invisibly extends the X library to use the 423keyboard extension if it is present. This means that most clients can take 424advantage of all of XKB without modification, but it also means that the XKB 425state can be reported to clients that have not explicitly requested the 426keyboard extension. Clients that <emphasis> 427directly</emphasis> 428 interpret the state field of core protocol events or that interpret the keymap 429directly may be affected by some of the XKB differences; clients that use 430library or toolkit routines to interpret keyboard events automatically use all 431of the XKB features. 432</para> 433</note> 434 435<para> 436XKB-aware clients can query the keyboard state at any time or request immediate 437notification of a change to any of the fundamental or derived components of the 438keyboard state. 439</para> 440</sect1> 441</chapter> 442