specs/ch13.xml

   1 <chapter id='The_Server_Database_of_Keyboard_Components'>
   2 <title>The Server Database of Keyboard Components</title>
   3
   4 <para>
   5 The X server maintains a database of keyboard components and common keyboard
   6 mappings. This database contains five kinds of components; when combined, these
   7 five components provide a complete description of a keyboard and its behavior.
   8 </para>
   9
  10
  11 <para>
  12 The X Keyboard Extension provides requests to list the contents of this
  13 database, to assemble and complete keyboard descriptions by merging the current
  14 keyboard description with the contents of this database, or to replace the
  15 current keyboard description with a complete keyboard description assembled as
  16 described below.
  17 </para>
  18
  19 <sect1 id='Component_Names'>
  20 <title>Component Names</title>
  21
  22 <para>
  23 Component and keymap names have the form "<emphasis>
  24 class</emphasis>
  25 (<emphasis>
  26 member</emphasis>
  27 )" where <emphasis>
  28 class</emphasis>
  29  describes a subset of the available components for a particular type and the
  30 optional <emphasis>
  31 member</emphasis>
  32  identifies a specific component from that subset. For example, the name
  33 "atlantis(acme)" might specify the symbols used for the atlantis national
  34 keyboard layout by the vendor "acme." Each class has an optional <emphasis>
  35 default</emphasis>
  36  member — references which specify a class but not a member refer to the
  37 default member of the class, if one exists.
  38 </para>
  39
  40
  41 <para>
  42 The <emphasis>
  43 class</emphasis>
  44  and <emphasis>
  45 member</emphasis>
  46  names are both specified using characters from the Latin-1 character set. XKB
  47 implementations must accept all alphanumeric characters, minus (‘-’) and
  48 underscore (‘_’) in class or member names, and must not accept parentheses,
  49 plus, vertical bar, percent sign, asterisk, question mark or white space. The
  50 use of other characters is implementation-dependent.
  51 </para>
  52
  53
  54 </sect1>
  55 <sect1 id='Partial_Components_and_Combining_Multiple_Components'>
  56 <title>Partial Components and Combining Multiple Components</title>
  57
  58 <para>
  59 Some of the elements in the server database contain describe only a piece of
  60 the corresponding keyboard component. These <emphasis>
  61 partial</emphasis>
  62  components should be combined with other components of the same type to be
  63 useful.
  64 </para>
  65
  66
  67 <para>
  68 For example, a partial symbols map might describe the differences between a
  69 common ASCII keyboard and some national layout. Such a partial map is not
  70 useful on its own because it does not include those symbols that are the same
  71 on both the ASCII and national layouts (such as function keys). On the other
  72 hand, this partial map can configure <emphasis>
  73 any</emphasis>
  74  ASCII keyboard to use a national layout.
  75 </para>
  76
  77
  78 <para>
  79 Two components can be combined in two ways:
  80 </para>
  81
  82 <itemizedlist>
  83 <listitem>
  84   <para>If the second component <emphasis>
  85 overrides</emphasis>
  86  the first, any definitions that are present in both components are taken from
  87 the second.
  88   </para>
  89 </listitem>
  90 <listitem>
  91   <para>If the second component <emphasis>
  92 augments</emphasis>
  93  the first, any definitions that are present in both components are taken from
  94 the first.
  95   </para>
  96 </listitem>
  97 </itemizedlist>
  98
  99 <para>
 100 Applications can use a <emphasis>
 101 component expression</emphasis>
 102  to combine multiple components of some time into a complete description of
 103 some aspect of the keyboard. A component expression is a string which lists the
 104 components to be combined separated by operators which specify the rules for
 105 combining them. A complete description is assembled from the listed components,
 106 left to right, as follows:
 107 </para>
 108
 109 <itemizedlist>
 110 <listitem>
 111   <para>If the new elements are being merged with an existing map, the special
 112 component name ‘%’ refers to the unmodified value of the map.
 113   </para>
 114 </listitem>
 115 <listitem>
 116   <para>The ‘+’ operator specifies that the next specified component should
 117 override the current assembled definition.
 118   </para>
 119 </listitem>
 120 <listitem>
 121   <para>The ‘|’ operator specifies that the next specified component should
 122 augment the currently assembled definition.
 123   </para>
 124 </listitem>
 125 <listitem>
 126   <para>If the new elements are being merged with an existing map and the
 127 component expression begins with an operator, a leading ‘%’ is implied.
 128   </para>
 129 </listitem>
 130 <listitem>
 131   <para>If any unknown or illegal characters appear anywhere in the string, the
 132 entire expression is invalid and is ignored.
 133   </para>
 134 </listitem>
 135 </itemizedlist>
 136
 137 <para>
 138 For example, the component expression "+de" specifies that the default element
 139 of the "de" map should be applied to the current keyboard mapping, overriding
 140 any existing definitions.
 141 </para>
 142
 143
 144 <para>
 145 A slightly more involved example: the expression
 146 "acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the
 147 ASCII keyboard supplied by the "acme" vendor. The new definition begins with
 148 the symbols for the default ASCII keyboard for Acme, overrides them with any
 149 keys that are defined for the default German keyboard layout and then applies
 150 the definitions from the iso9995-3 to any undefined keys or groups of keys
 151 (part three of the iso9995 standard defines a common set of bindings for the
 152 secondary group, but allows national layouts to override those definitions
 153 where necessary).
 154 </para>
 155
 156
 157 </sect1>
 158 <sect1 id='Component_Hints'>
 159 <title>Component Hints</title>
 160
 161 <para>
 162 Each component has a set of flags that provide some additional hints about that
 163 component. XKB provides these hints for clients that present the keyboard
 164 database to users and specifies their interpretation only loosely. Clients can
 165 use these hints to constrain the list of components or to control the way that
 166 components are presented to the user.
 167 </para>
 168
 169
 170 <para>
 171 Hints for a component are reported with its name. The least significant byte of
 172 the hints field has the same meaning for all five types of keyboard components,
 173 and can contain any combination of the following values:
 174 </para>
 175
 176 <informaltable frame='topbot'>
 177 <?dbfo keep-together="always" ?>
 178 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 179 <colspec colname='c1' colwidth='1.0*'/>
 180 <colspec colname='c2' colwidth='3.0*'/>
 181 <thead>
 182   <row rowsep='1'>
 183     <entry>Flag</entry>
 184     <entry>Meaning</entry>
 185   </row>
 186 </thead>
 187 <tbody>
 188   <row>
 189     <entry><emphasis>
 190 LC_Hidden</emphasis>
 191 </entry>
 192     <entry>Indicates a component that should not normally be presented to the
 193 user.</entry>
 194   </row>
 195   <row>
 196     <entry><emphasis>
 197 LC_Default</emphasis>
 198 </entry>
 199     <entry>Indicates a component that is the default member of its
 200 class.</entry>
 201   </row>
 202   <row>
 203     <entry><emphasis>
 204 LC_Partial</emphasis>
 205 </entry>
 206     <entry>Indicates a partial component.</entry>
 207   </row>
 208 </tbody>
 209 </tgroup>
 210 </informaltable>
 211
 212 <para>
 213 The interpretation of the most significant byte of the hints field is dependent
 214 on the type of component. The hints defined for each kind of component are
 215 listed in the section below that describes that kind of component.
 216 </para>
 217
 218
 219 </sect1>
 220 <sect1 id='Keyboard_Components'>
 221 <title>Keyboard Components</title>
 222
 223 <para>
 224 The five types of components stored in the server database of keyboard
 225 components correspond to the <emphasis>
 226 symbols</emphasis>
 227 , <emphasis>
 228 geometry</emphasis>
 229 , <emphasis>
 230 keycodes</emphasis>
 231 , <emphasis>
 232 compat</emphasis>
 233  and <emphasis>
 234 types</emphasis>
 235  symbolic names associated with a keyboard.
 236 </para>
 237
 238 </sect1>
 239 <sect1 id='The_Keycodes_Component'>
 240 <title>The Keycodes Component</title>
 241
 242 <para>
 243 The <emphasis>
 244 keycodes</emphasis>
 245  component of a keyboard mapping specifies the range and interpretation of the
 246 raw keycodes reported by the device. It sets the <emphasis>
 247 keycodes</emphasis>
 248  symbolic name, the minimum and maximum legal keycodes for the keyboard, and
 249 the symbolic name for each key. The keycodes component might also contain
 250 aliases for some keys, symbolic names for some indicators, and a description of
 251 which indicators are physically present.
 252 </para>
 253
 254
 255 <para>
 256 The special keycodes component named "computed" indicates that XKB should
 257 assign unused keycodes to any unknown keys referenced by name by any of the
 258 other components. The computed keycodes component is useful primarily when
 259 browsing keymaps because it makes it possible to use the symbols and geometry
 260 components without having to find a set of keycodes that includes keycode
 261 definitions for all of the keys listed in the two components.
 262 </para>
 263
 264
 265 <para>
 266 XKB defines no hints that are specific to the keycodes component.
 267 </para>
 268
 269
 270 <sect2 id='The_Types_Component'>
 271 <title>The Types Component</title>
 272
 273 <para>
 274 The <emphasis>
 275 types</emphasis>
 276  component of a keyboard mapping specifies the key types that can be associated
 277 with the various keyboard keys. It affects the <emphasis>
 278 types</emphasis>
 279  symbolic name and the list of types associated with the keyboard (see
 280 <link linkend='Key_Types'>Key Types</link>). The types component
 281 of a keyboard mapping can also optionally contain real modifier bindings and
 282 symbolic names for one or more virtual modifiers.
 283 </para>
 284
 285
 286 <para>
 287 The special types component named "canonical" always contains the types and
 288 definitions listed in <link linkend="canonical_key_types">Canonical Key Types</link> of this document.
 289 </para>
 290
 291
 292 <para>
 293 XKB defines no hints that are specific to the types component.
 294 </para>
 295
 296
 297 </sect2>
 298 <sect2 id='The_Compatibility_Map_Component'>
 299 <title>The Compatibility Map Component</title>
 300
 301 <para>
 302 The <emphasis>
 303 compatibility map</emphasis>
 304  component of a keyboard mapping primarily specifies the rules used to assign
 305 actions to keysyms. It affects the <emphasis>
 306 compat</emphasis>
 307  symbolic name, the symbol compatibility map and the group compatibility map.
 308 The compat component might also specify maps for some indicators and the real
 309 modifier bindings and symbolic names of some virtual modifiers.
 310 </para>
 311
 312
 313 <para>
 314 XKB defines no hints that are specific to the compatibility map component.
 315 </para>
 316
 317
 318 </sect2>
 319 <sect2 id='The_Symbols_Component'>
 320 <title>The Symbols Component</title>
 321
 322 <para>
 323 The <emphasis>
 324 symbols</emphasis>
 325  component of a keyboard mapping specifies primarily the symbols bound to each
 326 keyboard key. It affects the <emphasis>
 327 symbols</emphasis>
 328  symbolic name, a key symbol mapping for each key, they keyboard modifier
 329 mapping, and the symbolic names for the keyboard symbol groups. Optionally, the
 330 <emphasis>
 331 symbols</emphasis>
 332  component can contain explicit actions and behaviors for some keys, or the
 333 real modifier bindings and symbolic names for some virtual modifiers.
 334 </para>
 335
 336
 337 <para>
 338 XKB defines the following additional hints for the symbols component:
 339 </para>
 340
 341 <informaltable frame='topbot'>
 342 <?dbfo keep-together="always" ?>
 343 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 344 <colspec colname='c1' colwidth='1.0*'/>
 345 <colspec colname='c2' colwidth='3.0*'/>
 346 <thead>
 347   <row rowsep='1'>
 348     <entry>Flag</entry>
 349     <entry>Meaning</entry>
 350   </row>
 351 </thead>
 352 <tbody>
 353   <row>
 354     <entry><emphasis>
 355 LC_AlphanumericKeys</emphasis>
 356 </entry>
 357     <entry>Indicates a symbol component that contains bindings primarily for an
 358 alphanumeric section of the keyboard.</entry>
 359   </row>
 360   <row>
 361     <entry><emphasis>
 362 LC_ModifierKeys</emphasis>
 363 </entry>
 364     <entry>Indicates a symbol component that contains bindings primarily for
 365 modifier keys.</entry>
 366   </row>
 367   <row>
 368     <entry><emphasis>
 369 LC_KeypadKeys</emphasis>
 370 </entry>
 371     <entry>Indicates a symbol component that contains bindings primarily for
 372 numeric keypad keys.</entry>
 373   </row>
 374   <row>
 375     <entry>LC_FunctionKeys</entry>
 376     <entry>Indicates a symbol component that contains bindings primarily for
 377 function keys.</entry>
 378   </row>
 379   <row>
 380     <entry>LC_AlternateGroup</entry>
 381     <entry>Indicates a symbol component that contains bindings for an alternate
 382 keyboard group.</entry>
 383   </row>
 384 </tbody>
 385 </tgroup>
 386 </informaltable>
 387
 388 <para>
 389 These hints only apply to partial symbols components; full symbols components
 390 are assumed to specify all of the pieces listed above.
 391 </para>
 392
 393 <note><para>The alphanumeric, modifier, keypad or function keys hints should
 394 describe the primary intent of the component designer and should not simply an
 395 exhaustive list of the kinds of keys that are affected. For example, national
 396 keyboard layouts affect primarily alphanumeric keys, but many affect a few
 397 modifier keys too; such mappings should set only <emphasis>
 398 LC_AlphanumericKeys</emphasis>
 399  hint. In general, symbol components should set only one of those four flags
 400 (though <emphasis>
 401 LC_AlternateGroup</emphasis>
 402  may be combined with any of the other flags).</para></note>
 403
 404 </sect2>
 405 <sect2 id='The_Geometry_Component'>
 406 <title>The Geometry Component</title>
 407
 408 <para>
 409 The <emphasis>
 410 geometry</emphasis>
 411  component of a keyboard mapping specifies primarily the geometry of the
 412 keyboard. It contains the geometry symbolic name and the keyboard geometry
 413 description. The geometry component might also contain aliases for some keys or
 414 symbolic names for some indicators and might affect the set of indicators that
 415 are physically present. Key aliases defined in the geometry component of a
 416 keyboard mapping override those defined in the keycodes component.
 417 </para>
 418
 419
 420 <para>
 421 XKB defines no hints that are specific to the geometry component.
 422 </para>
 423
 424
 425 </sect2>
 426 </sect1>
 427 <sect1 id='Complete_Keymaps'>
 428 <title>Complete Keymaps</title>
 429
 430 <para>
 431 The X server also reports a set of fully specified keymaps. The keymaps
 432 specified in this list are usually assembled from the components stored in the
 433 rest of the database and typically represent the most commonly used keymaps for
 434 a particular system.
 435 </para>
 436
 437
 438 <para>
 439 XKB defines no hints that are specific to complete keymaps.
 440 </para>
 441 </sect1>
 442 </chapter>