specs/XKB/ch17.xml

   1 <chapter id='The_Xkb_Compatibility_Map'>
   2 <title>The Xkb Compatibility Map</title>
   3
   4 <para>
   5 As shown in Figure 17.1, the X server is normally dealing with more than one
   6 client, each of which may be receiving events from the keyboard, and each of
   7 which may issue requests to modify the keyboard in some manner. Each client may
   8 be either Xkb-unaware, Xkb-capable, or Xkb-aware. The server itself may be
   9 either Xkb-aware or Xkb-unaware. If the server is Xkb-unaware, Xkb state and
  10 keyboard mappings are not involved in any manner, and Xkb-aware clients may not
  11 issue Xkb requests to the server. If the server is Xkb-aware, the server must
  12 be able to deliver events and accept requests in which the keyboard state and
  13 mapping are compatible with the mode in which the client is operating.
  14 Consequently, for some situations, conversions must be made between Xkb state /
  15 keyboard mappings and core protocol state / keyboard mappings, and vice versa.
  16 </para>
  17
  18 <mediaobject>
  19  <imageobject> <imagedata format="SVG" fileref="XKBlib-18.svg"/>
  20  </imageobject>
  21  <caption>Server Interaction with Types of Clients</caption>
  22 </mediaobject>
  23
  24
  25
  26 <para>
  27 In addition to these situations involving a single server, there are cases
  28 where a client that deals with multiple servers may need to configure keyboards
  29 on different servers to be similar and the different servers may not all be
  30 Xkb-aware. Finally, a client may be dealing with descriptions of keyboards
  31 (files, and so on) that are based on core protocol and therefore may need to be
  32 able to map these descriptions to Xkb descriptions.
  33 </para>
  34
  35
  36 <para>
  37 An Xkb-aware server maintains keyboard state and mapping as an Xkb keyboard
  38 state and an Xkb keyboard mapping plus a compatibility map used to convert from
  39 Xkb components to core components and vice versa. In addition, the server also
  40 maintains a core keyboard mapping that approximates the Xkb keyboard mapping.
  41 The core keyboard mapping may be updated piecemeal, on a per-key basis. When
  42 the server receives a core protocol <emphasis>
  43 ChangeKeyboardMapping</emphasis>
  44  or <emphasis>
  45 SetModifierMapping</emphasis>
  46  request, it updates its core keyboard mapping, then uses the compatibility map
  47 to update its Xkb keyboard mapping. When the server receives an <emphasis>
  48 XkbSetMap</emphasis>
  49  request, it updates those portions of its Xkb keyboard mapping specified by
  50 the request, then uses its compatibility map to update the corresponding parts
  51 of its core keyboard map. Consequently, the server’s Xkb keyboard map and
  52 also its core keyboard map may contain components that were set directly and
  53 others that were computed. Figure 17.2 illustrates these relationships.
  54 </para>
  55
  56 <note><para>The core keyboard map is contained only in the server, not in any
  57 client-side data structures.</para></note>
  58
  59 <mediaobject>
  60  <imageobject> <imagedata format="SVG" fileref="XKBlib-19.svg"/>
  61  </imageobject>
  62  <caption>Server Derivation of State and Keyboard Mapping Components</caption>
  63 </mediaobject>
  64
  65
  66
  67 <para>
  68 There are three kinds of compatibility transformations made by the server:
  69 </para>
  70
  71 <orderedlist>
  72   <listitem>
  73     <para><emphasis role='bold'>Xkb State to Core State</emphasis></para>
  74     <para>
  75 Keyboard state information reported to a client in the state field of various
  76 core events may be translated from the Xkb keyboard state maintained by the
  77 server, which includes a group number, to core protocol state, which does
  78 not.
  79     </para>
  80     <para>
  81 In addition, whenever the Xkb state is retrieved, the <emphasis>
  82 compat_state</emphasis>
  83 , <emphasis>
  84 compat_grab_mods</emphasis>
  85 , and <emphasis>
  86 compat_lookup_mods</emphasis>
  87  fields of the <emphasis>
  88 XkbStateRec</emphasis>
  89  returned indicate the result of applying the compatibility map to the current
  90 Xkb state in the server.
  91     </para>
  92   </listitem>
  93   <listitem>
  94     <para><emphasis role='bold'>Core Keyboard Mapping to Xkb Keyboard Mapping</emphasis></para>
  95     <para>
  96 After core protocol requests received by the server to change the keyboard
  97 mapping (<emphasis>
  98 ChangeKeyboardMapping</emphasis>
  99  and <emphasis>
 100 SetModifierMapping</emphasis>
 101 ) have been applied to the server’s core keyboard map, the results must be
 102 transformed to achieve an equivalent change of the Xkb keyboard mapping
 103 maintained by the server.
 104     </para>
 105   </listitem>
 106   <listitem>
 107     <para><emphasis role='bold'>Xkb Keyboard Mapping to Core Keyboard Mapping</emphasis></para>
 108     <para>
 109 After Xkb protocol requests received by the server to change the keyboard
 110 mapping (<emphasis>
 111 XkbSetMap</emphasis>
 112 ) have been applied to the server’s Xkb keyboard map, the results are
 113 transformed to achieve an approximately equivalent change to the core keyboard
 114 mapping maintained by the server.
 115     </para>
 116   </listitem>
 117 </orderedlist>
 118
 119 <para>
 120 This chapter discusses how a client may modify the compatibility map so that
 121 subsequent transformations have a particular result.
 122 </para>
 123
 124
 125 <sect1 id='The_XkbCompatMap_Structure'>
 126 <title>The XkbCompatMap Structure</title>
 127
 128 <para>
 129 All configurable aspects of mapping Xkb state and configuration to and from
 130 core protocol state and configuration are defined by a compatibility map,
 131 contained in an <emphasis>
 132 XkbCompatMap</emphasis>
 133  structure; plus a set of explicit override controls used to prevent particular
 134 components of type 2 (core-to-Xkb keyboard mapping) transformations from
 135 automatically occurring. These explicit override controls are maintained in a
 136 separate data structure discussed in section 16.3. <!-- xref -->
 137 </para>
 138
 139
 140 <para>
 141 The <emphasis>
 142 compat</emphasis>
 143  member of an Xkb keyboard description (<emphasis>
 144 XkbDescRec</emphasis>
 145 ) points to the<emphasis>
 146  XkbCompatMap</emphasis>
 147  structure:
 148 </para>
 149
 150 <para><programlisting>
 151 typedef struct _XkbCompatMapRec {
 152       XkbSymInterpretPtr   sym_interpret;            /* symbol based key semantics*/
 153       XkbModsRec           groups[XkbNumKbdGroups];  /* group =&gt; modifier map */
 154       unsigned short       num_si;                   /* # structures used in
 155                                                         <emphasis>sym_interpret</emphasis> */
 156       unsigned short       size_si;                  /* # structures allocated in
 157                                                         <emphasis>sym_interpret</emphasis> */
 158 } <emphasis>XkbCompatMapRec</emphasis>, *XkbCompatMapPtr;
 159 </programlisting></para>
 160
 161 <mediaobject>
 162  <imageobject> <imagedata format="SVG" fileref="XKBlib-20.svg"/>
 163  </imageobject>
 164  <caption>Xkb Compatibility Data Structures</caption>
 165 </mediaobject>
 166
 167
 168 <para>
 169 The subsections that follow discuss how the compatibility map and explicit
 170 override controls are used in each of the three cases where compatibility
 171 transformations are made.
 172 </para>
 173
 174 <sect2 id='Xkb_State_to_Core_Protocol_State_Transformation'>
 175 <title>Xkb State to Core Protocol State Transformation</title>
 176
 177 <para>
 178 As shown in Figure 17.3, there are four <emphasis>
 179 group compatibility maps</emphasis>
 180  (contained in <emphasis>
 181 groups</emphasis>
 182  [0..3]) in the <emphasis>
 183 XkbCompatMapRec</emphasis>
 184  structure, one per possible Xkb group. Each group compatibility map is a
 185 modifier definition (see section 7.2 for a description of modifier
 186 definitions). The <emphasis>
 187 mask</emphasis>
 188  component of the definition specifies which real modifiers should be set in
 189 the core protocol state field when the corresponding group is active. Because
 190 only one group is active at any one time, only one of the four possible
 191 transformations is ever applied at any one point in time. If the device
 192 described by the <emphasis>
 193 XkbDescRec</emphasis>
 194  does not support four groups, the extra groups fields are present, but
 195 undefined.
 196 </para>
 197
 198 <para>
 199 Normally, the Xkb-aware server reports keyboard state in the <emphasis>
 200 state</emphasis>
 201  member of events such as a <emphasis>
 202 KeyPress</emphasis>
 203  event and <emphasis>
 204 ButtonPress</emphasis>
 205  event, encoded as follows:
 206 </para>
 207
 208 <informaltable frame='topbot'>
 209 <?dbfo keep-together="always" ?>
 210 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 211 <colspec colname='c1' colwidth='1.0*'/>
 212 <colspec colname='c1' colwidth='2.0*'/>
 213 <thead>
 214   <row rowsep='1'>
 215     <entry>bits</entry>
 216     <entry>meaning</entry>
 217   </row>
 218 </thead>
 219 <tbody>
 220   <row>
 221     <entry>15</entry>
 222     <entry>0</entry>
 223   </row>
 224   <row>
 225     <entry>13-14</entry>
 226     <entry>Group index</entry>
 227   </row>
 228   <row>
 229     <entry>8-12</entry>
 230     <entry>Pointer Buttons</entry>
 231   </row>
 232   <row>
 233     <entry>0-7</entry>
 234     <entry>Modifiers</entry>
 235   </row>
 236 </tbody>
 237 </tgroup>
 238 </informaltable>
 239
 240 <para>
 241 For Xkb-unaware clients, only core protocol keyboard information may be
 242 reported. Because core protocol does not define the group index, the group
 243 index is mapped to modifier bits as specified by the <emphasis>
 244 groups</emphasis>
 245 [group index] field of the compatibility map (the bits set in the compatibility
 246 map are ORed into bits 0-7 of the state), and bits 13-14 are reported in the
 247 event as zero.
 248 </para>
 249
 250 </sect2>
 251 <sect2 id='Core_Keyboard_Mapping_to_Xkb_Keyboard_Mapping_Transformation'>
 252 <title>Core Keyboard Mapping to Xkb Keyboard Mapping Transformation</title>
 253
 254 <para>
 255 When a core protocol keyboard mapping request is received by the server, the
 256 server’s core keyboard map is updated, and then the Xkb map maintained by the
 257 server is updated. Because a client may have explicitly configured some of the
 258 Xkb keyboard mapping in the server, this automatic regeneration of the Xkb
 259 keyboard mapping from the core protocol keyboard mapping should not modify any
 260 components of the Xkb keyboard mapping that were explicitly set by a client.
 261 The client must set explicit override controls to prevent this from happening
 262 (see section 16.3). The core-to-Xkb mapping is done as follows:
 263 </para>
 264
 265 <orderedlist>
 266   <listitem>
 267     <para>
 268 Map the symbols from the keys in the core keyboard map to groups and symbols on
 269 keys in the Xkb keyboard map. The core keyboard mapping is of fixed width, so
 270 each key in the core mapping has the same number of symbols associated with it.
 271 The Xkb mapping allows a different number of symbols to be associated with each
 272 key; those symbols may be divided into a different number of groups (1-4) for
 273 each key. For each key, this process therefore involves partitioning the fixed
 274 number of symbols from the core mapping into a set of variable-length groups
 275 with a variable number of symbols in each group. For example, if the core
 276 protocol map is of width five, the partition for one key might result in one
 277 group with two symbols and another with three symbols. A different key might
 278 result in two groups with two symbols plus a third group with one symbol. The
 279 core protocol map requires at least two symbols in each of the first two
 280 groups.
 281     </para>
 282     <orderedlist>
 283       <listitem>
 284         <para>
 285 For each changed key, determine the number of groups represented in the new
 286 core keyboard map. This results in a tentative group count for each key in the
 287 Xkb map.
 288         </para>
 289       </listitem>
 290       <listitem>
 291         <para>
 292 For each changed key, determine the number of symbols in each of the groups
 293 found in step 1a. There is one explicit override control associated with each
 294 of the four possible groups for each Xkb key, <emphasis>
 295 ExplicitKeyType1</emphasis>
 296  through <emphasis>
 297 ExplicitKeyType4</emphasis>
 298 . If no explicit override control is set for a group, the number of symbols
 299 used for that group from the core map is two.  If the explicit override control
 300 is set for a group on the key, the number of symbols used for that Xkb group
 301 from the core map is the width of the Xkb group with one exception: because of
 302 the core protocol requirement for at least two symbols in each of groups one
 303 and two, the number of symbols used for groups one and two is the maximum of 2
 304 or the width of the Xkb group.
 305         </para>
 306       </listitem>
 307       <listitem>
 308         <para>
 309 For each changed key, assign the symbols in the core map to the appropriate
 310 group on the key. If the total number of symbols required by the Xkb map for a
 311 particular key needs more symbols than the core protocol map contains, the
 312 additional symbols are taken to be <emphasis>
 313 NoSymbol</emphasis>
 314  keysyms appended to the end of the core set. If the core map contains more
 315 symbols than are needed by the Xkb map, trailing symbols in the core map are
 316 discarded. In the absence of an explicit override for group one or two, symbols
 317 are assigned in order by group; the first symbols in the core map are assigned
 318 to group one, in order, followed by group two, and so on. For example, if the
 319 core map contained eight symbols per key, and a particular Xkb map contained 2
 320 symbols for G1 and G2 and three for G3, the symbols would be assigned as (G is
 321 group, L is shift level):
 322         </para>
 323 <literallayout>
 324           G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3
 325 </literallayout>
 326         <para>
 327 If an explicit override control is set for group one or two, the symbols are
 328 taken from the core set in a somewhat different order. The first four symbols
 329 from the core set are assigned to G1L1, G1L2, G2L1, G2L2, respectively. If
 330 group one requires more symbols, they are taken next, and then any additional
 331 symbols needed by group two. Group three and four symbols are taken in complete
 332 sequence after group two. For example, a key with four groups and three symbols
 333 in each group would take symbols from the core set in the following order:
 334         </para>
 335 <literallayout>
 336 G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3
 337 </literallayout>
 338         <para>
 339 As previously noted, the core protocol map requires at lease two symbols in
 340 groups one and two. Because of this, if an explicit override control for an Xkb
 341 key is set and group one and / or group two is of width one, it is not possible
 342 to generate the symbols taken from the core protocol set and assigned to
 343 position G1L2 and / or G2L2.
 344         </para>
 345       </listitem>
 346       <listitem>
 347         <para>
 348 For each group on each changed key, assign a key type appropriate for the
 349 symbols in the group.
 350         </para>
 351       </listitem>
 352       <listitem>
 353         <para>
 354 For each changed key, remove any empty or redundant groups.
 355         </para>
 356       </listitem>
 357     </orderedlist>
 358   </listitem>
 359   <listitem>
 360     <para>
 361 At this point, the groups and their associated symbols have been assigned to
 362 the corresponding key definitions in the Xkb map.
 363     </para>
 364   </listitem>
 365   <listitem>
 366     <para>
 367 Apply symbol interpretations to modify key operation. This phase is completely
 368 skipped if the  <emphasis>
 369 ExplicitInterpret</emphasis>
 370  override control bit is set in the explicit controls mask for the Xkb key (see
 371 section 16.3).
 372     </para>
 373     <orderedlist>
 374       <listitem>
 375         <para>
 376 For each symbol on each changed key, attempt to match the symbol and modifiers
 377 from the Xkb map to a symbol interpretation describing how to generate the
 378 symbol.
 379         </para>
 380       </listitem>
 381       <listitem>
 382         <para>
 383 When a match is found in step 2a, apply the symbol interpretation to change the
 384 semantics associated with the symbol in the Xkb key map. If no match is found,
 385 apply a default interpretation.
 386         </para>
 387       </listitem>
 388     </orderedlist>
 389   </listitem>
 390 </orderedlist>
 391
 392 <para>
 393 The symbol interpretations used in step 2 are configurable and may be specified
 394 using <emphasis>
 395 XkbSymInterpretRec</emphasis>
 396  structures referenced by the <emphasis>
 397 sym_interpret</emphasis>
 398  field of an <emphasis>
 399 XkbCompatMapRec</emphasis>
 400  (see Figure 17.3).
 401 </para>
 402
 403 <sect3 id='Symbol_Interpretations__the_XkbSymInterpretRec_Structure'>
 404 <title>Symbol Interpretations — the XkbSymInterpretRec Structure</title>
 405
 406 <para>
 407 Symbol interpretations are used to guide the X server when it modifies the Xkb
 408 keymap in step 2. An initial set of symbol interpretations is loaded by the
 409 server when it starts. A client may add new ones using <emphasis>
 410 XkbSetCompatMap</emphasis>
 411  (see section 17.4).
 412 </para>
 413
 414
 415 <para>
 416 Symbol interpretations result in key semantics being set. When a symbol
 417 interpretation is applied, the following components of server key event
 418 processing may be modified for the particular key involved:
 419 </para>
 420
 421 <literallayout>
 422       Virtual modifier map
 423       Auto repeat
 424       Key behavior (may be set to <emphasis>XkbKB_Lock</emphasis>)
 425       Key action (see section 16.1)
 426 </literallayout>
 427
 428 <para>
 429 The <emphasis>XkbSymInterpretRec</emphasis>
 430 structure specifies a symbol interpretation:
 431 </para>
 432
 433 <para><programlisting>
 434 typedef struct {
 435       KeySym          sym;          /* keysym of interest or <emphasis>NULL</emphasis> */
 436       unsigned char   flags;        /* <emphasis>XkbSI_AutoRepeat, XkbSI_LockingKey</emphasis> */
 437       unsigned char   match;        /* specifies how mods is interpreted */
 438       unsigned char   mods;         /* modifier bits, correspond to eight real modifiers */
 439       unsigned char   virtual_mod;  /* 1 modifier to add to key virtual mod map */
 440       XkbAnyAction    act;          /* action to bind to symbol position on key */
 441 } <emphasis>XkbSymInterpretRec</emphasis>,*XkbSymInterpretPtr;
 442 </programlisting></para>
 443
 444 <para>
 445 If <emphasis>
 446 sym</emphasis>
 447  is not <emphasis>
 448 NULL</emphasis>
 449 , it limits the symbol interpretation to keys on which that particular keysym
 450 is selected by the modifiers matching the criteria specified by <emphasis>
 451 mods</emphasis>
 452  and <emphasis>
 453 match</emphasis>
 454 . If <emphasis>
 455 sym</emphasis>
 456  is <emphasis>
 457 NULL</emphasis>
 458 , the interpretation may be applied to any symbol selected on a key when the
 459 modifiers match the criteria specified by <emphasis>
 460 mods</emphasis>
 461  and <emphasis>
 462 match</emphasis>
 463 .
 464 </para>
 465
 466
 467 <para>
 468 <emphasis>match</emphasis>
 469 must be one of the values shown in Table 17.1 and specifies how the real
 470 modifiers specified in <emphasis>mods</emphasis>
 471 are to be interpreted.
 472 </para>
 473
 474 <table frame='topbot'>
 475 <title>Symbol Interpretation Match Criteria</title>
 476 <?dbfo keep-together="always" ?>
 477 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 478 <colspec colname='c1' colwidth='2.0*'/>
 479 <colspec colname='c2' colwidth='1.0*'/>
 480 <colspec colname='c3' colwidth='3.0*'/>
 481 <thead>
 482 <row rowsep='1'>
 483   <entry>Match Criteria</entry>
 484   <entry>Value</entry>
 485   <entry>Effect</entry>
 486   </row>
 487 </thead>
 488 <tbody>
 489   <row>
 490     <entry><emphasis>XkbSI_NoneOf</emphasis></entry>
 491     <entry>(0)</entry>
 492     <entry>
 493 None of the bits that are on in <emphasis>mods</emphasis>
 494  can be set, but other bits can be.
 495     </entry>
 496   </row>
 497   <row>
 498     <entry><emphasis>XkbSI_AnyOfOrNone</emphasis></entry>
 499     <entry>(1)</entry>
 500     <entry>
 501 Zero or more of the bits that are on in <emphasis>
 502 mods</emphasis>
 503  can be set, as well as others.
 504     </entry>
 505   </row>
 506   <row>
 507     <entry><emphasis>XkbSI_AnyOf</emphasis></entry>
 508     <entry>(2)</entry>
 509     <entry>
 510 One or more of the bits that are on in <emphasis>
 511 mods</emphasis>
 512  can be set, as well as any others.
 513     </entry>
 514   </row>
 515   <row>
 516     <entry><emphasis>XkbSI_AllOf</emphasis></entry>
 517     <entry>(3)</entry>
 518     <entry>
 519 All of the bits that are on in <emphasis>
 520 mods</emphasis>
 521  must be set, but others may be set as well.
 522     </entry>
 523   </row>
 524   <row>
 525     <entry><emphasis>XkbSI_Exactly</emphasis></entry>
 526     <entry>(4)</entry>
 527     <entry>
 528 All of the bits that are on in <emphasis>
 529 mods</emphasis>
 530  must be set, and no other bits may be set.
 531     </entry>
 532   </row>
 533 </tbody>
 534 </tgroup>
 535 </table>
 536
 537 <para>
 538 In addition to the above bits, <emphasis>
 539 match</emphasis>
 540  may contain the <emphasis>
 541 XkbSI_LevelOneOnly</emphasis>
 542  bit, in which case the modifier match criteria specified by <emphasis>
 543 mods</emphasis>
 544  and <emphasis>
 545 match</emphasis>
 546  applies only if <emphasis>
 547 sym</emphasis>
 548  is in level one of its group; otherwise, <emphasis>
 549 mods</emphasis>
 550  and <emphasis>
 551 match</emphasis>
 552  are ignored and the symbol matches a condition where no modifiers are set.
 553 </para>
 554
 555 <para><programlisting>
 556 #define XkbSI_LevelOneOnly  (0x80)
 557 /* use mods + match only if sym is level 1 */
 558 </programlisting></para>
 559
 560 <para>
 561 If no matching symbol interpretation is found, the server uses a default
 562 interpretation where:
 563 </para>
 564
 565 <informaltable frame='none'>
 566 <?dbfo keep-together="always" ?>
 567 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 568 <colspec colname='c1' colwidth='1.0*'/>
 569 <colspec colname='c1' colwidth='3.0*'/>
 570 <tbody>
 571   <row>
 572     <entry><emphasis>sym</emphasis> =</entry>
 573     <entry>0</entry>
 574   </row>
 575   <row>
 576     <entry><emphasis>flags</emphasis> =</entry>
 577     <entry><emphasis>XkbSI_AutoRepeat</emphasis></entry>
 578   </row>
 579   <row>
 580     <entry><emphasis>match</emphasis> =</entry>
 581     <entry><emphasis>XkbSI_AnyOfOrNone</emphasis></entry>
 582   </row>
 583   <row>
 584     <entry><emphasis>mods</emphasis> =</entry>
 585     <entry>0</entry>
 586   </row>
 587   <row>
 588     <entry><emphasis>virtual_mod</emphasis> =</entry>
 589     <entry><emphasis>XkbNoModifier</emphasis></entry>
 590   </row>
 591   <row>
 592
 593    <entry><emphasis>act</emphasis> =</entry>
 594     <entry><emphasis>SA_NoAction</emphasis></entry>
 595   </row>
 596 </tbody>
 597 </tgroup>
 598 </informaltable>
 599
 600 <para>
 601 When a matching symbol interpretation is found in step 2a, the interpretation
 602 is applied to modify the Xkb map as follows.
 603 </para>
 604
 605 <para>
 606 The <emphasis>
 607 act</emphasis>
 608  field specifies a single action to be bound to the symbol position; any key
 609 event that selects the symbol causes the action to be taken. Valid actions are
 610 defined in section 16.1.
 611 </para>
 612
 613
 614 <para>
 615 If the Xkb keyboard map for the key does not have its <emphasis>
 616 ExplicitVModMap</emphasis>
 617  control set, the <emphasis>
 618 XkbSI_LevelOneOnly</emphasis>
 619  bit and symbol position are examined. If the <emphasis>
 620 XkbSI_LevelOneOnly</emphasis>
 621  bit is not set in <emphasis>
 622 match</emphasis>
 623  or the symbol is in position G1L1, the <emphasis>
 624 virtual_mod</emphasis>
 625  field is examined. If <emphasis>
 626 virtual_mod</emphasis>
 627  is not <emphasis>
 628 XkbNoModifier</emphasis>
 629 , <emphasis>
 630 virtual_mod</emphasis>
 631  specifies a single virtual modifier to be added to the virtual modifier map
 632 for the key.<emphasis>
 633  virtual_mod</emphasis>
 634  is specified as an index in the range [0..15].
 635 </para>
 636
 637
 638 <para>
 639 If the matching symbol is in position G1L1 of the key, two bits in the flags
 640 field potentially specify additional behavior modifications:
 641 </para>
 642
 643 <para><programlisting>
 644 #define      XkbSI_AutoRepeat    (1&lt;&lt;0)
 645                                  /* key repeats if sym is in position G1L1 */
 646 #define      XkbSI_LockingKey    (1&lt;&lt;1)
 647                                  /* set <emphasis> KB_Lock</emphasis>
 648                                     behavior if sym is in psn G1L1 */
 649 </programlisting></para>
 650
 651 <para>
 652 If the Xkb keyboard map for the key does not have its <emphasis>
 653 ExplicitAutoRepeat</emphasis>
 654  control set, its auto repeat behavior is set based on the value of the
 655 <emphasis>
 656 XkbSI_AutoRepeat</emphasis>
 657  bit. If the <emphasis>
 658 XkbSI_AutoRepeat</emphasis>
 659  bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is
 660 turned off.
 661 </para>
 662
 663
 664 <para>
 665 If the Xkb keyboard map for the key does not have its <emphasis>
 666 ExplicitBehavior</emphasis>
 667  control set, its locking behavior is set based on the value of the <emphasis>
 668 XkbSI_LockingKey</emphasis>
 669  bit. If <emphasis>
 670 XkbSI_LockingKey</emphasis>
 671  is set, the key behavior is set to <emphasis>
 672 KB_Lock</emphasis>
 673 ; otherwise, it is turned off (see section 16.3).
 674 </para>
 675
 676
 677 </sect3>
 678 </sect2>
 679 <sect2 id='Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations'>
 680 <title>Xkb Keyboard Mapping to Core Keyboard Mapping Transformations</title>
 681
 682 <para>
 683 Whenever the server processes Xkb requests to change the keyboard mapping, it
 684 discards the affected portion of its core keyboard mapping and regenerates it
 685 based on the new Xkb mapping.
 686 </para>
 687
 688
 689 <para>
 690 When the Xkb mapping for a key is transformed to a core protocol mapping, the
 691 symbols for the core map are taken in the following order from the Xkb map:
 692 </para>
 693
 694
 695 <para>
 696 G1L1 G1L2 G2L1 G2L2 G1L3-n G2L3-n G3L1-n G4L1-n
 697 </para>
 698
 699
 700 <para>
 701 If group one is of width one in the Xkb map, G1L2 is taken to be NoSymbol;
 702 similarly, if group two is of width one in the Xkb map, G2L2 is taken to be
 703 NoSymbol.
 704 </para>
 705
 706
 707 <para>
 708 If the Xkb key map for a particular key has fewer groups than the core
 709 keyboard, the symbols for group one are repeated to fill in the missing core
 710 components. For example, an Xkb key with a single width-three group would be
 711 mapped to a core mapping counting three groups as:
 712 </para>
 713
 714
 715 <para>
 716 G1L1 G1L2 G1L1 G1L2 G1L3 G1L3 G1L1 G1L2 G1L3
 717 </para>
 718
 719
 720 <para>
 721 When a core keyboard map entry is generated from an Xkb keyboard map entry, a
 722 modifier mapping is generated as well. The modifier mapping contains all of the
 723 modifiers affected by any of the actions associated with the key combined with
 724 all of the real modifiers associated with any of the virtual modifiers bound to
 725 the key. In addition, if any of the actions associated with the key affect any
 726 component of the keyboard group, all of the modifiers in the <emphasis>
 727 mask</emphasis>
 728  field of all of the group compatibility maps are added to the modifier mapping
 729 as well. While an <emphasis>
 730 XkbSA_ISOLock</emphasis>
 731  action can theoretically affect any modifier, if the Xkb mapping for a key
 732 specifies an <emphasis>
 733 XkbSA_ISOLock</emphasis>
 734  action, only the modifiers or group that are set by default are added to the
 735 modifier mapping.
 736 </para>
 737
 738
 739 </sect2>
 740 </sect1>
 741 <sect1 id='Getting_Compatibility_Map_Components_From_the_Server'>
 742 <title>Getting Compatibility Map Components From the Server</title>
 743
 744 <para>
 745 Use <emphasis>
 746 XkbGetCompatMap</emphasis>
 747  to fetch any combination of the current compatibility map components from the
 748 server. When another client modifies the compatibility map, you are notified if
 749 you have selected for <emphasis>
 750 XkbCompatMapNotify</emphasis>
 751  events (see section 17.5). <emphasis>
 752 XkbGetCompatMap</emphasis>
 753  is particularly useful when you receive an event of this type, as it allows
 754 you to update your program’s version of the compatibility map to match the
 755 modified version now in the server. If your program is dealing with multiple
 756 servers and needs to configure them all in a similar manner, the updated
 757 compatibility map may be used to reconfigure other servers.
 758 </para>
 759
 760 <note><para>To make a complete matching configuration you must also update the
 761 explicit override components of the server state.</para></note>
 762
 763 <informaltable frame='none'>
 764 <?dbfo keep-together="always" ?>
 765 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 766 <colspec colname='c1' colwidth='1.0*'/>
 767 <tbody>
 768   <row>
 769     <entry role='functiondecl'>
 770 Status <emphasis>
 771 XkbGetCompatMap</emphasis>
 772 (<emphasis>
 773 display, which, xkb</emphasis>
 774 )
 775     </entry>
 776   </row>
 777   <row>
 778     <entry role='functionargdecl'>
 779 Display * <emphasis>
 780             display</emphasis>
 781 ;            /* connection to server */
 782     </entry>
 783   </row>
 784   <row>
 785     <entry role='functionargdecl'>
 786 unsigned int<emphasis>
 787             which</emphasis>
 788 ;            /* mask of compatibility map components to fetch */
 789     </entry>
 790   </row>
 791   <row>
 792     <entry role='functionargdecl'>
 793 XkbDescRec * <emphasis>
 794             xkb</emphasis>
 795 ;            /* keyboard description where results placed */
 796     </entry>
 797 </row>
 798 </tbody>
 799 </tgroup>
 800 </informaltable>
 801
 802 <para>
 803 <emphasis>
 804 XkbGetCompatMap</emphasis>
 805  fetches the components of the compatibility map specified in <emphasis>
 806 which</emphasis>
 807  from the server specified by <emphasis>
 808 display</emphasis>
 809  and places them in the <emphasis>
 810 compat</emphasis>
 811  structure of the keyboard description <emphasis>
 812 xkb</emphasis>
 813 . Valid values for <emphasis>
 814 which</emphasis>
 815  are an inclusive OR of the values shown in Table 17.2.
 816 </para>
 817
 818 <table frame='topbot'>
 819 <title>Compatibility Map Component Masks</title>
 820 <?dbfo keep-together="always" ?>
 821 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 822 <colspec colname='c1' colwidth='1.5*'/>
 823 <colspec colname='c2' colwidth='1.0*'/>
 824 <colspec colname='c3' colwidth='2.0*'/>
 825 <thead>
 826 <row rowsep='1'>
 827   <entry>Mask</entry>
 828   <entry>Value</entry>
 829   <entry>Affecting</entry>
 830   </row>
 831 </thead>
 832 <tbody>
 833   <row>
 834     <entry><emphasis>XkbSymInterpMask</emphasis></entry>
 835     <entry>(1&lt;&lt;0)</entry>
 836     <entry>Symbol interpretations</entry>
 837   </row>
 838   <row>
 839     <entry><emphasis>XkbGroupCompatMask</emphasis></entry>
 840     <entry>(1&lt;&lt;1)</entry>
 841     <entry>Group maps</entry>
 842   </row>
 843   <row>
 844     <entry><emphasis>XkbAllCompatMask</emphasis></entry>
 845     <entry>(0x3)</entry>
 846     <entry>All compatibility map components</entry>
 847   </row>
 848 </tbody>
 849 </tgroup>
 850 </table>
 851
 852 <para>
 853 If no compatibility map structure is allocated in <emphasis>
 854 xkb</emphasis>
 855  upon entry, <emphasis>
 856 XkbGetCompatMap</emphasis>
 857  allocates one. If one already exists, its contents are overwritten with the
 858 returned results.
 859 </para>
 860
 861
 862 <para>
 863 <emphasis>
 864 XkbGetCompatMap</emphasis>
 865  fetches compatibility map information for the device specified by the
 866 <emphasis>
 867 device_spec</emphasis>
 868  field of <emphasis>
 869 xkb</emphasis>
 870 . Unless you have specifically modified this field, it is the default keyboard
 871 device. <emphasis>
 872 XkbGetCompatMap</emphasis>
 873  returns <emphasis>
 874 Success</emphasis>
 875  if successful, <emphasis>
 876 BadAlloc</emphasis>
 877  if it is unable to obtain necessary storage for either the return values or
 878 work space, <emphasis>
 879 BadMatch</emphasis>
 880  if the <emphasis>
 881 dpy</emphasis>
 882  field of the <emphasis>
 883 xkb</emphasis>
 884  argument is non-<emphasis>
 885 NULL</emphasis>
 886  and does not match the <emphasis>
 887 display</emphasis>
 888  argument, and <emphasis>
 889 BadLength</emphasis>
 890  under certain conditions caused by server or Xkb implementation errors.
 891 </para>
 892
 893
 894 </sect1>
 895 <sect1 id='Using_the_Compatibility_Map'>
 896 <title>Using the Compatibility Map</title>
 897
 898 <para>
 899 Xkb provides several functions that make it easier to apply the compatibility
 900 map to configure a client-side Xkb keyboard mapping, given a core protocol
 901 representation of part or all of a keyboard mapping. Obtain a core protocol
 902 representation of a keyboard mapping from an actual server (by using <emphasis>
 903 XGetKeyboardMapping</emphasis>
 904 , for example), a data file, or some other source.
 905 </para>
 906
 907 <para>
 908 To update a local Xkb keyboard map to reflect the mapping expressed by a core
 909 format mapping by calling the function <emphasis>
 910 XkbUpdateMapFromCore</emphasis>
 911 .
 912 </para>
 913
 914 <informaltable frame='none'>
 915 <?dbfo keep-together="always" ?>
 916 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 917 <colspec colname='c1' colwidth='1.0*'/>
 918 <tbody>
 919   <row>
 920     <entry role='functiondecl'>
 921 Bool <emphasis>
 922 XkbUpdateMapFromCore</emphasis>
 923 (<emphasis>
 924 xkb</emphasis>
 925 ,<emphasis>
 926  first_key</emphasis>
 927 ,<emphasis>
 928  num_keys</emphasis>
 929 ,<emphasis>
 930  map_width</emphasis>
 931 ,<emphasis>
 932  core_keysyms</emphasis>
 933 ,<emphasis>
 934  changes</emphasis>
 935 )
 936     </entry>
 937   </row>
 938   <row>
 939     <entry role='functionargdecl'>
 940 XkbDescPtr <emphasis>
 941             xkb</emphasis>
 942 ;            /* keyboard description to update */
 943     </entry>
 944   </row>
 945   <row>
 946     <entry role='functionargdecl'>
 947 KeyCode <emphasis>
 948             first_key</emphasis>
 949 ;            /* keycode of first key description to update */
 950     </entry>
 951   </row>
 952   <row>
 953     <entry role='functionargdecl'>
 954 int <emphasis>
 955             num_keys</emphasis>
 956 ;            /* number of key descriptions to update */
 957     </entry>
 958   </row>
 959   <row>
 960     <entry role='functionargdecl'>
 961 int <emphasis>
 962             map_width</emphasis>
 963 ;            /* width of core protocol keymap */
 964     </entry>
 965   </row>
 966   <row>
 967     <entry role='functionargdecl'>
 968 KeySym *<emphasis>
 969             core_keysyms</emphasis>
 970 ;            /* symbols in core protocol keymap */
 971     </entry>
 972   </row>
 973   <row>
 974     <entry role='functionargdecl'>
 975 XkbChangesPtr       <emphasis>
 976       changes</emphasis>
 977 ;            /* backfilled with changes made to Xkb */
 978     </entry>
 979 </row>
 980 </tbody>
 981 </tgroup>
 982 </informaltable>
 983
 984 <para>
 985 <emphasis>
 986 XkbUpdateMapFromCore</emphasis>
 987  interprets input argument information representing a keyboard map in core
 988 format to update the Xkb keyboard description passed in <emphasis>
 989 xkb</emphasis>
 990 . Only a portion of the Xkb map is updated — the portion corresponding to
 991 keys with keycodes in the range <emphasis>
 992 first_key</emphasis>
 993  through <emphasis>
 994 first_key</emphasis>
 995  + <emphasis>
 996 num_keys</emphasis>
 997  - 1. If <emphasis>
 998 XkbUpdateMapFromCore</emphasis>
 999  is being called in response to a<emphasis>
1000  </emphasis>
1001 <emphasis>
1002 MappingNotify</emphasis>
1003 <emphasis>
1004  </emphasis>
1005 event<emphasis>
1006 , first_key</emphasis>
1007  and <emphasis>
1008 num_keys</emphasis>
1009  are reported in the <emphasis>
1010 MappingNotify</emphasis>
1011  event. <emphasis>
1012 core_keysyms</emphasis>
1013  contains the keysyms corresponding to the keycode range being updated, in core
1014 keyboard description order. <emphasis>
1015 map_width</emphasis>
1016  is the number of keysyms per key in <emphasis>
1017 core_keysyms</emphasis>
1018 . Thus, the first <emphasis>
1019 map_width</emphasis>
1020  entries in <emphasis>
1021 core_keysyms</emphasis>
1022  are for the key with keycode <emphasis>
1023 first_key</emphasis>
1024 , the next <emphasis>
1025 map_width</emphasis>
1026  entries are for key <emphasis>
1027 first_key</emphasis>
1028  + 1, and so on.
1029 </para>
1030
1031
1032 <para>
1033 In addition to modifying the Xkb keyboard mapping in <emphasis>
1034 xkb</emphasis>
1035 , <emphasis>
1036 XkbUpdateMapFromCore</emphasis>
1037  backfills the changes structure whose address is passed in <emphasis>
1038 changes</emphasis>
1039  to indicate the modifications that were made. You may then use <emphasis>
1040 changes</emphasis>
1041  in subsequent calls such as <emphasis>
1042 XkbSetMap</emphasis>
1043 , to propagate the local modifications to a server.
1044 </para>
1045
1046
1047 <para>
1048 When dealing with core keyboard mappings or descriptions, it is sometimes
1049 necessary to determine the Xkb key types appropriate for the symbols bound to a
1050 key in a core keyboard mapping. Use <emphasis>
1051 XkbKeyTypesForCoreSymbols</emphasis>
1052  for this purpose:
1053 </para>
1054
1055
1056 <informaltable frame='none'>
1057 <?dbfo keep-together="always" ?>
1058 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1059 <colspec colname='c1' colwidth='1.0*'/>
1060 <tbody>
1061   <row>
1062     <entry role='functiondecl'>
1063 int <emphasis>
1064 XkbKeyTypesForCoreSymbols</emphasis>
1065 (<emphasis>
1066 map_width</emphasis>
1067 ,<emphasis>
1068  core_syms</emphasis>
1069 ,<emphasis>
1070  protected, types_inout, xkb_syms_rtrn</emphasis>
1071 )
1072     </entry>
1073   </row>
1074   <row>
1075     <entry role='functionargdecl'>
1076 XkbDescPtr<emphasis>
1077       xkb</emphasis>
1078 ;            /* keyboard description in which to place symbols*/
1079     </entry>
1080   </row>
1081   <row>
1082     <entry role='functionargdecl'>
1083 int<emphasis>
1084       map_width</emphasis>
1085 ;            /* width of core protocol keymap in <emphasis>
1086 xkb_syms_rtrn</emphasis>
1087  */
1088     </entry>
1089   </row>
1090   <row>
1091     <entry role='functionargdecl'>
1092 KeySym *<emphasis>
1093       core_syms</emphasis>
1094 ;            /* core protocol format array of KeySyms */
1095     </entry>
1096   </row>
1097   <row>
1098     <entry role='functionargdecl'>
1099 unsigned int       <emphasis>
1100 protected</emphasis>
1101 ;            /* explicit key types */
1102     </entry>
1103   </row>
1104   <row>
1105     <entry role='functionargdecl'>
1106 int *<emphasis>
1107       types_inout;</emphasis>
1108             /* backfilled with the canonical types bound to groups one and two
1109 for the key */
1110     </entry>
1111   </row>
1112   <row>
1113     <entry role='functionargdecl'>
1114 KeySym *      <emphasis>
1115 xkb_syms_rtrn</emphasis>
1116       ;      /* backfilled with symbols bound to the key in the Xkb mapping */
1117     </entry>
1118 </row>
1119 </tbody>
1120 </tgroup>
1121 </informaltable>
1122
1123 <para>
1124 <emphasis>
1125 XkbKeyTypesForCoreSymbols</emphasis>
1126  expands the symbols in <emphasis>
1127 core_syms</emphasis>
1128  and types in <emphasis>
1129 types_inout</emphasis>
1130  according to the rules specified in section 12 of the core protocol, then
1131 chooses canonical key types (canonical key types are defined in section 15.2.1)
1132 for groups 1 and 2 using the rules specified by the Xkb protocol and places
1133 them in <emphasis>
1134 xkb_syms_rtrn</emphasis>
1135 , which will be non-<emphasis>
1136 NULL</emphasis>
1137 .
1138 </para>
1139
1140
1141 <para>
1142 A core keymap is a two-dimensional array of keysyms. It has <emphasis>
1143 map_width</emphasis>
1144  columns and <emphasis>
1145 max_key_code</emphasis>
1146  rows. <emphasis>
1147 XkbKeyTypesForCoreSymbols</emphasis>
1148  takes a single row from a core keymap, determines the number of groups
1149 associated with it, the type of each group, and the symbols bound to each
1150 group. The return value is the number of groups, <emphasis>
1151 types_inout</emphasis>
1152  has the types for each group, and <emphasis>
1153 xkb_syms_rtrn</emphasis>
1154  has the symbols in Xkb order (that is, groups are contiguous, regardless of
1155 size).
1156 </para>
1157
1158
1159 <para>
1160 <emphasis>
1161 protected</emphasis>
1162  contains the explicitly protected key types. There is one  explicit override
1163 control associated with each of the four possible groups for each Xkb key,
1164 <emphasis>
1165 ExplicitKeyType1</emphasis>
1166  through <emphasis>
1167 ExplicitKeyType4</emphasis>
1168 <emphasis>
1169 ; protected </emphasis>
1170 is an inclusive OR of these controls. <emphasis>
1171 map_width</emphasis>
1172  is the width of the core keymap and is not dependent on any Xkb definitions.
1173 <emphasis>
1174 types_inout</emphasis>
1175  is an array of four type indices. On input, <emphasis>
1176 types_inout</emphasis>
1177  contains the indices of any types already assigned to the key, in case they
1178 are explicitly protected from change.
1179 </para>
1180
1181
1182 <para>
1183 Upon return, <emphasis>
1184 types_inout</emphasis>
1185  contains any automatically selected (that is, canonical) types plus any
1186 protected types. Canonical types are assigned to all four groups if there are
1187 enough symbols to do so. The four entries in <emphasis>
1188 types_inout</emphasis>
1189  correspond to the four groups for the key in question.
1190 </para>
1191
1192
1193 <para>
1194 If the groups mapping does not change, but the symbols assigned to an Xkb
1195 keyboard compatibility map do change, the semantics of the key may be modified.
1196 To apply the new compatibility mapping to an individual key to get its
1197 semantics updated, use <emphasis>
1198 XkbApplyCompatMapToKey</emphasis>
1199 .
1200 </para>
1201
1202
1203 <informaltable frame='none'>
1204 <?dbfo keep-together="always" ?>
1205 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1206 <colspec colname='c1' colwidth='1.0*'/>
1207 <tbody>
1208   <row>
1209     <entry role='functiondecl'>
1210 Bool <emphasis>
1211 XkbApplyCompatMapToKey</emphasis>
1212 (<emphasis>
1213 xkb</emphasis>
1214 ,<emphasis>
1215  key</emphasis>
1216 ,<emphasis>
1217  changes</emphasis>
1218 )
1219     </entry>
1220   </row>
1221   <row>
1222     <entry role='functionargdecl'>
1223   XkbDescPtr<emphasis>
1224             xkb;            </emphasis>
1225 /* keyboard description to be updated */
1226     </entry>
1227   </row>
1228   <row>
1229     <entry role='functionargdecl'>
1230   KeyCode<emphasis>
1231             key</emphasis>
1232 ;            /* key to be updated */
1233     </entry>
1234   </row>
1235   <row>
1236     <entry role='functionargdecl'>
1237   XkbChangesPtr<emphasis>
1238             changes</emphasis>
1239 ;            /* notes changes to the Xkb keyboard description */
1240     </entry>
1241 </row>
1242 </tbody>
1243 </tgroup>
1244 </informaltable>
1245
1246 <para>
1247 <emphasis>
1248 XkbApplyCompatMapToKey</emphasis>
1249  essentially performs the operation described in section 17.1.2 to a specific
1250 key. This updates the behavior, actions, repeat status, and virtual modifier
1251 bindings of the key.
1252 </para>
1253
1254
1255 </sect1>
1256 <sect1 id='Changing_the_Servers_Compatibility_Map'>
1257 <title>Changing the Server’s Compatibility Map</title>
1258
1259 <para>
1260 To modify the server’s compatibility map, first modify a local copy of the
1261 Xkb compatibility map, then call <emphasis>
1262 XkbSetCompatMap</emphasis>
1263 . You may allocate a new compatibility map for this purpose using <emphasis>
1264 XkbAllocCompatMap</emphasis>
1265  (see section 17.6). You may also use a compatibility map from another server,
1266 although you need to adjust the <emphasis>
1267 device_spec</emphasis>
1268  field in the <emphasis>
1269 XkbDescRec</emphasis>
1270  accordingly. Note that symbol interpretations in a compatibility map
1271 (<emphasis>
1272 sym_interpret</emphasis>
1273 , the vector of <emphasis>
1274 XkbSymInterpretRec</emphasis>
1275  structures) are also allocated using this same function.
1276 </para>
1277
1278 <informaltable frame='none'>
1279 <?dbfo keep-together="always" ?>
1280 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1281 <colspec colname='c1' colwidth='1.0*'/>
1282 <tbody>
1283   <row>
1284     <entry role='functiondecl'>
1285 Bool <emphasis>
1286 XkbSetCompatMap</emphasis>
1287 (<emphasis>
1288 display, which, xkb, update_actions</emphasis>
1289 )
1290     </entry>
1291   </row>
1292   <row>
1293     <entry role='functionargdecl'>
1294 Display * <emphasis>
1295             display</emphasis>
1296 ;            /* connection to server */
1297     </entry>
1298   </row>
1299   <row>
1300     <entry role='functionargdecl'>
1301 unsigned int<emphasis>
1302             which</emphasis>
1303 ;            /* mask of compat map components to set */
1304     </entry>
1305   </row>
1306   <row>
1307     <entry role='functionargdecl'>
1308 XkbDescPtr <emphasis>
1309             xkb</emphasis>
1310 ;            /* source for compat map components */
1311     </entry>
1312   </row>
1313   <row>
1314     <entry role='functionargdecl'>
1315 Bool <emphasis>
1316             update_actions</emphasis>
1317 ;            /* <emphasis>
1318 True</emphasis>
1319  =&gt; apply to server’s keyboard map */
1320     </entry>
1321 </row>
1322 </tbody>
1323 </tgroup>
1324 </informaltable>
1325
1326 <para>
1327 <emphasis>
1328 XkbSetCompatMap</emphasis>
1329  copies compatibility map information from the keyboard description in
1330 <emphasis>
1331 xkb</emphasis>
1332  to the server specified in <emphasis>
1333 display</emphasis>
1334 ’s compatibility map for the device specified by the <emphasis>
1335 device_spec</emphasis>
1336  field of <emphasis>
1337 xkb</emphasis>
1338 . Unless you have specifically modified this field, it is the default keyboard
1339 device.<emphasis>
1340  which</emphasis>
1341  specifies the compatibility map components to be set, and is an inclusive OR
1342 of the bits shown in Table 17.2.
1343 </para>
1344
1345
1346 <para>
1347 After updating its compatibility map for the specified device, if <emphasis>
1348 update_actions</emphasis>
1349  is <emphasis>
1350 True,</emphasis>
1351  the server applies the new compatibility map to its entire keyboard for the
1352 device to generate a new set of key semantics, compatibility state, and a new
1353 core keyboard map. If <emphasis>
1354 update_actions</emphasis>
1355  is <emphasis>
1356 False</emphasis>
1357 , the new compatibility map is not used to generate any modifications to the
1358 current device semantics, state, or core keyboard map. One reason for not
1359 applying the compatibility map immediately would be if one server was being
1360 configured to match another on a piecemeal basis; the map should not be applied
1361 until everything is updated. To force an update at a later time, use <emphasis>
1362 XkbSetCompatMap</emphasis>
1363  specifying <emphasis>
1364 which</emphasis>
1365  as zero and <emphasis>
1366 update_actions</emphasis>
1367  as <emphasis>
1368 True</emphasis>
1369 .
1370 </para>
1371
1372
1373 <para>
1374 <emphasis>
1375 XkbSetCompatMap</emphasis>
1376  returns <emphasis>
1377 True</emphasis>
1378  if successful and <emphasis>
1379 False</emphasis>
1380  if unsuccessful. The server may report problems it encounters when processing
1381 the request subsequently via protocol errors.
1382 </para>
1383
1384
1385 <para>
1386 To add a symbol interpretation to the list of symbol interpretations in an
1387 <emphasis>
1388 XkbCompatRec</emphasis>
1389 , use <emphasis>
1390 XkbAddSymInterpret</emphasis>
1391 .
1392 </para>
1393
1394
1395 <informaltable frame='none'>
1396 <?dbfo keep-together="always" ?>
1397 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1398 <colspec colname='c1' colwidth='1.0*'/>
1399 <tbody>
1400   <row>
1401     <entry role='functiondecl'>
1402 XkbSymInterpretPtr <emphasis>
1403 XkbAddSymInterpret</emphasis>
1404 (<emphasis>
1405 xkb, si, updateMap, changes</emphasis>
1406 )
1407     </entry>
1408   </row>
1409   <row>
1410     <entry role='functionargdecl'>
1411 XkbDescPtr<emphasis>
1412             xkb</emphasis>
1413 ;            /* keyboard description to be updated */
1414     </entry>
1415   </row>
1416   <row>
1417     <entry role='functionargdecl'>
1418 XkbSymInterpretPtr<emphasis>
1419             si</emphasis>
1420 ;            /* symbol interpretation to be added */
1421     </entry>
1422   </row>
1423   <row>
1424     <entry role='functionargdecl'>
1425 Bool<emphasis>
1426             updateMap</emphasis>
1427 ;            /* <emphasis>
1428 True</emphasis>
1429 =&gt;apply compatibility map to keys */
1430     </entry>
1431   </row>
1432   <row>
1433     <entry role='functionargdecl'>
1434 XkbChangesPtr<emphasis>
1435             changes</emphasis>
1436 ;            /* changes are put here */
1437     </entry>
1438 </row>
1439 </tbody>
1440 </tgroup>
1441 </informaltable>
1442
1443 <para>
1444 <emphasis>
1445 XkbAddSymInterpret</emphasis>
1446  adds <emphasis>
1447 si</emphasis>
1448  to the list of symbol interpretations in <emphasis>
1449 xkb</emphasis>
1450 . If <emphasis>
1451 updateMap</emphasis>
1452  is <emphasis>
1453 True</emphasis>
1454 , it (re)applies the compatibility map to all of the keys on the keyboard. If
1455 <emphasis>
1456 changes</emphasis>
1457  is non-<emphasis>
1458 NULL</emphasis>
1459 , it reports the parts of the keyboard that were affected (unless <emphasis>
1460 updateMap</emphasis>
1461  is <emphasis>
1462 True</emphasis>
1463 , not much changes). <emphasis>
1464 XkbAddSymInterpret</emphasis>
1465  returns a pointer to the actual new symbol interpretation in the list or
1466 <emphasis>
1467 NULL</emphasis>
1468  if it failed.
1469 </para>
1470
1471
1472 </sect1>
1473 <sect1 id='Tracking_Changes_to_the_Compatibility_Map'>
1474 <title>Tracking Changes to the Compatibility Map</title>
1475
1476 <para>
1477 The server automatically generates <emphasis>
1478 MappingNotify</emphasis>
1479  events when the keyboard mapping changes. If you wish to be notified of
1480 changes to the compatibility map, you should select for <emphasis>
1481 XkbCompatMapNotify</emphasis>
1482  events. If you select for <emphasis>
1483 XkbMapNotify</emphasis>
1484  events, you no longer receive the automatically generated <emphasis>
1485 MappingNotify</emphasis>
1486  events. If you subsequently deselect <emphasis>
1487 XkbMapNotifyEvent</emphasis>
1488  delivery, you again receive <emphasis>
1489 MappingNotify</emphasis>
1490  events.
1491 </para>
1492
1493
1494 <para>
1495 To receive <emphasis>
1496 XkbCompatMapNotify</emphasis>
1497  events under all possible conditions, use <emphasis>
1498 XkbSelectEvents</emphasis>
1499  (see section 4.3) and pass <emphasis>
1500 XkbCompatMapNotifyMask</emphasis>
1501  in both <emphasis>
1502 bits_to_change</emphasis>
1503  and <emphasis>
1504 values_for_bits</emphasis>
1505 .
1506 </para>
1507
1508
1509 <para>
1510 To receive <emphasis>
1511 XkbCompatMapNotify</emphasis>
1512  events only under certain conditions, use <emphasis>
1513 XkbSelectEventDetails</emphasis>
1514  using <emphasis>
1515 XkbCompatMapNotify</emphasis>
1516  as the <emphasis>
1517 event_type</emphasis>
1518  and specifying the desired map changes in <emphasis>
1519 bits_to_change</emphasis>
1520  and <emphasis>
1521 values_for_bits</emphasis>
1522  using mask bits from Table 17.2.
1523 </para>
1524
1525
1526 <para>
1527 Note that you are notified of changes you make yourself, as well as changes
1528 made by other clients.
1529 </para>
1530
1531
1532 <para>
1533 The structure for the <emphasis>
1534 XkbCompatMapNotifyEvent</emphasis>
1535  is:
1536 </para>
1537
1538 <para><programlisting>
1539 typedef struct {
1540       int            type;          /* Xkb extension base event code */
1541       unsigned long  serial;        /* X server serial number for event */
1542       Bool           send_event;    /* <emphasis>True</emphasis> =&gt;
1543                                        synthetically generated */
1544       Display *      display;       /* server connection where event generated */
1545       Time           time;          /* server time when event generated */
1546       int            xkb_type;      /* <emphasis>XkbCompatMapNotify</emphasis> */
1547       int            device;        /* Xkb device ID, will not be
1548                                        <emphasis>XkbUseCoreKbd</emphasis> */
1549       unsigned int   changed_groups;/* number of group maps changed */
1550       int            first_si;      /* index to 1st changed symbol
1551                                        interpretation */
1552       int            num_si;        /* number of changed symbol
1553                                        interpretations */
1554       int            num_total_si;  /* total number of valid symbol
1555                                        interpretations */
1556 } <emphasis>XkbCompatMapNotifyEvent</emphasis>;
1557 </programlisting></para>
1558
1559 <para>
1560 <emphasis>
1561 changed_groups</emphasis>
1562  is the number of group compatibility maps that have changed. If you are
1563 maintaining a corresponding copy of the compatibility map, or get a fresh copy
1564 from the server using <emphasis>
1565 XkbGetCompatMap</emphasis>
1566 , <emphasis>
1567 changed_groups</emphasis>
1568  references <emphasis>
1569 groups</emphasis>
1570 [0..<emphasis>
1571 changed_groups</emphasis>
1572 -1] in the <emphasis>
1573 XkbCompatMapRec</emphasis>
1574  structure.
1575 </para>
1576
1577
1578 <para>
1579 <emphasis>
1580 first_si</emphasis>
1581  is the index of the first changed symbol interpretation, <emphasis>
1582 num_si</emphasis>
1583  is the number of changed symbol interpretations, and <emphasis>
1584 num_total_si</emphasis>
1585  is the total number of valid symbol interpretations. If you are maintaining a
1586 corresponding copy of the compatibility map, or get a fresh copy from the
1587 server using <emphasis>
1588 XkbGetCompatMap</emphasis>
1589 , <emphasis>
1590 first_si</emphasis>
1591 , <emphasis>
1592 num_si</emphasis>
1593 , and <emphasis>
1594 num_total_si</emphasis>
1595  are appropriate for use with the <emphasis>
1596 compat.sym_interpret</emphasis>
1597  vector in this structure.
1598 </para>
1599
1600
1601 </sect1>
1602 <sect1 id='Allocating_and_Freeing_the_Compatibility_Map'>
1603 <title>Allocating and Freeing the Compatibility Map</title>
1604
1605 <para>
1606 If you are modifying the compatibility map, you need to allocate a new
1607 compatibility map if you do not already have one available. To do so, use
1608 <emphasis>
1609 XkbAllocCompatMap</emphasis>
1610 .
1611 </para>
1612
1613 <informaltable frame='none'>
1614 <?dbfo keep-together="always" ?>
1615 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1616 <colspec colname='c1' colwidth='1.0*'/>
1617 <tbody>
1618   <row>
1619     <entry role='functiondecl'>
1620 Status <emphasis>
1621 XkbAllocCompatMap</emphasis>
1622 (<emphasis>
1623 xkb, which, num_si</emphasis>
1624 )
1625     </entry>
1626   </row>
1627   <row>
1628     <entry role='functionargdecl'>
1629 XkbDescPtr <emphasis>
1630       xkb</emphasis>
1631 ;            /* keyboard description in which to allocate compat map */
1632     </entry>
1633   </row>
1634   <row>
1635     <entry role='functionargdecl'>
1636 unsigned int<emphasis>
1637       which</emphasis>
1638 ;            /* mask of compatibility map components to allocate */
1639     </entry>
1640   </row>
1641   <row>
1642     <entry role='functionargdecl'>
1643 unsigned int<emphasis>
1644       num_si</emphasis>
1645 ;            /* number of symbol interpretations to allocate */
1646     </entry>
1647 </row>
1648 </tbody>
1649 </tgroup>
1650 </informaltable>
1651
1652 <para>
1653 <emphasis>
1654 xkb</emphasis>
1655  specifies the keyboard description for which compatibility maps are to be
1656 allocated. The compatibility map is the <emphasis>
1657 compat</emphasis>
1658  field in this structure.
1659 </para>
1660
1661
1662 <para>
1663 <emphasis>
1664 which</emphasis>
1665  specifies the compatibility map components to be allocated (see <emphasis>
1666 XkbGetCompatMap</emphasis>
1667 , in section 17.2). <emphasis>
1668 which</emphasis>
1669  is an inclusive OR of the bits shown in Table 17.2.
1670 </para>
1671
1672
1673 <para>
1674 <emphasis>
1675 num_si</emphasis>
1676  specifies the total number of entries to allocate in the symbol interpretation
1677 vector (<emphasis>
1678 xkb.compat.sym_interpret</emphasis>
1679 ).
1680 </para>
1681
1682
1683 <para>
1684 Note that symbol interpretations in a compatibility map (the <emphasis>
1685 sym_interpret</emphasis>
1686  vector of <emphasis>
1687 XkbSymInterpretRec</emphasis>
1688  structures) are also allocated using this same function. To ensure that there
1689 is sufficient space in the symbol interpretation vector for entries to be
1690 added, use <emphasis>
1691 XkbAllocCompatMap</emphasis>
1692  specifying <emphasis>
1693 which</emphasis>
1694  as <emphasis>
1695 XkbSymInterpretMask</emphasis>
1696  and the number of free symbol interpretations needed in <emphasis>
1697 num_si</emphasis>
1698 .
1699 </para>
1700
1701
1702 <para>
1703 <emphasis>
1704 XkbAllocCompatMap</emphasis>
1705  returns <emphasis>
1706 Success</emphasis>
1707  if successful, <emphasis>
1708 BadMatch</emphasis>
1709  if <emphasis>
1710 xkb</emphasis>
1711  is <emphasis>
1712 NULL</emphasis>
1713 , or <emphasis>
1714 BadAlloc</emphasis>
1715  if errors are encountered when attempting to allocate storage.
1716 </para>
1717
1718
1719 <para>
1720 To free an entire compatibility map or selected portions of one, use <emphasis>
1721 XkbFreeCompatMap</emphasis>
1722 .
1723 </para>
1724
1725
1726 <informaltable frame='none'>
1727 <?dbfo keep-together="always" ?>
1728 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1729 <colspec colname='c1' colwidth='1.0*'/>
1730 <tbody>
1731   <row>
1732     <entry role='functiondecl'>
1733 void <emphasis>
1734 XkbFreeCompatMap</emphasis>
1735 (<emphasis>
1736 xkb, which, free_map</emphasis>
1737 )
1738     </entry>
1739   </row>
1740   <row>
1741     <entry role='functionargdecl'>
1742 XkbDescPtr <emphasis>
1743       xkb</emphasis>
1744 ;            /* Xkb description in which to free compatibility map */
1745     </entry>
1746   </row>
1747   <row>
1748     <entry role='functionargdecl'>
1749 unsigned int<emphasis>
1750       which</emphasis>
1751 ;            /* mask of compatibility map components to free */
1752     </entry>
1753   </row>
1754   <row>
1755     <entry role='functionargdecl'>
1756 Bool <emphasis>
1757       free_map</emphasis>
1758 ;            /* <emphasis>
1759 True</emphasis>
1760  =&gt; free <emphasis>
1761 XkbCompatMap</emphasis>
1762  structure itself */
1763     </entry>
1764 </row>
1765 </tbody>
1766 </tgroup>
1767 </informaltable>
1768
1769 <para>
1770 <emphasis>
1771 which</emphasis>
1772  specifies the compatibility map components to be freed (see <emphasis>
1773 XkbGetCompatMap</emphasis>
1774 , in section 17.2). <emphasis>
1775 which</emphasis>
1776  is an inclusive OR of the bits shown in Table 17.2
1777 </para>
1778
1779
1780 <para>
1781 <emphasis>
1782 free_map</emphasis>
1783  indicates whether the <emphasis>
1784 XkbCompatMap</emphasis>
1785  structure itself should be freed. If <emphasis>
1786 free_map</emphasis>
1787  is <emphasis>
1788 True</emphasis>
1789 , <emphasis>
1790 which</emphasis>
1791  is ignored, all non-<emphasis>
1792 NULL</emphasis>
1793  compatibility map components are freed, and the <emphasis>
1794 compat</emphasis>
1795  field in the <emphasis>
1796 XkbDescRec</emphasis>
1797  referenced by <emphasis>
1798 xkb</emphasis>
1799  is set to <emphasis>
1800 NULL</emphasis>
1801 .
1802 </para>
1803
1804 </sect1>
1805 </chapter>