1<chapter id='Virtual_Modifiers'> 2<title>Virtual Modifiers</title> 3<para> 4The core protocol specifies that 5certain keysyms, when bound to modifiers, affect the rules of keycode to keysym 6interpretation for all keys; for example, when <emphasis> 7Num_Lock</emphasis> 8 is bound to some modifier, that modifier is used to choose shifted or 9unshifted state for the numeric keypad keys. The core protocol does not provide 10a convenient way to determine the mapping of modifier bits, in particular 11<emphasis> 12Mod1</emphasis> 13 through <emphasis> 14Mod5</emphasis> 15, to keysyms such as <emphasis> 16Num_Lock</emphasis> 17 and <emphasis> 18Mode_switch</emphasis> 19. Clients must retrieve and search the modifier map to determine the keycodes 20bound to each modifier, and then retrieve and search the keyboard mapping to 21determine the keysyms bound to the keycodes. They must repeat this process for 22all modifiers whenever any part of the modifier mapping is changed. 23</para> 24 25<para> 26XKB provides a set of sixteen named virtual modifiers, each of which can be 27bound to any set of the eight "real" modifiers (<emphasis> 28Shift</emphasis> 29, <emphasis> 30Lock</emphasis> 31, <emphasis> 32Control</emphasis> 33 and <emphasis> 34Mod1</emphasis> 35-<emphasis> 36Mod5</emphasis> 37 as reported in the keyboard state). This makes it easier for applications and 38keyboard layout designers to specify to the function a modifier key or data 39structure should fulfill without having to worry about which modifier is bound 40to a particular keysym. 41</para> 42 43 44<para> 45The use of a single, server-driven mechanism for reporting changes to all data 46structures makes it easier for clients to stay synchronized. For example, the 47core protocol specifies a special interpretation for the modifier bound to the 48<emphasis> 49Num_Lock</emphasis> 50 key. Whenever any keys or modifiers are rebound, every application has to 51check the keyboard mapping to make sure that the binding for <emphasis> 52Num_Lock</emphasis> 53 has not changed. If <emphasis> 54Num_Lock</emphasis> 55 is remapped when XKB is in use, the keyboard description is automatically 56updated to reflect the new binding, and clients are notified immediately and 57explicitly if there is a change they need to consider. 58</para> 59 60 61<para> 62The separation of function from physical modifier bindings also makes it easier 63to specify more clearly the intent of a binding. X servers do not all assign 64modifiers the same way — for example, <emphasis> 65Num_Lock</emphasis> 66 might be bound to <emphasis> 67Mod2</emphasis> 68 for one vendor and to <emphasis> 69Mod4</emphasis> 70 for another. This makes it cumbersome to automatically remap the keyboard to a 71desired configuration without some kind of prior knowledge about the keyboard 72layout and bindings. With XKB, applications simply use virtual modifiers to 73specify the behavior they want, without regard for the actual physical bindings 74in effect. 75</para> 76 77 78<para> 79XKB puts most aspects of the keyboard under user or program control, so it is 80even more important to clearly and uniformly refer to modifiers by function. 81</para> 82 83<sect1 id='Modifier_Definitions'> 84<title>Modifier Definitions</title> 85<para> 86Use an <emphasis> 87XKB modifier definition</emphasis> 88 to specify the modifiers affected by any XKB control or data structure. An XKB 89modifier definition consists of a set of real modifiers, a set of virtual 90modifiers, and an effective mask. The mask is derived from the real and virtual 91modifiers and cannot be explicitly changed — it contains all of the real 92modifiers specified in the definition <emphasis> 93plus</emphasis> 94 any real modifiers that are bound to the virtual modifiers specified in the 95definition. For example, this modifier definition specifies the numeric lock 96modifier if the <emphasis> 97Num_Lock</emphasis> 98 keysym is not bound to any real modifier: 99</para> 100<literallayout class='monospaced'> 101{ real_mods= None, virtual_mods= NumLock, mask= None } 102</literallayout> 103 104<para> 105If we assign <emphasis> 106Mod2</emphasis> 107 to the <emphasis> 108Num_Lock</emphasis> 109 key, the definition changes to: 110</para> 111 112<literallayout class='monospaced'> 113{ real_mods= None, virtual_mods= NumLock, mask= Mod2 } 114</literallayout> 115 116<para> 117Using this kind of modifier definition makes it easy to specify the desired 118behavior in such a way that XKB can automatically update all of the data 119structures that make up a keymap to reflect user or application specified 120changes in any one aspect of the keymap. 121</para> 122 123 124<para> 125The use of modifier definitions also makes it possible to unambiguously specify 126the reason that a modifier is of interest. On a system for which the <emphasis> 127Alt</emphasis> 128 and <emphasis> 129Meta</emphasis> 130 keysyms are bound to the same modifier, the following definitions behave 131identically: 132</para> 133 134<literallayout class='monospaced'> 135{ real_mods= None, virtual_mods= Alt, mask= Mod1 } 136{ real_mods= None, virtual_mods= Meta, mask= Mod1 } 137</literallayout> 138 139<para> 140If we rebind one of the modifiers, the modifier definitions automatically 141reflect the change: 142</para> 143 144<literallayout class='monospaced'> 145{ real_mods= None, virtual_mods= Alt, mask= Mod1 } 146{ real_mods= None, virtual_mods= Meta, mask= Mod4 } 147</literallayout> 148 149<para> 150Without the level of indirection provided by virtual modifier maps and modifier 151definitions, we would have no way to tell which of the two definitions is 152concerned with <emphasis> 153Alt</emphasis> 154 and which is concerned with <emphasis> 155Meta</emphasis>. 156</para> 157 158 159<sect2 id='Inactive_Modifier_Definitions'> 160<title>Inactive Modifier Definitions</title> 161<para> 162Some XKB structures ignore modifier 163definitions in which the virtual modifiers are unbound. Consider this 164example: 165</para> 166<literallayout class='monospaced'> 167if ( state matches { Shift } ) Do OneThing; 168if ( state matches { Shift+NumLock } ) Do Another; 169</literallayout> 170 171<para> 172If the <emphasis> 173NumLock</emphasis> 174 virtual modifier is not bound to any real modifiers, these effective masks for 175these two cases are identical (i.e. they contain only <emphasis> 176Shift</emphasis> 177). When it is essential to distinguish between <emphasis> 178OneThing</emphasis> 179 and Another, XKB considers only those modifier definitions for which all 180virtual modifiers are bound. 181</para> 182</sect2> 183</sect1> 184 185<sect1 id='Virtual_Modifier_Mapping'> 186<title>Virtual Modifier Mapping</title> 187<para> 188XKB maintains a <emphasis> 189virtual modifier mapping</emphasis> 190, which lists the virtual modifiers associated with each key. The real 191modifiers bound to a virtual modifier always include all of the modifiers bound 192to any of the keys that specify that virtual modifier in their virtual modifier 193mapping. 194</para> 195 196<para> 197For example, if <emphasis> 198Mod3</emphasis> 199 is bound to the <emphasis> 200Num_Lock</emphasis> 201 key by the core protocol modifier mapping, and the <emphasis> 202NumLock</emphasis> 203 virtual modifier is bound to they <emphasis> 204Num_Lock</emphasis> 205 key by the virtual modifier mapping, <emphasis> 206Mod3</emphasis> 207 is added to the set of modifiers associated with the <emphasis> 208NumLock</emphasis> 209 virtual modifier. 210</para> 211 212 213<para> 214The virtual modifier mapping is normally updated automatically whenever actions 215are assigned to keys (see <link linkend='Changing_the_Keyboard_Mapping_Using_the_Core_Protocol'>Changing 216the Keyboard Mapping Using the Core Protocol</link> for details) and few 217applications should need to change the virtual modifier mapping explicitly. 218</para> 219</sect1> 220</chapter> 221