1<chapter id='Symbolic_Names'>
2<title>Symbolic Names</title>
3
4<para>
5The core protocol does not provide any information to clients other than that
6actually used to interpret events. This makes it difficult to write a client
7which presents the keyboard to a user in an easy-to-understand way. Such
8applications have to examine the vendor string and keycodes to determine the
9type of keyboard connected to the server and have to examine keysyms and
10modifier mappings to determine the effects of most modifiers (the <emphasis>
11Shift</emphasis>
12, <emphasis>
13Lock</emphasis>
14 and <emphasis>
15Control</emphasis>
16 modifiers are defined by the core protocol but no semantics are implied for
17any other modifiers).
18</para>
19
20
21<para>
22This extension provides such applications with symbolic names for most
23components of the keyboard extension and a description of the physical layout
24of the keyboard.
25</para>
26
27
28<para>
29The <emphasis>
30keycodes</emphasis>
31 name describes the range and meaning of the keycodes returned by the keyboard
32in question; the <emphasis>
33keyboard</emphasis>
34 <emphasis>
35geometry </emphasis>
36name describes the physical location, size and shape of the various keys on the
37keyboard. As an example to distinguish between these two names, consider
38function keys on PC-compatible keyboards. Function keys are sometimes above the
39main keyboard and sometimes to the left of the main keyboard, but the same
40keycode is used for the key that is logically <emphasis>
41F1</emphasis>
42 regardless of physical position. Thus, all PC-compatible keyboards might share
43a keycodes name but different geometry names.
44</para>
45
46<note><para>The keycodes name is intended to be a very general description of
47the keycodes returned by a keyboard; A single keycodes name might cover
48keyboards with differing numbers of keys provided that the keys that all keys
49have the same semantics when present. For example, 101 and 102 key PC keyboards
50might use the same name. Applications can use the keyboard geometry to
51determine which subset of the named keyboard type is in use.</para></note>
52
53<para>
54The <emphasis>
55symbols</emphasis>
56 name identifies the symbols bound to the keys. The symbols name is a human or
57application-readable description of the intended locale or usage of the
58keyboard with these symbols. The <emphasis>
59physical symbols</emphasis>
60 name describes the symbols actually engraved on the keyboard, which might be
61different than the symbols currently being used.
62</para>
63
64
65<para>
66The <emphasis>
67types</emphasis>
68 name provides some information about the set of key types that can be
69associated with the keyboard keys. The <emphasis>
70compat</emphasis>
71 name provides some information about the rules used to bind actions to keys
72changed using core protocol requests.
73</para>
74
75
76<para>
77The <emphasis>
78compat</emphasis>
79, <emphasis>
80types</emphasis>
81, <emphasis>
82keycodes</emphasis>
83, <emphasis>
84symbols</emphasis>
85 and <emphasis>
86geometry</emphasis>
87 names typically correspond to the keyboard components from which the current
88keyboard description was assembled. These components are stored individually in
89the server’s database of keyboard components, described in
90<link linkend='The_Server_Database_of_Keyboard_Components'>
91The Server Database of Keyboard
92Components</link>, and can be combined to assemble a complete keyboard
93description.
94</para>
95
96
97<para>
98Each key has a four-byte symbolic name. The key name links keys with similar
99functions or in similar positions on keyboards that report different scan
100codes. <emphasis>
101Key aliases</emphasis>
102 allow the keyboard layout designer to assign multiple names to a single key,
103to make it easier to refer to keys using either their position <emphasis>
104or</emphasis>
105 their "function."
106</para>
107
108
109<para>
110For example, consider the common keyboard customizations:
111</para>
112
113<itemizedlist>
114<listitem>
115  <para>Set the "key to the left of the letter a" to be a control key.
116  </para>
117</listitem>
118<listitem>
119  <para>Change the "caps lock" key, wherever it might be, to a control key.
120  </para>
121</listitem>
122</itemizedlist>
123
124<para>
125If we specify key names by position, the first customization is simple but the
126second is impossible; if we specify key names by function, the second
127customization is simple but the first is impossible. Using key aliases, we can
128specify both function and position for "troublesome" keys, and both
129customizations are straightforward.
130</para>
131
132
133<para>
134Key aliases can be specified both in the symbolic names component and in the
135keyboard geometry (see <link linkend='Keyboard_Geometry'>Keyboard
136Geometry</link>). Both sets of aliases are always valid, but key alias
137definitions in the keyboard geometry have priority; if both symbolic names and
138geometry include aliases, applications should consider the definitions from the
139geometry before considering the definitions from the symbolic names section.
140</para>
141
142
143<para>
144XKB provides symbolic names for each of the four keyboard groups, sixteen
145virtual modifiers, thirty-two keyboard indicators, and up to <emphasis>
146MaxRadioGroups</emphasis>
147 (32) radio groups.
148</para>
149
150
151<para>
152XKB allows keyboard layout designers or editors to assign names to each key
153type and to each of the levels in a key type. For example, the second position
154on an alphabetic key might be called the "Caps" level while the second position
155on a numeric keypad key might be called the "Num Lock" level.
156</para>
157</chapter>
158