specs/XKB/ch14.xml

   1 <chapter id='Xkb_Keyboard_Mapping'>
   2 <title>Xkb Keyboard Mapping</title>
   3
   4 <para>
   5 The Xkb keyboard mapping contains all the information the server and clients
   6 need to interpret key events. This chapter provides an overview of the
   7 terminology used to describe an Xkb keyboard mapping and introduces common
   8 utilities for manipulating the keyboard mapping.
   9 </para>
  10
  11
  12 <para>
  13 The mapping consists of two components, a server map and a client map. The
  14 <emphasis>
  15 client</emphasis>
  16  map is the collection of information a client needs to interpret key events
  17 from the keyboard. It contains a global list of key types and an array of key
  18 symbol maps, each of which describes the symbols bound to a key and the rules
  19 to be used to interpret those symbols. The <emphasis>
  20 server</emphasis>
  21  map contains the information the server needs to interpret key events. This
  22 includes actions and behaviors for each key, explicit components for a key, and
  23 the virtual modifiers and the per-key virtual modifier mapping.
  24 </para>
  25
  26
  27 <para>
  28 For detailed information on particular components of the keyboard map, refer to
  29 Chapter 15, "Xkb Client Keyboard Mapping" and Chapter 16, "Xkb Server Keyboard
  30 Mapping."
  31 </para>
  32
  33 <sect1 id='Notation_and_Terminology'>
  34 <title>Notation and Terminology</title>
  35
  36 <para>
  37 The graphic characters or control functions that may be accessed by one key are
  38 logically arranged in groups and levels, where <emphasis>
  39 group</emphasis>
  40  and <emphasis>
  41 level</emphasis>
  42  are defined as in the ISO9995 standard:
  43 </para>
  44
  45 <variablelist>
  46   <varlistentry>
  47     <term>Group:</term>
  48     <listitem>
  49       <para>
  50 A logical state of a keyboard providing access to a collection of
  51 graphic characters. Usually these graphic characters logically belong together
  52 and may be arranged on several levels within a group.
  53       </para>
  54     </listitem>
  55   </varlistentry>
  56   <varlistentry>
  57     <term>Level:</term>
  58     <listitem>
  59       <para>
  60 One of several states (normally 2 or 3) governing which graphic
  61 character is produced when a graphic key is actuated. In certain cases the
  62 level may also affect function keys.
  63       </para>
  64     </listitem>
  65   </varlistentry>
  66 </variablelist>
  67
  68 <para>
  69 These definitions, taken from the ISO standard, refer to graphic keys and
  70 characters. In the context of Xkb, Group and Level are not constrained to
  71 graphic keys and characters; they may be used with any key to access any
  72 character the key is capable of generating.
  73 </para>
  74
  75
  76 <para>
  77 Level is often referred to as "Shift Level". Levels are numbered sequentially
  78 starting at one.
  79 </para>
  80
  81 <note><para>Shift level is derived from the modifier state, but not necessarily
  82 in the same way for all keys. For example, the <emphasis>
  83 Shift</emphasis>
  84  modifier selects shift level 2 on most keys, but for keypad keys the modifier
  85 bound to <emphasis>
  86 Num_Lock</emphasis>
  87  (that is, the <emphasis>
  88 NumLock</emphasis>
  89  virtual modifier) also selects shift level 2.</para></note>
  90
  91 <para>
  92 For example, consider the following key (the gray characters indicate symbols
  93 that are implied or expected but are not actually engraved on the key):
  94 </para>
  95
  96 <mediaobject>
  97  <imageobject> <imagedata format="SVG" fileref="XKBlib-14.svg"/>
  98  </imageobject>
  99 <caption>Shift Levels and Groups</caption>
 100  </mediaobject>
 101
 102
 103 <!--
 104 <H5 CLASS="Figure">
 105 Shift Levels and Groups</H5>
 106 -->
 107
 108 <para>
 109 This key has two groups, indicated by the columns, and each group has two shift
 110 levels. For the first group (Group1), the symbol shift level one is <emphasis>
 111 a</emphasis>
 112 , and the symbol for shift level two is <emphasis>
 113 A</emphasis>
 114 . For the second group, the symbol for shift level one is <emphasis>
 115 æ</emphasis>
 116 , and the symbol for shift level two is <emphasis>
 117 Æ</emphasis>
 118 .
 119 </para>
 120
 121 <sect2 id='Core_Implementation'>
 122 <title>Core Implementation</title>
 123
 124 <para>
 125 The standard interpretation rules for the core X keymap only allow clients to
 126 access keys such as the one shown in Figure 14.1. That is, clients using the
 127 standard interpretation rules can only access one of four keysyms for any given
 128 <emphasis>
 129 KeyPress</emphasis>
 130  event — two different symbols in two different groups.
 131 </para>
 132
 133
 134 <para>
 135 In general, the <emphasis>
 136 Shift</emphasis>
 137  modifier, the <emphasis>
 138 Lock</emphasis>
 139  modifier, and the modifier bound to the <emphasis>
 140 Num_Lock</emphasis>
 141  key are used to change between shift level 1 and shift level 2. To switch
 142 between groups, the core implementation uses the modifier bound to the
 143 <emphasis>
 144 Mode_switch</emphasis>
 145  key. When the <emphasis>
 146 Mode_switch</emphasis>
 147  modifier is set, the keyboard is logically in Group 2. When the <emphasis>
 148 Mode_switch</emphasis>
 149  modifier is not set, the keyboard is logically in Group 1.
 150 </para>
 151
 152
 153 <para>
 154 The core implementation does not clearly specify the behavior of keys. For
 155 example, the locking behavior of the <emphasis>
 156 CapsLock</emphasis>
 157  and <emphasis>
 158 Num_Lock</emphasis>
 159  keys depends on the vendor.
 160 </para>
 161
 162
 163 </sect2>
 164 <sect2 id='Xkb_Implementation'>
 165 <title>Xkb Implementation</title>
 166
 167 <para>
 168 Xkb extends the core implementation by providing access to up to four keyboard
 169 groups with up to 63 shift levels per key
 170 <footnote><para>
 171 The core implementation restricts the number of symbols per key to 255.
 172 With four groups, this allows for up to 63 symbols (or shift levels) per
 173 group. Most keys will only have a few shift levels.
 174 </para></footnote>. In
 175 addition, Xkb provides precise specifications regarding the behavior of keys.
 176 In Xkb, modifier state and the current group are independent (with the
 177 exception of compatibility mapping, discussed in Chapter 17).
 178 </para>
 179
 180
 181 <para>
 182 Xkb handles switching between groups via key actions, independent of any
 183 modifier state information. Key actions are in the server map component and are
 184 described in detail in section 16.1.4.
 185 </para>
 186
 187
 188 <para>
 189 Xkb handles shift levels by associating a key type with each group on each key.
 190 Each key type defines the shift levels available for the groups on keys of its
 191 type and specifies the modifier combinations necessary to access each level.
 192 </para>
 193
 194
 195 <para>
 196 For example, Xkb allows key types where the <emphasis>
 197 Control</emphasis>
 198  modifier can be used to access the shift level two of a key. Key types are in
 199 the client map component and are described in detail in section 15.2. <!-- xref -->
 200 </para>
 201
 202
 203 <para>
 204 Xkb provides precise specification of the behavior of a key using key
 205 behaviors. Key behaviors are in the server map component and are described in
 206 detail in section 16.2. <!-- xref -->
 207 </para>
 208
 209
 210 </sect2>
 211 </sect1>
 212 <sect1 id='Getting_Map_Components_from_the_Server'>
 213 <title>Getting Map Components from the Server</title>
 214
 215 <para>
 216 Xkb provides two functions to obtain the keyboard mapping components from the
 217 server. The first function, <emphasis>
 218 XkbGetMap</emphasis>
 219 , allocates an <emphasis>
 220 XkbDescRec</emphasis>
 221  structure, retrieves mapping components from the server, and stores them in
 222 the <emphasis>
 223 XkbDescRec</emphasis>
 224  structure it just allocated. The second function, <emphasis>
 225 XkbGetUpdatedMap</emphasis>
 226 , retrieves mapping components from the server and stores them in an <emphasis>
 227 XkbDescRec</emphasis>
 228  structure that has previously been allocated.
 229 </para>
 230
 231
 232 <para>
 233 To allocate an <emphasis>
 234 XkbDescRec</emphasis>
 235  structure and populate it with the server’s keyboard client map and server
 236 map, use <emphasis>
 237 XkbGetMap. XkbGetMap </emphasis>
 238 is similar to <emphasis>
 239 XkbGetKeyboard</emphasis>
 240  (see section 6.2), but is used only for obtaining the address of an <emphasis>
 241 XkbDescRec</emphasis>
 242  structure that is populated with keyboard mapping components. It allows finer
 243 control over which substructures of the keyboard mapping components are to be
 244 populated. <emphasis>
 245 XkbGetKeyboard</emphasis>
 246  always returns fully populated components, while <emphasis>
 247 XkbGetMap</emphasis>
 248  can be instructed to return a partially populated component.
 249 </para>
 250
 251 <informaltable frame='none'>
 252 <?dbfo keep-together="always" ?>
 253 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 254 <colspec colname='c1' colwidth='1.0*'/>
 255 <tbody>
 256   <row>
 257     <entry role='functiondecl'>
 258 XkbDescPtr <emphasis>
 259 XkbGetMap</emphasis>
 260 (<emphasis>
 261 display, which, device_spec</emphasis>
 262 )
 263     </entry>
 264   </row>
 265   <row>
 266     <entry role='functionargdecl'>
 267 Display *       <emphasis>
 268       display</emphasis>
 269 ;            /* connection to X server */
 270     </entry>
 271   </row>
 272   <row>
 273     <entry role='functionargdecl'>
 274 unsigned int      <emphasis>
 275       which</emphasis>
 276 ;            /* mask selecting subcomponents to populate */
 277     </entry>
 278   </row>
 279   <row>
 280     <entry role='functionargdecl'>
 281 unsigned int      <emphasis>
 282       device_spec</emphasis>
 283 ;            /* device_id, or <emphasis>
 284 XkbUseCoreKbd</emphasis>
 285  */
 286     </entry>
 287 </row>
 288 </tbody>
 289 </tgroup>
 290 </informaltable>
 291
 292 <para>
 293 The <emphasis>
 294 which</emphasis>
 295  mask is a bitwise inclusive OR of the masks defined in Table 14.1. Only those
 296 portions of the keyboard server map and the keyboard client maps that are
 297 specified in <emphasis>
 298 which</emphasis>
 299  are allocated and populated.
 300 </para>
 301
 302
 303 <para>
 304 In addition to allocating and obtaining the server map and the client map,
 305 <emphasis>
 306 XkbGetMap</emphasis>
 307  also sets the <emphasis>
 308 device_spec</emphasis>
 309 , the <emphasis>
 310 min_key_code</emphasis>
 311 <emphasis>
 312 , </emphasis>
 313 and <emphasis>
 314 max_key_code</emphasis>
 315  fields of the keyboard description.
 316 </para>
 317
 318
 319 <para>
 320 <emphasis>
 321 XkbGetMap</emphasis>
 322  is synchronous; it queries the server for the desired information, waits for a
 323 reply, and then returns. If successful<emphasis>
 324 , XkbGetMap</emphasis>
 325  returns a pointer to the <emphasis>
 326 XkbDescRec</emphasis>
 327  structure it allocated. If unsuccessful, <emphasis>
 328 XkbGetMap</emphasis>
 329  returns <emphasis>
 330 NULL</emphasis>
 331 . When unsuccessful, one of the following protocol errors is also generated:
 332 <emphasis>
 333 BadAlloc</emphasis>
 334  (unable to allocate the <emphasis>
 335 XkbDescRec</emphasis>
 336  structure), <emphasis>
 337 BadValue</emphasis>
 338  (some mask bits in <emphasis>
 339 which</emphasis>
 340  are undefined)<emphasis>
 341 ,</emphasis>
 342  or <emphasis>
 343 BadImplementation</emphasis>
 344  (a compatible version of the Xkb extension is not available in the server). To
 345 free the returned data, use <emphasis>
 346 XkbFreeClientMap</emphasis>
 347 .
 348 </para>
 349
 350
 351 <para>
 352 Xkb also provides convenience functions to get partial component definitions
 353 from the server. These functions are specified in the "convenience functions"
 354 column in Table 14.1. Refer to the sections listed in the table for more
 355 information on these functions.
 356 </para>
 357
 358 <table frame='topbot'>
 359 <title>Xkb Mapping Component Masks and Convenience Functions</title>
 360 <?dbfo keep-together="always" ?>
 361 <tgroup cols='6' align='left' colsep='0' rowsep='0'>
 362 <colspec colname='c1' colwidth='3.0*'/>
 363 <colspec colname='c2' colwidth='0.9*'/>
 364 <colspec colname='c3' colwidth='0.9*'/>
 365 <colspec colname='c4' colwidth='1.6*'/>
 366 <colspec colname='c5' colwidth='2.1*'/>
 367 <colspec colname='c6' colwidth='0.9*'/>
 368 <thead>
 369 <row rowsep='1'>
 370   <entry>Mask</entry>
 371   <entry>Value</entry>
 372   <entry>Map</entry>
 373   <entry>Fields</entry>
 374   <entry>Convenience Functions</entry>
 375   <entry>Section</entry>
 376 </row>
 377 </thead>
 378 <tbody>
 379   <row>
 380     <entry><emphasis>XkbKeyTypesMask</emphasis></entry>
 381     <entry>(1&lt;&lt;0)</entry>
 382     <entry>client</entry>
 383     <entry>
 384       <para><emphasis>types</emphasis></para>
 385       <para><emphasis>size_types</emphasis></para>
 386       <para><emphasis>num_types</emphasis></para>
 387     </entry>
 388     <entry>
 389       <para><emphasis>XkbGetKeyTypes</emphasis></para>
 390       <para><emphasis>XkbResizeKeyType</emphasis></para>
 391       <para><emphasis>XkbCopyKeyType</emphasis></para>
 392       <para><emphasis>XkbCopyKeyTypes</emphasis></para>
 393     </entry>
 394     <entry>15.2</entry>
 395   </row>
 396   <row>
 397     <entry><emphasis>XkbKeySymsMask</emphasis></entry>
 398     <entry>(1&lt;&lt;1)</entry>
 399     <entry>client</entry>
 400     <entry>
 401       <para><emphasis>syms</emphasis></para>
 402       <para><emphasis>size_syms</emphasis></para>
 403       <para><emphasis>num_syms</emphasis></para>
 404       <para><emphasis>key_sym_map</emphasis></para>
 405     </entry>
 406     <entry>
 407       <para><emphasis>XkbGetKeySyms</emphasis></para>
 408       <para><emphasis>XkbResizeKeySyms</emphasis></para>
 409       <para><emphasis>XkbChangeTypes&#xAD;OfKey</emphasis></para>
 410     </entry>
 411     <entry>15.3</entry>
 412   </row>
 413   <row>
 414     <entry><emphasis>XkbModifierMapMask</emphasis></entry>
 415     <entry>(1&lt;&lt;2)</entry>
 416     <entry>client</entry>
 417     <entry><emphasis>modmap</emphasis></entry>
 418     <entry><emphasis>XkbGetKeyModifier&#xAD;Map</emphasis></entry>
 419     <entry>15.4</entry>
 420   </row>
 421   <row>
 422     <entry><emphasis>XkbExplicitComponentsMask</emphasis></entry>
 423     <entry>(1&lt;&lt;3)</entry>
 424     <entry>server</entry>
 425     <entry><emphasis>explicit</emphasis></entry>
 426     <entry><emphasis>XkbGetKeyExplicit&#xAD;Components</emphasis></entry>
 427     <entry>16.3</entry>
 428   </row>
 429   <row>
 430     <entry><emphasis>XkbKeyActionsMask</emphasis></entry>
 431     <entry>(1&lt;&lt;4)</entry>
 432     <entry>server</entry>
 433     <entry>
 434       <para><emphasis>key_acts</emphasis></para>
 435       <para><emphasis>acts</emphasis></para>
 436       <para><emphasis>num_acts</emphasis></para>
 437       <para><emphasis>size_acts</emphasis></para>
 438     </entry>
 439     <entry>
 440       <para><emphasis>XkbGetKeyActions</emphasis></para>
 441       <para><emphasis>XkbResizeKey&#xAD;Actions</emphasis></para>
 442     </entry>
 443     <entry>16.1</entry>
 444   </row>
 445   <row>
 446     <entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry>
 447     <entry>(1&lt;&lt;5)</entry>
 448     <entry>server</entry>
 449     <entry><emphasis>behaviors</emphasis></entry>
 450     <entry><emphasis>XkbGetKey&#xAD;Behaviors</emphasis></entry>
 451     <entry>16.2</entry>
 452   </row>
 453   <row>
 454     <entry><emphasis>XkbVirtualModsMask</emphasis></entry>
 455     <entry>(1&lt;&lt;6)</entry>
 456     <entry>server</entry>
 457     <entry><emphasis>vmods</emphasis></entry>
 458     <entry><emphasis>XkbGetVirtualMods</emphasis></entry>
 459     <entry>16.4</entry>
 460   </row>
 461   <row>
 462     <entry><emphasis>XkbVirtualModMapMask</emphasis></entry>
 463     <entry>(1&lt;&lt;7)</entry>
 464     <entry>server</entry>
 465     <entry><emphasis>vmodmap</emphasis></entry>
 466     <entry><emphasis>XkbGetVirtualMod&#xAD;Map</emphasis></entry>
 467     <entry>16.4</entry>
 468   </row>
 469 </tbody>
 470 </tgroup>
 471 </table>
 472
 473 <para>
 474 Xkb defines combinations of these masks for convenience:
 475 </para>
 476
 477 <para><programlisting>
 478 #define  XkbResizableInfoMask      (XkbKeyTypesMask)
 479 #define  XkbAllClientInfoMask      (XkbKeyTypesMask | XkbKeySymsMask |
 480                                     XkbModifierMapMask)
 481 #define  XkbAllServerInfoMask      (XkbExplicitComponentsMask |
 482                                     XkbKeyActionsMask| XkbKeyBehaviorsMask |
 483                                     XkbVirtualModsMask | XkbVirtualModMapMask)
 484 #define  XkbAllMapComponentsMask   (XkbAllClientInfoMask|XkbAllServerInfoMask)
 485 </programlisting></para>
 486
 487 <para>
 488 Key types, symbol maps, and actions are all interrelated: changes in one
 489 require changes in the others. The convenience functions make it easier to edit
 490 these components and handle the interdependencies.
 491 </para>
 492
 493
 494 <para>
 495 To update the client or server map information in an existing keyboard
 496 description, use <emphasis>XkbGetUpdatedMap</emphasis>.
 497 </para>
 498
 499
 500 <informaltable frame='none'>
 501 <?dbfo keep-together="always" ?>
 502 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 503 <colspec colname='c1' colwidth='1.0*'/>
 504 <tbody>
 505   <row>
 506     <entry role='functiondecl'>
 507 Status <emphasis>
 508 XkbGetUpdatedMap</emphasis>
 509 (<emphasis>
 510 display, which, xkb</emphasis>
 511 )
 512     </entry>
 513   </row>
 514   <row>
 515     <entry role='functionargdecl'>
 516 Display * <emphasis>
 517             display</emphasis>
 518 ;            /* connection to X server */
 519     </entry>
 520   </row>
 521   <row>
 522     <entry role='functionargdecl'>
 523 unsigned int<emphasis>
 524             which</emphasis>
 525 ;            /* mask selecting subcomponents to populate */
 526     </entry>
 527   </row>
 528   <row>
 529     <entry role='functionargdecl'>
 530 XkbDescPtr            <emphasis>
 531 xkb</emphasis>
 532 ;            /* keyboard description to be updated */
 533     </entry>
 534 </row>
 535 </tbody>
 536 </tgroup>
 537 </informaltable>
 538
 539 <para>
 540 The <emphasis>
 541 which</emphasis>
 542  parameter is a bitwise inclusive OR of the masks in Table 14.1. If the needed
 543 components of the <emphasis>
 544 xkb</emphasis>
 545  structure are not already allocated, <emphasis>
 546 XkbGetUpdatedMap</emphasis>
 547  allocates them. <emphasis>
 548 XkbGetUpdatedMap</emphasis>
 549  fetches the requested information for the device specified in the <emphasis>
 550 XkbDescRec</emphasis>
 551  passed in the <emphasis>
 552 xkb</emphasis>
 553  parameter.
 554 </para>
 555
 556
 557 <para>
 558 <emphasis>
 559 XkbGetUpdatedMap</emphasis>
 560  is synchronous; it queries the server for the desired information, waits for a
 561 reply, and then returns. If successful<emphasis>
 562 , XkbGetUpdatedMap</emphasis>
 563  returns <emphasis>
 564 Success</emphasis>
 565 . If unsuccessful, <emphasis>
 566 XkbGetUpdatedMap</emphasis>
 567  returns one of the following: <emphasis>
 568 BadAlloc</emphasis>
 569  (unable to allocate a component in the <emphasis>
 570 XkbDescRec</emphasis>
 571  structure), <emphasis>
 572 BadValue</emphasis>
 573  (some mask bits in <emphasis>
 574 which</emphasis>
 575  are undefined), <emphasis>
 576 BadImplementation</emphasis>
 577  (a compatible version of the Xkb extension is not available in the server or
 578 the reply from the server was invalid).
 579 </para>
 580
 581 </sect1>
 582 <sect1 id='Changing_Map_Components_in_the_Server'>
 583 <title>Changing Map Components in the Server</title>
 584
 585 <para>
 586 There are two ways to make changes to map components: either change a local
 587 copy of the keyboard map and call <emphasis>
 588 XkbSetMap</emphasis>
 589  to send the modified map to the server, or, to reduce network traffic, use
 590 an<emphasis>
 591  XkbMapChangesRec</emphasis>
 592  structure and call <emphasis>XkbChangeMap</emphasis>.
 593 </para>
 594
 595 <informaltable frame='none'>
 596 <?dbfo keep-together="always" ?>
 597 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 598 <colspec colname='c1' colwidth='1.0*'/>
 599 <tbody>
 600   <row>
 601     <entry role='functiondecl'>
 602 Bool <emphasis>
 603 XkbSetMap</emphasis>
 604 (<emphasis>
 605 dpy</emphasis>
 606 ,<emphasis>
 607  which</emphasis>
 608 ,<emphasis>
 609  xkb</emphasis>
 610 )
 611     </entry>
 612   </row>
 613   <row>
 614     <entry role='functionargdecl'>
 615 Display *<emphasis>
 616             dpy</emphasis>
 617 ;            /* connection to X server */
 618     </entry>
 619   </row>
 620   <row>
 621     <entry role='functionargdecl'>
 622 unsigned int<emphasis>
 623             which</emphasis>
 624 ;            /* mask selecting subcomponents to update */
 625     </entry>
 626   </row>
 627   <row>
 628     <entry role='functionargdecl'>
 629 XkbDescPtr <emphasis>
 630             xkb</emphasis>
 631 ;            /* description from which new values are taken */
 632     </entry>
 633 </row>
 634 </tbody>
 635 </tgroup>
 636 </informaltable>
 637
 638 <para>
 639 Use <emphasis>
 640 XkbSetMap</emphasis>
 641  to send a complete new set of values for entire components (for example, all
 642 symbols, all actions, and so on) to the server. The <emphasis>
 643 which</emphasis>
 644  parameter specifies the components to be sent to the server, and is a bitwise
 645 inclusive OR of the masks listed in Table 14.1. The <emphasis>
 646 xkb</emphasis>
 647  parameter is a pointer to an <emphasis>
 648 XkbDescRec</emphasis>
 649  structure and contains the information to be copied to the server. For each
 650 bit set in the <emphasis>
 651 which</emphasis>
 652  parameter, <emphasis>
 653 XkbSetMap</emphasis>
 654  takes the corresponding structure values from the <emphasis>
 655 xkb</emphasis>
 656  parameter and sends it to the server specified by <emphasis>
 657 dpy</emphasis>.
 658 </para>
 659
 660 <para>
 661 If any components specified by <emphasis>
 662 which</emphasis>
 663  are not present in the <emphasis>
 664 xkb</emphasis>
 665  parameter, <emphasis>
 666 XkbSetMap</emphasis>
 667  returns <emphasis>
 668 False</emphasis>
 669 . Otherwise, it sends the update request to the server and returns <emphasis>
 670 True</emphasis>
 671 . <emphasis>
 672 XkbSetMap</emphasis>
 673  can generate <emphasis>
 674 BadAlloc</emphasis>
 675 , <emphasis>
 676 BadLength</emphasis>
 677 , and <emphasis>
 678 BadValue</emphasis>
 679  protocol errors.
 680 </para>
 681
 682
 683 <para>
 684 Key types, symbol maps, and actions are all interrelated; changes in one
 685 require changes in the others. Xkb provides functions to make it easier to edit
 686 these components and handle the interdependencies. Table 14.1 lists these
 687 helper functions and provides a pointer to where they are defined.
 688 </para>
 689
 690
 691 <sect2 id='The_XkbMapChangesRec_Structure'>
 692 <title>The XkbMapChangesRec Structure</title>
 693
 694 <para>
 695 Use the <emphasis>
 696 XkbMapChangesRec</emphasis>
 697  structure to identify and track partial modifications to the mapping
 698 components and to reduce the amount of traffic between the server and clients.
 699 </para>
 700
 701 <para><programlisting>
 702 typedef struct _XkbMapChanges {
 703       unsigned short    changed;              /* identifies valid components
 704                                                  in structure */
 705       KeyCode           min_key_code;         /* lowest numbered keycode for
 706                                                  device */
 707       KeyCode           max_key_code;         /* highest numbered keycode for
 708                                                  device */
 709       unsigned char     first_type;           /* index of first key <emphasis>type</emphasis>
 710                                                  modified */
 711       unsigned char     num_types;            /* # types modified */
 712       KeyCode           first_key_sym;        /* first key whose <emphasis>key_sym_map</emphasis>
 713                                                  changed */
 714       unsigned char     num_key_syms;         /* # <emphasis>key_sym_map</emphasis>
 715                                                  entries changed */
 716       KeyCode           first_key_act;        /* first key whose <emphasis>key_acts</emphasis>
 717                                                  entry changed */
 718       unsigned char     num_key_acts;         /* # <emphasis>key_acts</emphasis>
 719                                                  entries changed */
 720       KeyCode           first_key_behavior;   /* first key whose <emphasis>behaviors</emphasis>
 721                                                  changed */
 722       unsigned char     num_key_behaviors;    /* # <emphasis>behaviors</emphasis>
 723                                                  entries changed */
 724       KeyCode           first_key_explicit;   /* first key whose <emphasis>explicit</emphasis>
 725                                                  entry changed */
 726       unsigned char     num_key_explicit;     /* # <emphasis> explicit</emphasis>
 727                                                  entries changed */
 728       KeyCode           first_modmap_key;     /* first key whose <emphasis>modmap</emphasis>
 729                                                  entry changed */
 730       unsigned char     num_modmap_keys;      /* # <emphasis>modmap</emphasis>
 731                                                  entries changed */
 732       KeyCode           first_vmodmap_key;    /* first key whose <emphasis>vmodmap</emphasis>
 733                                                  changed */
 734       unsigned char     num_vmodmap_keys;     /* # <emphasis> vmodmap</emphasis>
 735                                                  entries changed */
 736       unsigned char     pad1;                 /* reserved */
 737       unsigned short    vmods;                /* mask indicating which <emphasis>vmods</emphasis>
 738                                                  changed */
 739 } <emphasis>XkbMapChangesRec</emphasis>,*XkbMapChangesPtr;
 740 </programlisting></para>
 741
 742 <para>
 743 The <emphasis>
 744 changed</emphasis>
 745  field identifies the map components that have changed in an <emphasis>
 746 XkbDescRec</emphasis>
 747  structure and may contain any of the bits in Table 14.1, which are also shown
 748 in Table 14.2. Every 1 bit in <emphasis>
 749 changed</emphasis>
 750  also identifies which other fields in the <emphasis>
 751 XkbMapChangesRec</emphasis>
 752  structure contain valid values, as indicated in Table 14.2. The <emphasis>
 753 min_key_code</emphasis>
 754  and <emphasis>
 755 max_key_code</emphasis>
 756  fields are for reference only; they are ignored on any requests sent to the
 757 server and are always updated by the server whenever it returns the data for an
 758 <emphasis>
 759 XkbMapChangesRec</emphasis>
 760 .
 761 </para>
 762
 763 <table frame='topbot'>
 764 <title>XkbMapChangesRec Masks</title>
 765 <?dbfo keep-together="always" ?>
 766 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 767 <colspec colname='c1' colwidth='1.0*'/>
 768 <colspec colname='c2' colwidth='1.0*'/>
 769 <colspec colname='c3' colwidth='1.0*'/>
 770 <thead>
 771 <row rowsep='1'>
 772   <entry>Mask</entry>
 773   <entry>Valid XkbMapChangesRec Fields</entry>
 774   <entry>XkbDescRec Field Containing Changed Data</entry>
 775 </row>
 776 </thead>
 777 <tbody>
 778   <row>
 779     <entry><emphasis>XkbKeyTypesMask</emphasis></entry>
 780     <entry>
 781 <para>first_type</para>,
 782 <para>num_types</para>
 783     </entry>
 784     <entry>
 785 <para>map-&gt;type[first_type] ..</para>
 786 <para>map-&gt;type[first_type + num_types - 1]</para>
 787     </entry>
 788   </row>
 789   <row>
 790     <entry><emphasis>XkbKeySymsMask</emphasis></entry>
 791     <entry>
 792 <para>first_key_sym</para>,
 793 <para>num_key_syms</para>
 794     </entry>
 795     <entry>
 796 <para>map-&gt;key_sym_map[first_key_sym] ..</para>
 797 <para>map-&gt;key_sym_map[first_key_sym + num_key_syms - 1]</para>
 798     </entry>
 799   </row>
 800   <row>
 801     <entry><emphasis>XkbModifierMapMask</emphasis></entry>
 802     <entry>
 803 <para>first_modmap_key</para>,
 804 <para>num_modmap_keys</para>
 805     </entry>
 806     <entry>
 807 <para>map-&gt;modmap[first_modmap_key] ..</para>
 808 <para>map-&gt;modmap[first_modmap_key + num_modmap_keys-1]</para>
 809     </entry>
 810   </row>
 811   <row>
 812     <entry><emphasis>XkbExplicitComponentsMask</emphasis></entry>
 813     <entry>
 814 <para>first_key_explicit</para>,
 815 <para>num_key_explicit</para>
 816     </entry>
 817     <entry>
 818 <para>server-&gt;explicit[first_key_explicit] ..</para>
 819 <para>server-&gt;explicit[first_key_explicit + num_key_explicit - 1]</para>
 820     </entry>
 821   </row>
 822   <row>
 823     <entry><emphasis>XkbKeyActionsMask</emphasis></entry>
 824     <entry>
 825 <para>first_key_act,</para>
 826 <para>num_key_acts</para>
 827     </entry>
 828     <entry>
 829 <para>server-&gt;key_acts[first_key_act] ..</para>
 830 <para>server-&gt;key_acts[first_key_act + num_key_acts - 1]</para>
 831     </entry>
 832   </row>
 833   <row>
 834     <entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry>
 835     <entry>
 836 <para>first_key_behavior,</para>
 837 <para>num_key_behaviors</para>
 838     </entry>
 839     <entry>
 840 <para>server-&gt;behaviors[first_key_behavior] ..</para>
 841 <para>server-&gt;behaviors[first_key_behavior + num_key_behaviors - 1]</para>
 842     </entry>
 843   </row>
 844   <row>
 845     <entry><emphasis>XkbVirtuawModsMask</emphasis></entry>
 846     <entry>vmods</entry>
 847     <entry>server-&gt;vmods[*]</entry>
 848   </row>
 849   <row>
 850     <entry><emphasis>XkbVirtualModMapMask</emphasis></entry>
 851     <entry>
 852 <para>first_vmodmap_key,</para>
 853 <para>num_vmodmap_keys</para>
 854     </entry>
 855     <entry>
 856 <para>server-&gt;vmodmap[first_vmodmap_key] ..</para>
 857 <para>server-&gt;vmodmap[first_vmodmap_key + num_vmodmap_keys - 1]</para>
 858     </entry>
 859   </row>
 860 </tbody>
 861 </tgroup>
 862 </table>
 863
 864 <para>
 865 To update only partial components of a keyboard description, modify the
 866 appropriate fields in the server and map components of a local copy of the
 867 keyboard description, then call <emphasis>
 868 XkbChangeMap</emphasis>
 869  with an <emphasis>
 870 XkbMapChangesRec</emphasis>
 871  structure indicating which components have changed.
 872 </para>
 873
 874 <informaltable frame='none'>
 875 <?dbfo keep-together="always" ?>
 876 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 877 <colspec colname='c1' colwidth='1.0*'/>
 878 <tbody>
 879   <row>
 880     <entry role='functiondecl'>
 881 Bool <emphasis>
 882 XkbChangeMap</emphasis>
 883 (<emphasis>
 884 dpy</emphasis>
 885 ,<emphasis>
 886  xkb</emphasis>
 887 ,<emphasis>
 888  changes</emphasis>
 889 )
 890     </entry>
 891   </row>
 892   <row>
 893     <entry role='functionargdecl'>
 894 Display *<emphasis>
 895             dpy</emphasis>
 896 ;            /* connection to X server */
 897     </entry>
 898   </row>
 899   <row>
 900     <entry role='functionargdecl'>
 901 XkbDescPtr <emphasis>
 902             xkb</emphasis>
 903 ;            /* description from which new values are taken */
 904     </entry>
 905   </row>
 906   <row>
 907     <entry role='functionargdecl'>
 908 XkbMapChangesPtr <emphasis>
 909             changes</emphasis>
 910 ;            /*identifies component parts to update */
 911     </entry>
 912 </row>
 913 </tbody>
 914 </tgroup>
 915 </informaltable>
 916
 917 <para>
 918 <emphasis>
 919 XkbChangeMap</emphasis>
 920  copies any components specified by the <emphasis>
 921 changes</emphasis>
 922  structure from the keyboard description, <emphasis>
 923 xkb</emphasis>
 924 , to the X server specified by <emphasis>
 925 dpy</emphasis>
 926 .
 927 </para>
 928
 929
 930 <para>
 931 If any components specified by <emphasis>
 932 changes</emphasis>
 933  are not present in the <emphasis>
 934 xkb</emphasis>
 935  parameter, <emphasis>
 936 XkbChangeMap</emphasis>
 937  returns <emphasis>
 938 False</emphasis>
 939 . Otherwise, it sends a request to the server and returns <emphasis>
 940 True</emphasis>
 941 .
 942 </para>
 943
 944
 945 <para>
 946 <emphasis>
 947 XkbChangeMap</emphasis>
 948  can generate <emphasis>
 949 BadAlloc</emphasis>
 950 , <emphasis>
 951 BadLength</emphasis>
 952 , and <emphasis>
 953 BadValue</emphasis>
 954  protocol errors.
 955 </para>
 956
 957
 958 </sect2>
 959 </sect1>
 960 <sect1 id='Tracking_Changes_to_Map_Components'>
 961 <title>Tracking Changes to Map Components</title>
 962
 963 <para>
 964 The Xkb extension reports <emphasis>
 965 XkbMapNotify</emphasis>
 966  events to clients wanting notification whenever a map component of the Xkb
 967 description for a device changes. There are many different types of Xkb
 968 keyboard map changes. Xkb uses an event detail mask to identify each type of
 969 change. The event detail masks are identical to the masks listed in Table 14.1.
 970 </para>
 971
 972
 973 <para>
 974 To receive <emphasis>
 975 XkbMapNotify</emphasis>
 976  events under all possible conditions, use <emphasis>
 977 XkbSelectEvents</emphasis>
 978  (see section 4.3) and pass <emphasis>
 979 XkbMapNotifyMask</emphasis>
 980  in both <emphasis>
 981 bits_to_change</emphasis>
 982  and <emphasis>
 983 values_for_bits</emphasis>
 984 .
 985 </para>
 986
 987
 988 <para>
 989 To receive <emphasis>
 990 XkbMapNotify</emphasis>
 991  events only under certain conditions, use <emphasis>
 992 XkbSelectEventDetails</emphasis>
 993  using <emphasis>
 994 XkbMapNotify</emphasis>
 995  as the <emphasis>
 996 event_type</emphasis>
 997  and specifying the desired map changes in <emphasis>
 998 bits_to_change</emphasis>
 999  and <emphasis>
1000 values_for_bits</emphasis>
1001  using mask bits from Table 14.1.
1002 </para>
1003
1004
1005 <para>
1006 The structure for <emphasis>
1007 XkbMapNotify</emphasis>
1008  events is:
1009 </para>
1010
1011 <para><programlisting>
1012 typedef struct {
1013       int            type;         /* Xkb extension base event code */
1014       unsigned long  serial;       /* X server serial number for event */
1015       Bool           send_event;   /* <emphasis>True</emphasis> =&gt; synthetically generated */
1016       Display *      display;      /* server connection where event generated */
1017       Time           time;         /* server time when event generated */
1018       int            xkb_type;     /* <emphasis> XkbMapNotify</emphasis> */
1019       int            device;       /* Xkb device ID, will not be <emphasis>XkbUseCoreKbd</emphasis> */
1020       unsigned int   changed;      /* identifies valid fields in rest of event */
1021       unsigned int   resized;      /* reserved */
1022       int            first_type;   /* index of first key <emphasis> type</emphasis> modified */
1023       int            num_types     /* # types modified */
1024       KeyCode        min_key_code; /* minimum keycode for device */
1025       KeyCode        max_key_code; /* maximum keycode for device */
1026       KeyCode        first_key_sym; /* first key whose <emphasis>key_sym_map</emphasis> changed */
1027       KeyCode        first_key_act; /* first key whose <emphasis> key_acts</emphasis> entry changed */
1028       KeyCode        first_key_behavior; /* first key whose <emphasis> behaviors</emphasis> changed */
1029       KeyCode        first_key_explicit; /* first key whose <emphasis> explicit </emphasis> entry changed */
1030       KeyCode        first_modmap_key;   /* first key whose <emphasis> modmap</emphasis> entry changed */
1031       KeyCode        first_vmodmap_key;  /* # <emphasis> modmap</emphasis> entries changed */
1032       int            num_key_syms;       /* # <emphasis>key_sym_map</emphasis> entries changed */
1033       int            num_key_acts;       /* # <emphasis> key_acts</emphasis> entries changed */
1034       int            num_key_behaviors;  /* # <emphasis> behaviors</emphasis> entries changed */
1035       int            num_key_explicit;   /* # <emphasis> explicit</emphasis> entries changed */
1036       int            num_modmap_keys;    /* # <emphasis> modmap</emphasis> entries changed */
1037       int            num_vmodmap_keys;   /* # <emphasis> vmodmap</emphasis> entries changed */
1038       unsigned in      t      vmods;     /* mask indicating which <emphasis> vmods</emphasis> changed */
1039 } <emphasis>XkbMapNotifyEvent</emphasis>;
1040 </programlisting></para>
1041
1042 <para>
1043 The <emphasis>
1044 changed</emphasis>
1045  field specifies the map components that have changed and is the bitwise
1046 inclusive OR of the mask bits defined in Table 14.1. The other fields in this
1047 event are interpreted as the like-named fields in an <emphasis>
1048 XkbMapChangesRec</emphasis>
1049  (see section 14.3.1). The <emphasis>
1050 XkbMapNotifyEvent</emphasis>
1051  structure also has an additional <emphasis>
1052 resized</emphasis>
1053  field that is reserved for future use.
1054 </para>
1055
1056
1057 </sect1>
1058 <sect1 id='Allocating_and_Freeing_Client_and_Server_Maps'>
1059 <title>Allocating and Freeing Client and Server Maps</title>
1060
1061 <para>
1062 Calling <emphasis>
1063 XkbGetMap</emphasis>
1064  (see section 14.2) should be sufficient for most applications to get client
1065 and server maps. As a result, most applications do not need to directly
1066 allocate client and server maps.
1067 </para>
1068
1069
1070 <para>
1071 If you change the number of key types or construct map components without
1072 loading the necessary components from the X server, do not allocate any map
1073 components directly using <emphasis>
1074 malloc</emphasis>
1075  or <emphasis>
1076 Xmalloc</emphasis>
1077 . Instead, use the Xkb allocators, <emphasis>
1078 XkbAllocClientMap,</emphasis>
1079  and <emphasis>
1080 XkbAllocServerMap</emphasis>
1081 .
1082 </para>
1083
1084
1085 <para>
1086 Similarly, use the Xkb destructors, <emphasis>
1087 XkbFreeClientMap,</emphasis>
1088  and <emphasis>
1089 XkbFreeServerMap</emphasis>
1090  instead of <emphasis>
1091 free</emphasis>
1092  or <emphasis>
1093 Xfree</emphasis>
1094 .
1095 </para>
1096
1097
1098 <sect2 id='Allocating_an_Empty_Client_Map'>
1099 <title>Allocating an Empty Client Map</title>
1100
1101 <para>
1102 To allocate and initialize an empty client map description record, use
1103 <emphasis>
1104 XkbAllocClientMap.</emphasis>
1105 </para>
1106
1107 <informaltable frame='none'>
1108 <?dbfo keep-together="always" ?>
1109 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1110 <colspec colname='c1' colwidth='1.0*'/>
1111 <tbody>
1112   <row>
1113     <entry role='functiondecl'>
1114 Status <emphasis>
1115 XkbAllocClientMap</emphasis>
1116 (<emphasis>
1117 xkb, which, type_count</emphasis>
1118 )
1119     </entry>
1120   </row>
1121   <row>
1122     <entry role='functionargdecl'>
1123 XkbDescPtr <emphasis>
1124             xkb</emphasis>
1125 ;            /* keyboard description in which to allocate client map */
1126     </entry>
1127   </row>
1128   <row>
1129     <entry role='functionargdecl'>
1130 unsigned int<emphasis>
1131             which</emphasis>
1132 ;            /* mask selecting map components to allocate */
1133     </entry>
1134   </row>
1135   <row>
1136     <entry role='functionargdecl'>
1137 unsigned int<emphasis>
1138             type_count</emphasis>
1139 ;            /* value of <emphasis>
1140 num_types</emphasis>
1141  field in map to be allocated */
1142     </entry>
1143 </row>
1144 </tbody>
1145 </tgroup>
1146 </informaltable>
1147
1148 <para>
1149 <emphasis>
1150 XkbAllocClientMap</emphasis>
1151  allocates and initializes an empty client map in the <emphasis>
1152 map</emphasis>
1153  field of the keyboard description specified by <emphasis>
1154 xkb</emphasis>
1155 . The <emphasis>
1156 which</emphasis>
1157  parameter specifies the particular components of the client map structure to
1158 allocate and is a mask composed by a bitwise inclusive OR of one or more of the
1159 masks shown in Table 14.3.
1160 </para>
1161
1162 <table frame='topbot'>
1163 <title>XkbAllocClientMap Masks</title>
1164 <?dbfo keep-together="always" ?>
1165 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
1166 <colspec colname='c1' colwidth='1.0*'/>
1167 <colspec colname='c2' colwidth='2.0*'/>
1168 <thead>
1169 <row rowsep='1'>
1170   <entry>Mask</entry>
1171   <entry>Effect</entry>
1172   </row>
1173 </thead>
1174 <tbody>
1175   <row>
1176     <entry>XkbKeyTypesMask</entry>
1177     <entry>
1178 The <emphasis>
1179 type_count </emphasis>
1180 field specifies the number of entries to preallocate for the <emphasis>
1181 types</emphasis>
1182  field of the client map. If the <emphasis>
1183 type_count </emphasis>
1184 field is less than <emphasis>
1185 XkbNumRequiredTypes</emphasis>
1186  (see section 15.2.1), returns <emphasis>
1187 BadValue</emphasis>.
1188 </entry>
1189   </row>
1190   <row>
1191     <entry>XkbKeySymsMask</entry>
1192 <entry>
1193 The <emphasis>
1194 min_key_code</emphasis>
1195  and <emphasis>
1196 max_key_code</emphasis>
1197  fields of the <emphasis>
1198 xkb</emphasis>
1199  parameter are used to allocate the <emphasis>
1200 syms</emphasis>
1201  and <emphasis>
1202 key_sym_map</emphasis>
1203  fields of the client map. The fields are allocated to contain the maximum
1204 number of entries necessary for <emphasis>
1205 max_key_code</emphasis>
1206  - <emphasis>
1207 min_key_code</emphasis>
1208  + 1 keys.
1209 </entry>
1210   </row>
1211   <row>
1212     <entry>XkbModifierMapMask</entry>
1213 <entry>
1214 The <emphasis>
1215 min_key_code</emphasis>
1216  and <emphasis>
1217 max_key_code</emphasis>
1218  fields of the <emphasis>
1219 xkb</emphasis>
1220  parameter are used to allocate the <emphasis>
1221 modmap</emphasis>
1222  field of the client map. The field is allocated to contain the maximum number
1223 of entries necessary for <emphasis>
1224 max_key_code</emphasis>
1225  - <emphasis>
1226 min_key_code</emphasis>
1227  + 1 keys.
1228 </entry>
1229   </row>
1230 </tbody>
1231 </tgroup>
1232 </table>
1233
1234 <note><para>The <emphasis>
1235 min_key_code</emphasis>
1236  and <emphasis>
1237 max_key_code</emphasis>
1238  fields of the <emphasis>
1239 xkb</emphasis>
1240  parameter must be legal values if the <emphasis>
1241 XkbKeySymsMask</emphasis>
1242  or <emphasis>
1243 XkbModifierMapMask</emphasis>
1244  masks are set in the <emphasis>
1245 which</emphasis>
1246  parameter. If they are not valid, <emphasis>
1247 XkbAllocClientMap</emphasis>
1248  returns <emphasis>
1249 BadValue</emphasis>
1250 . </para></note>
1251
1252 <para>
1253 If the client map of the keyboard description is not <emphasis>
1254 NULL</emphasis>
1255 , and any fields are already allocated in the client map, <emphasis>
1256 XkbAllocClientMap</emphasis>
1257  does not overwrite the existing values; it simply ignores that part of the
1258 request. The only exception is the <emphasis>
1259 types</emphasis>
1260  array. If <emphasis>
1261 type_count</emphasis>
1262  is greater than the current <emphasis>
1263 num_types</emphasis>
1264  field of the client map, <emphasis>
1265 XkbAllocClientMap</emphasis>
1266  resizes the <emphasis>
1267 types</emphasis>
1268  array and resets the <emphasis>
1269 num_types</emphasis>
1270  field accordingly.
1271 </para>
1272
1273
1274 <para>
1275 If <emphasis>
1276 XkbAllocClientMap</emphasis>
1277  is successful, it returns <emphasis>
1278 Success</emphasis>
1279 . Otherwise, it can return either <emphasis>
1280 BadMatch</emphasis>
1281 , <emphasis>
1282 BadAlloc</emphasis>
1283 , or <emphasis>
1284 BadValue</emphasis>
1285  errors.
1286 </para>
1287
1288
1289 </sect2>
1290 <sect2 id='Freeing_a_Client_Map'>
1291 <title>Freeing a Client Map</title>
1292
1293 <para>
1294 To free memory used by the client map member of an <emphasis>
1295 XkbDescRec</emphasis>
1296  structure, use <emphasis>
1297 XkbFreeClientMap.</emphasis>
1298 </para>
1299
1300 <informaltable frame='none'>
1301 <?dbfo keep-together="always" ?>
1302 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1303 <colspec colname='c1' colwidth='1.0*'/>
1304 <tbody>
1305   <row>
1306     <entry role='functiondecl'>
1307 void <emphasis>
1308 XkbFreeClientMap</emphasis>
1309 (<emphasis>
1310 xkb, which, free_all</emphasis>
1311 )
1312     </entry>
1313   </row>
1314   <row>
1315     <entry role='functionargdecl'>
1316 XkbDescPtr <emphasis>
1317       xkb</emphasis>
1318 ;            /* keyboard description containing client map to free */
1319     </entry>
1320   </row>
1321   <row>
1322     <entry role='functionargdecl'>
1323 unsigned int<emphasis>
1324       which</emphasis>
1325 ;            /* mask identifying components of map to free */
1326     </entry>
1327   </row>
1328   <row>
1329     <entry role='functionargdecl'>
1330 Bool <emphasis>
1331       free_all</emphasis>
1332 ;            /* <emphasis>
1333 True</emphasis>
1334  =&gt; free all client components and map itself */
1335     </entry>
1336 </row>
1337 </tbody>
1338 </tgroup>
1339 </informaltable>
1340
1341 <para>
1342 <emphasis>
1343 XkbFreeClientMap</emphasis>
1344  frees the components of client map specified by <emphasis>
1345 which</emphasis>
1346  in the <emphasis>
1347 XkbDescRec</emphasis>
1348  structure specified by the <emphasis>
1349 xkb</emphasis>
1350  parameter and sets the corresponding structure component values to <emphasis>
1351 NULL</emphasis>
1352 . The <emphasis>
1353 which</emphasis>
1354  parameter specifies a combination of the client map masks shown in Table 14.3.
1355 </para>
1356
1357
1358 <para>
1359 If <emphasis>
1360 free_all</emphasis>
1361  is <emphasis>
1362 True</emphasis>
1363 , <emphasis>
1364 which</emphasis>
1365  is ignored; <emphasis>
1366 XkbFreeClientMap</emphasis>
1367  frees every non-<emphasis>
1368 NULL</emphasis>
1369  structure component in the client map, frees the <emphasis>
1370 XkbClientMapRec</emphasis>
1371  structure referenced by the <emphasis>
1372 map</emphasis>
1373  member of the <emphasis>
1374 xkb</emphasis>
1375  parameter, and sets the <emphasis>
1376 map</emphasis>
1377  member to <emphasis>
1378 NULL.</emphasis>
1379 </para>
1380
1381
1382 </sect2>
1383 <sect2 id='Allocating_an_Empty_Server_Map'>
1384 <title>Allocating an Empty Server Map</title>
1385
1386 <para>
1387 To allocate and initialize an empty server map description record, use
1388 <emphasis>
1389 XkbAllocServerMap.</emphasis>
1390 </para>
1391
1392 <informaltable frame='none'>
1393 <?dbfo keep-together="always" ?>
1394 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1395 <colspec colname='c1' colwidth='1.0*'/>
1396 <tbody>
1397   <row>
1398     <entry role='functiondecl'>
1399 Status <emphasis>
1400 XkbAllocServerMap</emphasis>
1401 (<emphasis>
1402 xkb, which, count_acts</emphasis>
1403 )
1404     </entry>
1405   </row>
1406   <row>
1407     <entry role='functionargdecl'>
1408 XkbDescPtr <emphasis>
1409             xkb</emphasis>
1410 ;            /* keyboard description in which to allocate server map */
1411     </entry>
1412   </row>
1413   <row>
1414     <entry role='functionargdecl'>
1415 unsigned int<emphasis>
1416             which</emphasis>
1417 ;            /* mask selecting map components to allocate */
1418     </entry>
1419   </row>
1420   <row>
1421     <entry role='functionargdecl'>
1422 unsigned int<emphasis>
1423             count_acts</emphasis>
1424 ;            /* value of <emphasis>
1425 num_acts</emphasis>
1426  field in map to be allocated */
1427     </entry>
1428 </row>
1429 </tbody>
1430 </tgroup>
1431 </informaltable>
1432
1433 <para>
1434 <emphasis>
1435 XkbAllocServerMap</emphasis>
1436  allocates and initializes an empty server map in the <emphasis>
1437 server</emphasis>
1438  field of the keyboard description specified by <emphasis>
1439 xkb</emphasis>
1440 . The <emphasis>
1441 which</emphasis>
1442  parameter specifies the particular components of the server map structure to
1443 allocate, as specified in Table 14.4.
1444 </para>
1445
1446 <table frame='topbot'>
1447 <title>XkbAllocServerMap Masks</title>
1448 <?dbfo keep-together="always" ?>
1449 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
1450 <colspec colname='c1' colwidth='1.0*'/>
1451 <colspec colname='c2' colwidth='2.0*'/>
1452 <thead>
1453 <row rowsep='1'>
1454   <entry>Mask</entry>
1455   <entry>Effect</entry>
1456   </row>
1457 </thead>
1458 <tbody>
1459   <row>
1460     <entry>XkbExplicitComponentsMask</entry>
1461     <entry>
1462 The <emphasis>
1463 min_key_code</emphasis>
1464  and <emphasis>
1465 max_key_code</emphasis>
1466  fields of the <emphasis>
1467 xkb</emphasis>
1468  parameter are used to allocate the <emphasis>
1469 explicit </emphasis>
1470 field of the server map.
1471     </entry>
1472   </row>
1473   <row>
1474     <entry>XkbKeyActionsMask</entry>
1475     <entry>
1476 The <emphasis>
1477 min_key_code</emphasis>
1478  and <emphasis>
1479 max_key_code</emphasis>
1480  fields of the <emphasis>
1481 xkb</emphasis>
1482  parameter are used to allocate the <emphasis>
1483 key_acts </emphasis>
1484 field of the server map. The <emphasis>
1485 count_acts</emphasis>
1486  parameter is used to allocate the <emphasis>
1487 acts</emphasis>
1488  field of the server map.
1489     </entry>
1490   </row>
1491   <row>
1492     <entry>XkbKeyBehaviorsMask</entry>
1493     <entry>
1494 The <emphasis>
1495 min_key_code</emphasis>
1496  and <emphasis>
1497 max_key_code</emphasis>
1498  fields of the <emphasis>
1499 xkb</emphasis>
1500  parameter are used to allocate the <emphasis>
1501 behaviors </emphasis>
1502 field of the server map.
1503     </entry>
1504   </row>
1505   <row>
1506     <entry>XkbVirtualModMapMask</entry>
1507     <entry>
1508 The <emphasis>
1509 min_key_code</emphasis>
1510  and <emphasis>
1511 max_key_code</emphasis>
1512  fields of the <emphasis>
1513 xkb </emphasis>
1514 parameter are used to allocate the <emphasis>
1515 vmodmap </emphasis>
1516 field of the server map.
1517     </entry>
1518   </row>
1519 </tbody>
1520 </tgroup>
1521 </table>
1522
1523 <note><para>The <emphasis>
1524 min_key_code</emphasis>
1525  and <emphasis>
1526 max_key_code</emphasis>
1527  fields of the <emphasis>
1528 xkb</emphasis>
1529  parameter must be legal values. If they are not valid, <emphasis>
1530 XkbAllocServerMap</emphasis>
1531  returns <emphasis>
1532 BadValue</emphasis>
1533 . </para></note>
1534
1535 <para>
1536 If the server map of the keyboard description is not <emphasis>
1537 NULL</emphasis>
1538  and any fields are already allocated in the server map, <emphasis>
1539 XkbAllocServerMap</emphasis>
1540  does not overwrite the existing values. The only exception is with the
1541 <emphasis>
1542 acts </emphasis>
1543 array. If the <emphasis>
1544 count_acts </emphasis>
1545 parameter is greater than the current <emphasis>
1546 num_acts </emphasis>
1547 field of the server map, <emphasis>
1548 XkbAllocServerMap</emphasis>
1549  resizes the <emphasis>
1550 acts </emphasis>
1551 array and resets the <emphasis>
1552 num_acts </emphasis>
1553 field accordingly.
1554 </para>
1555
1556
1557 <para>
1558 If <emphasis>
1559 XkbAllocServerMap</emphasis>
1560  is successful, it returns <emphasis>
1561 Success</emphasis>
1562 . Otherwise, it can return either <emphasis>
1563 BadMatch</emphasis>
1564  or <emphasis>
1565 BadAlloc</emphasis>
1566  errors.
1567 </para>
1568
1569
1570 </sect2>
1571 <sect2 id='Freeing_a_Server_Map'>
1572 <title>Freeing a Server Map</title>
1573
1574 <para>
1575 To free memory used by the server member of an <emphasis>
1576 XkbDescRec</emphasis>
1577  structure, use <emphasis>
1578 XkbFreeServerMap.</emphasis>
1579 </para>
1580
1581 <informaltable frame='none'>
1582 <?dbfo keep-together="always" ?>
1583 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1584 <colspec colname='c1' colwidth='1.0*'/>
1585 <tbody>
1586   <row>
1587     <entry role='functiondecl'>
1588 void <emphasis>
1589 XkbFreeServerMap</emphasis>
1590 (<emphasis>
1591 xkb, which, free_all</emphasis>
1592 )
1593     </entry>
1594   </row>
1595   <row>
1596     <entry role='functionargdecl'>
1597 XkbDescPtr <emphasis>
1598       xkb</emphasis>
1599 ;            /* keyboard description containing server map to free */
1600     </entry>
1601   </row>
1602   <row>
1603     <entry role='functionargdecl'>
1604 unsigned int<emphasis>
1605       which</emphasis>
1606 ;            /* mask identifying components of map to free */
1607     </entry>
1608   </row>
1609   <row>
1610     <entry role='functionargdecl'>
1611 Bool <emphasis>
1612       free_all</emphasis>
1613 ;            /* <emphasis>
1614 True</emphasis>
1615  =&gt; free all server map components and server itself */
1616     </entry>
1617 </row>
1618 </tbody>
1619 </tgroup>
1620 </informaltable>
1621
1622 <para>
1623 The <emphasis>
1624 XkbFreeServerMap</emphasis>
1625  function frees the specified components of server map in the <emphasis>
1626 XkbDescRec</emphasis>
1627  structure specified by the <emphasis>
1628 xkb</emphasis>
1629  parameter and sets the corresponding structure component values to <emphasis>
1630 NULL</emphasis>
1631 . The <emphasis>
1632 which</emphasis>
1633  parameter specifies a combination of the server map masks and is a bitwise
1634 inclusive OR of the masks listed in Table 14.4. If <emphasis>
1635 free_all</emphasis>
1636  is <emphasis>
1637 True</emphasis>
1638 , <emphasis>
1639 which</emphasis>
1640  is ignored and <emphasis>
1641 XkbFreeServerMap</emphasis>
1642  frees every non-<emphasis>
1643 NULL</emphasis>
1644  structure component in the server map, frees the <emphasis>
1645 XkbServerMapRec</emphasis>
1646  structure referenced by the <emphasis>
1647 server</emphasis>
1648  member of the <emphasis>
1649 xkb</emphasis>
1650  parameter, and sets the <emphasis>
1651 server</emphasis>
1652  member to <emphasis>
1653 NULL.</emphasis>
1654 </para>
1655
1656 </sect2>
1657 </sect1>
1658 </chapter>