xorg-libx11/specs/XKB/ch17.xml

<chapter id='The_Xkb_Compatibility_Map'>
<title>The Xkb Compatibility Map</title>

<para>
As shown in Figure 17.1, the X server is normally dealing with more than one
client, each of which may be receiving events from the keyboard, and each of
which may issue requests to modify the keyboard in some manner. Each client may
be either Xkb-unaware, Xkb-capable, or Xkb-aware. The server itself may be
either Xkb-aware or Xkb-unaware. If the server is Xkb-unaware, Xkb state and
keyboard mappings are not involved in any manner, and Xkb-aware clients may not
issue Xkb requests to the server. If the server is Xkb-aware, the server must
be able to deliver events and accept requests in which the keyboard state and
mapping are compatible with the mode in which the client is operating.
Consequently, for some situations, conversions must be made between Xkb state /
keyboard mappings and core protocol state / keyboard mappings, and vice versa.
</para>

<mediaobject>
 <imageobject> <imagedata format="SVG" fileref="XKBlib-18.svg"/>
 </imageobject>
 <caption>Server Interaction with Types of Clients</caption>
</mediaobject>



<para>
In addition to these situations involving a single server, there are cases
where a client that deals with multiple servers may need to configure keyboards
on different servers to be similar and the different servers may not all be
Xkb-aware. Finally, a client may be dealing with descriptions of keyboards
(files, and so on) that are based on core protocol and therefore may need to be
able to map these descriptions to Xkb descriptions.
</para>


<para>
An Xkb-aware server maintains keyboard state and mapping as an Xkb keyboard
state and an Xkb keyboard mapping plus a compatibility map used to convert from
Xkb components to core components and vice versa. In addition, the server also
maintains a core keyboard mapping that approximates the Xkb keyboard mapping.
The core keyboard mapping may be updated piecemeal, on a per-key basis. When
the server receives a core protocol
<emphasis>ChangeKeyboardMapping</emphasis>
 or
<emphasis>SetModifierMapping</emphasis>
 request, it updates its core keyboard mapping, then uses the compatibility map
to update its Xkb keyboard mapping. When the server receives an
<function>XkbSetMap</function>
 request, it updates those portions of its Xkb keyboard mapping specified by
the request, then uses its compatibility map to update the corresponding parts
of its core keyboard map. Consequently, the server’s Xkb keyboard map and
also its core keyboard map may contain components that were set directly and
others that were computed. Figure 17.2 illustrates these relationships.
</para>

<note><para>The core keyboard map is contained only in the server, not in any
client-side data structures.</para></note>

<mediaobject>
 <imageobject> <imagedata format="SVG" fileref="XKBlib-19.svg"/>
 </imageobject>
 <caption>Server Derivation of State and Keyboard Mapping Components</caption>
</mediaobject>



<para>
There are three kinds of compatibility transformations made by the server:
</para>

<orderedlist>
  <listitem>
    <para><emphasis role='bold'>Xkb State to Core State</emphasis></para>
    <para>
Keyboard state information reported to a client in the state field of various
core events may be translated from the Xkb keyboard state maintained by the
server, which includes a group number, to core protocol state, which does
not.
    </para>
    <para>
In addition, whenever the Xkb state is retrieved, the
<emphasis>compat_state</emphasis>,
<emphasis>compat_grab_mods</emphasis>,
and
<emphasis>compat_lookup_mods</emphasis>
 fields of the
<emphasis>XkbStateRec</emphasis>
 returned indicate the result of applying the compatibility map to the current
Xkb state in the server.
    </para>
  </listitem>
  <listitem>
    <para><emphasis role='bold'>Core Keyboard Mapping to Xkb Keyboard Mapping</emphasis></para>
    <para>
After core protocol requests received by the server to change the keyboard
mapping (
<emphasis>ChangeKeyboardMapping</emphasis>
 and
<emphasis>SetModifierMapping</emphasis>
) have been applied to the server’s core keyboard map, the results must be
transformed to achieve an equivalent change of the Xkb keyboard mapping
maintained by the server.
    </para>
  </listitem>
  <listitem>
    <para><emphasis role='bold'>Xkb Keyboard Mapping to Core Keyboard Mapping</emphasis></para>
    <para>
After Xkb protocol requests received by the server to change the keyboard
mapping (
<function>XkbSetMap</function>
) have been applied to the server’s Xkb keyboard map, the results are
transformed to achieve an approximately equivalent change to the core keyboard
mapping maintained by the server.
    </para>
  </listitem>
</orderedlist>

<para>
This chapter discusses how a client may modify the compatibility map so that
subsequent transformations have a particular result.
</para>


<sect1 id='The_XkbCompatMap_Structure'>
<title>The XkbCompatMap Structure</title>

<para>
All configurable aspects of mapping Xkb state and configuration to and from
core protocol state and configuration are defined by a compatibility map,
contained in an
<emphasis>XkbCompatMap</emphasis>
 structure; plus a set of explicit override controls used to prevent particular
components of type 2 (core-to-Xkb keyboard mapping) transformations from
automatically occurring. These explicit override controls are maintained in a
separate data structure discussed in section 16.3. <!-- xref -->
</para>


<para>
The
<emphasis>compat</emphasis>
 member of an Xkb keyboard description (
<emphasis>XkbDescRec</emphasis>
) points to the
<emphasis>XkbCompatMap</emphasis>
 structure:
</para>

<para><programlisting>
typedef struct _XkbCompatMapRec {
      XkbSymInterpretPtr   sym_interpret;            /* symbol based key semantics*/
      XkbModsRec           groups[XkbNumKbdGroups];  /* group =&gt; modifier map */
      unsigned short       num_si;                   /* # structures used in
                                                        <emphasis>sym_interpret</emphasis> */
      unsigned short       size_si;                  /* # structures allocated in
                                                        <emphasis>sym_interpret</emphasis> */
} <emphasis>XkbCompatMapRec</emphasis>, *XkbCompatMapPtr;
</programlisting></para>

<mediaobject>
 <imageobject> <imagedata format="SVG" fileref="XKBlib-20.svg"/>
 </imageobject>
 <caption>Xkb Compatibility Data Structures</caption>
</mediaobject>


<para>
The subsections that follow discuss how the compatibility map and explicit
override controls are used in each of the three cases where compatibility
transformations are made.
</para>

<sect2 id='Xkb_State_to_Core_Protocol_State_Transformation'>
<title>Xkb State to Core Protocol State Transformation</title>

<para>
As shown in Figure 17.3, there are four
<emphasis>group compatibility maps</emphasis>
 (contained in
<emphasis>groups</emphasis>
 [0..3]) in the
<emphasis>XkbCompatMapRec</emphasis>
 structure, one per possible Xkb group. Each group compatibility map is a
modifier definition (see section 7.2 for a description of modifier
definitions). The
<emphasis>mask</emphasis>
 component of the definition specifies which real modifiers should be set in
the core protocol state field when the corresponding group is active. Because
only one group is active at any one time, only one of the four possible
transformations is ever applied at any one point in time. If the device
described by the
<emphasis>XkbDescRec</emphasis>
 does not support four groups, the extra groups fields are present, but
undefined.
</para>

<para>
Normally, the Xkb-aware server reports keyboard state in the
<emphasis>state</emphasis>
 member of events such as a
<emphasis>KeyPress</emphasis>
 event and
<emphasis>ButtonPress</emphasis>
 event, encoded as follows:
</para>

<informaltable frame='topbot'>
<?dbfo keep-together="always" ?>
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<colspec colname='c1' colwidth='2.0*'/>
<thead>
  <row rowsep='1'>
    <entry>bits</entry>
    <entry>meaning</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>15</entry>
    <entry>0</entry>
  </row>
  <row>
    <entry>13-14</entry>
    <entry>Group index</entry>
  </row>
  <row>
    <entry>8-12</entry>
    <entry>Pointer Buttons</entry>
  </row>
  <row>
    <entry>0-7</entry>
    <entry>Modifiers</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
For Xkb-unaware clients, only core protocol keyboard information may be
reported. Because core protocol does not define the group index, the group
index is mapped to modifier bits as specified by the
<emphasis>groups</emphasis>
[group index] field of the compatibility map (the bits set in the compatibility
map are ORed into bits 0-7 of the state), and bits 13-14 are reported in the
event as zero.
</para>

</sect2>
<sect2 id='Core_Keyboard_Mapping_to_Xkb_Keyboard_Mapping_Transformation'>
<title>Core Keyboard Mapping to Xkb Keyboard Mapping Transformation</title>

<para>
When a core protocol keyboard mapping request is received by the server, the
server’s core keyboard map is updated, and then the Xkb map maintained by the
server is updated. Because a client may have explicitly configured some of the
Xkb keyboard mapping in the server, this automatic regeneration of the Xkb
keyboard mapping from the core protocol keyboard mapping should not modify any
components of the Xkb keyboard mapping that were explicitly set by a client.
The client must set explicit override controls to prevent this from happening
(see section 16.3). The core-to-Xkb mapping is done as follows:
</para>

<orderedlist>
  <listitem>
    <para>
Map the symbols from the keys in the core keyboard map to groups and symbols on
keys in the Xkb keyboard map. The core keyboard mapping is of fixed width, so
each key in the core mapping has the same number of symbols associated with it.
The Xkb mapping allows a different number of symbols to be associated with each
key; those symbols may be divided into a different number of groups (1-4) for
each key. For each key, this process therefore involves partitioning the fixed
number of symbols from the core mapping into a set of variable-length groups
with a variable number of symbols in each group. For example, if the core
protocol map is of width five, the partition for one key might result in one
group with two symbols and another with three symbols. A different key might
result in two groups with two symbols plus a third group with one symbol. The
core protocol map requires at least two symbols in each of the first two
groups.
    </para>
    <orderedlist>
      <listitem>
        <para>
For each changed key, determine the number of groups represented in the new
core keyboard map. This results in a tentative group count for each key in the
Xkb map.
        </para>
      </listitem>
      <listitem>
        <para>
For each changed key, determine the number of symbols in each of the groups
found in step 1a. There is one explicit override control associated with each
of the four possible groups for each Xkb key,
<emphasis>ExplicitKeyType1</emphasis>
 through
<emphasis>ExplicitKeyType4</emphasis>.
If no explicit override control is set for a group, the number of symbols
used for that group from the core map is two.  If the explicit override control
is set for a group on the key, the number of symbols used for that Xkb group
from the core map is the width of the Xkb group with one exception: because of
the core protocol requirement for at least two symbols in each of groups one
and two, the number of symbols used for groups one and two is the maximum of 2
or the width of the Xkb group.
        </para>
      </listitem>
      <listitem>
        <para>
For each changed key, assign the symbols in the core map to the appropriate
group on the key. If the total number of symbols required by the Xkb map for a
particular key needs more symbols than the core protocol map contains, the
additional symbols are taken to be
<emphasis>NoSymbol</emphasis>
 keysyms appended to the end of the core set. If the core map contains more
symbols than are needed by the Xkb map, trailing symbols in the core map are
discarded. In the absence of an explicit override for group one or two, symbols
are assigned in order by group; the first symbols in the core map are assigned
to group one, in order, followed by group two, and so on. For example, if the
core map contained eight symbols per key, and a particular Xkb map contained 2
symbols for G1 and G2 and three for G3, the symbols would be assigned as (G is
group, L is shift level):
        </para>
<literallayout>
          G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3
</literallayout>
        <para>
If an explicit override control is set for group one or two, the symbols are
taken from the core set in a somewhat different order. The first four symbols
from the core set are assigned to G1L1, G1L2, G2L1, G2L2, respectively. If
group one requires more symbols, they are taken next, and then any additional
symbols needed by group two. Group three and four symbols are taken in complete
sequence after group two. For example, a key with four groups and three symbols
in each group would take symbols from the core set in the following order:
        </para>
<literallayout>
G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3
</literallayout>
        <para>
As previously noted, the core protocol map requires at lease two symbols in
groups one and two. Because of this, if an explicit override control for an Xkb
key is set and group one and / or group two is of width one, it is not possible
to generate the symbols taken from the core protocol set and assigned to
position G1L2 and / or G2L2.
        </para>
      </listitem>
      <listitem>
        <para>
For each group on each changed key, assign a key type appropriate for the
symbols in the group.
        </para>
      </listitem>
      <listitem>
        <para>
For each changed key, remove any empty or redundant groups.
        </para>
      </listitem>
    </orderedlist>
  </listitem>
  <listitem>
    <para>
At this point, the groups and their associated symbols have been assigned to
the corresponding key definitions in the Xkb map.
    </para>
  </listitem>
  <listitem>
    <para>
Apply symbol interpretations to modify key operation. This phase is completely
skipped if the
<emphasis>ExplicitInterpret</emphasis>
 override control bit is set in the explicit controls mask for the Xkb key (see
section 16.3).
    </para>
    <orderedlist>
      <listitem>
        <para>
For each symbol on each changed key, attempt to match the symbol and modifiers
from the Xkb map to a symbol interpretation describing how to generate the
symbol.
        </para>
      </listitem>
      <listitem>
        <para>
When a match is found in step 2a, apply the symbol interpretation to change the
semantics associated with the symbol in the Xkb key map. If no match is found,
apply a default interpretation.
        </para>
      </listitem>
    </orderedlist>
  </listitem>
</orderedlist>

<para>
The symbol interpretations used in step 2 are configurable and may be specified
using
<emphasis>XkbSymInterpretRec</emphasis>
 structures referenced by the
<emphasis>sym_interpret</emphasis>
 field of an
<emphasis>XkbCompatMapRec</emphasis>
 (see Figure 17.3).
</para>

<sect3 id='Symbol_Interpretations__the_XkbSymInterpretRec_Structure'>
<title>Symbol Interpretations — the XkbSymInterpretRec Structure</title>

<para>
Symbol interpretations are used to guide the X server when it modifies the Xkb
keymap in step 2. An initial set of symbol interpretations is loaded by the
server when it starts. A client may add new ones using
<function>XkbSetCompatMap</function>
 (see section 17.4).
</para>


<para>
Symbol interpretations result in key semantics being set. When a symbol
interpretation is applied, the following components of server key event
processing may be modified for the particular key involved:
</para>

<literallayout>
      Virtual modifier map
      Auto repeat
      Key behavior (may be set to <emphasis>XkbKB_Lock</emphasis>)
      Key action (see section 16.1)
</literallayout>

<para>
The <emphasis>XkbSymInterpretRec</emphasis>
structure specifies a symbol interpretation:
</para>

<para><programlisting>
typedef struct {
      KeySym          sym;          /* keysym of interest or <emphasis>NULL</emphasis> */
      unsigned char   flags;        /* <emphasis>XkbSI_AutoRepeat, XkbSI_LockingKey</emphasis> */
      unsigned char   match;        /* specifies how mods is interpreted */
      unsigned char   mods;         /* modifier bits, correspond to eight real modifiers */
      unsigned char   virtual_mod;  /* 1 modifier to add to key virtual mod map */
      XkbAnyAction    act;          /* action to bind to symbol position on key */
} <emphasis>XkbSymInterpretRec</emphasis>,*XkbSymInterpretPtr;
</programlisting></para>

<para>
If
<emphasis>sym</emphasis>
 is not
<emphasis>NULL</emphasis>,
it limits the symbol interpretation to keys on which that particular keysym
is selected by the modifiers matching the criteria specified by
<emphasis>mods</emphasis>
 and
<emphasis>match</emphasis>.
If
<emphasis>sym</emphasis>
 is
<emphasis>NULL</emphasis>,
the interpretation may be applied to any symbol selected on a key when the
modifiers match the criteria specified by
<emphasis>mods</emphasis>
 and
<emphasis>match</emphasis>.
</para>


<para>
<emphasis>match</emphasis>
must be one of the values shown in Table 17.1 and specifies how the real
modifiers specified in <emphasis>mods</emphasis>
are to be interpreted.
</para>

<table frame='topbot'>
<title>Symbol Interpretation Match Criteria</title>
<?dbfo keep-together="always" ?>
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='2.0*'/>
<colspec colname='c2' colwidth='1.0*'/>
<colspec colname='c3' colwidth='3.0*'/>
<thead>
<row rowsep='1'>
  <entry>Match Criteria</entry>
  <entry>Value</entry>
  <entry>Effect</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry><emphasis>XkbSI_NoneOf</emphasis></entry>
    <entry>(0)</entry>
    <entry>
None of the bits that are on in <emphasis>mods</emphasis>
 can be set, but other bits can be.
    </entry>
  </row>
  <row>
    <entry><emphasis>XkbSI_AnyOfOrNone</emphasis></entry>
    <entry>(1)</entry>
    <entry>
Zero or more of the bits that are on in
<emphasis>mods</emphasis>
 can be set, as well as others.
    </entry>
  </row>
  <row>
    <entry><emphasis>XkbSI_AnyOf</emphasis></entry>
    <entry>(2)</entry>
    <entry>
One or more of the bits that are on in
<emphasis>mods</emphasis>
 can be set, as well as any others.
    </entry>
  </row>
  <row>
    <entry><emphasis>XkbSI_AllOf</emphasis></entry>
    <entry>(3)</entry>
    <entry>
All of the bits that are on in
<emphasis>mods</emphasis>
 must be set, but others may be set as well.
    </entry>
  </row>
  <row>
    <entry><emphasis>XkbSI_Exactly</emphasis></entry>
    <entry>(4)</entry>
    <entry>
All of the bits that are on in
<emphasis>mods</emphasis>
 must be set, and no other bits may be set.
    </entry>
  </row>
</tbody>
</tgroup>
</table>

<para>
In addition to the above bits,
<emphasis>match</emphasis>
 may contain the
<emphasis>XkbSI_LevelOneOnly</emphasis>
 bit, in which case the modifier match criteria specified by
<emphasis>mods</emphasis>
 and
<emphasis>match</emphasis>
 applies only if
<emphasis>sym</emphasis>
 is in level one of its group; otherwise,
<emphasis>mods</emphasis>
 and
<emphasis>match</emphasis>
 are ignored and the symbol matches a condition where no modifiers are set.
</para>

<para><programlisting>
#define XkbSI_LevelOneOnly  (0x80)
/* use mods + match only if sym is level 1 */
</programlisting></para>

<para>
If no matching symbol interpretation is found, the server uses a default
interpretation where:
</para>

<informaltable frame='none'>
<?dbfo keep-together="always" ?>
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<colspec colname='c1' colwidth='3.0*'/>
<tbody>
  <row>
    <entry><emphasis>sym</emphasis> =</entry>
    <entry>0</entry>
  </row>
  <row>
    <entry><emphasis>flags</emphasis> =</entry>
    <entry><emphasis>XkbSI_AutoRepeat</emphasis></entry>
  </row>
  <row>
    <entry><emphasis>match</emphasis> =</entry>
    <entry><emphasis>XkbSI_AnyOfOrNone</emphasis></entry>
  </row>
  <row>
    <entry><emphasis>mods</emphasis> =</entry>
    <entry>0</entry>
  </row>
  <row>
    <entry><emphasis>virtual_mod</emphasis> =</entry>
    <entry><emphasis>XkbNoModifier</emphasis></entry>
  </row>
  <row>

   <entry><emphasis>act</emphasis> =</entry>
    <entry><emphasis>SA_NoAction</emphasis></entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
When a matching symbol interpretation is found in step 2a, the interpretation
is applied to modify the Xkb map as follows.
</para>

<para>
The
<emphasis>act</emphasis>
 field specifies a single action to be bound to the symbol position; any key
event that selects the symbol causes the action to be taken. Valid actions are
defined in section 16.1.
</para>


<para>
If the Xkb keyboard map for the key does not have its
<emphasis>ExplicitVModMap</emphasis>
 control set, the
<emphasis>XkbSI_LevelOneOnly</emphasis>
 bit and symbol position are examined. If the
<emphasis>XkbSI_LevelOneOnly</emphasis>
 bit is not set in
<emphasis>match</emphasis>
 or the symbol is in position G1L1, the
<emphasis>virtual_mod</emphasis>
 field is examined. If
<emphasis>virtual_mod</emphasis>
 is not
<emphasis>XkbNoModifier</emphasis>,
<emphasis>virtual_mod</emphasis>
 specifies a single virtual modifier to be added to the virtual modifier map
for the key.
<emphasis>virtual_mod</emphasis>
 is specified as an index in the range [0..15].
</para>


<para>
If the matching symbol is in position G1L1 of the key, two bits in the flags
field potentially specify additional behavior modifications:
</para>

<para><programlisting>
#define      XkbSI_AutoRepeat    (1&lt;&lt;0)
                                 /* key repeats if sym is in position G1L1 */
#define      XkbSI_LockingKey    (1&lt;&lt;1)
                                 /* set <emphasis> KB_Lock</emphasis>
                                    behavior if sym is in psn G1L1 */
</programlisting></para>

<para>
If the Xkb keyboard map for the key does not have its
<emphasis>ExplicitAutoRepeat</emphasis>
 control set, its auto repeat behavior is set based on the value of the
<emphasis>XkbSI_AutoRepeat</emphasis>
 bit. If the
<emphasis>XkbSI_AutoRepeat</emphasis>
 bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is
turned off.
</para>


<para>
If the Xkb keyboard map for the key does not have its
<emphasis>ExplicitBehavior</emphasis>
 control set, its locking behavior is set based on the value of the
<emphasis>XkbSI_LockingKey</emphasis>
 bit. If
<emphasis>XkbSI_LockingKey</emphasis>
 is set, the key behavior is set to
<emphasis>KB_Lock</emphasis>
; otherwise, it is turned off (see section 16.3).
</para>


</sect3>
</sect2>
<sect2 id='Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations'>
<title>Xkb Keyboard Mapping to Core Keyboard Mapping Transformations</title>

<para>
Whenever the server processes Xkb requests to change the keyboard mapping, it
discards the affected portion of its core keyboard mapping and regenerates it
based on the new Xkb mapping.
</para>


<para>
When the Xkb mapping for a key is transformed to a core protocol mapping, the
symbols for the core map are taken in the following order from the Xkb map:
</para>


<para>
G1L1 G1L2 G2L1 G2L2 G1L3-n G2L3-n G3L1-n G4L1-n
</para>


<para>
If group one is of width one in the Xkb map, G1L2 is taken to be NoSymbol;
similarly, if group two is of width one in the Xkb map, G2L2 is taken to be
NoSymbol.
</para>


<para>
If the Xkb key map for a particular key has fewer groups than the core
keyboard, the symbols for group one are repeated to fill in the missing core
components. For example, an Xkb key with a single width-three group would be
mapped to a core mapping counting three groups as:
</para>


<para>
G1L1 G1L2 G1L1 G1L2 G1L3 G1L3 G1L1 G1L2 G1L3
</para>


<para>
When a core keyboard map entry is generated from an Xkb keyboard map entry, a
modifier mapping is generated as well. The modifier mapping contains all of the
modifiers affected by any of the actions associated with the key combined with
all of the real modifiers associated with any of the virtual modifiers bound to
the key. In addition, if any of the actions associated with the key affect any
component of the keyboard group, all of the modifiers in the
<emphasis>mask</emphasis>
 field of all of the group compatibility maps are added to the modifier mapping
as well. While an
<emphasis>XkbSA_ISOLock</emphasis>
 action can theoretically affect any modifier, if the Xkb mapping for a key
specifies an
<emphasis>XkbSA_ISOLock</emphasis>
 action, only the modifiers or group that are set by default are added to the
modifier mapping.
</para>


</sect2>
</sect1>
<sect1 id='Getting_Compatibility_Map_Components_From_the_Server'>
<title>Getting Compatibility Map Components From the Server</title>

<para>
Use
<function>XkbGetCompatMap</function>
 to fetch any combination of the current compatibility map components from the
server. When another client modifies the compatibility map, you are notified if
you have selected for
<emphasis>XkbCompatMapNotify</emphasis>
 events (see section 17.5).
<function>XkbGetCompatMap</function>
 is particularly useful when you receive an event of this type, as it allows
you to update your program’s version of the compatibility map to match the
modified version now in the server. If your program is dealing with multiple
servers and needs to configure them all in a similar manner, the updated
compatibility map may be used to reconfigure other servers.
</para>

<note><para>To make a complete matching configuration you must also update the
explicit override components of the server state.</para></note>

<indexterm significance="preferred" zone="XkbGetCompatMap"><primary><function>XkbGetCompatMap</function></primary></indexterm>
<funcsynopsis id="XkbGetCompatMap">
  <funcprototype>
    <funcdef>Status <function>XkbGetCompatMap</function></funcdef>
<!-- (
<emphasis>display, which, xkb</emphasis>
) -->

    <paramdef>Display *<parameter>display</parameter></paramdef>
    <paramdef>unsigned int <parameter>which</parameter></paramdef>
    <paramdef>XkbDescRec *<parameter>xkb</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>display</parameter>
    </term>
    <listitem>
      <para>
        connection to server
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>which</parameter>
    </term>
    <listitem>
      <para>
        mask of compatibility map components to fetch
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        keyboard description where results placed
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XkbGetCompatMap</function>
 fetches the components of the compatibility map specified in
<emphasis>which</emphasis>
 from the server specified by
<emphasis>display</emphasis>
 and places them in the
<emphasis>compat</emphasis>
 structure of the keyboard description
<emphasis>xkb</emphasis>.
Valid values for
<emphasis>which</emphasis>
 are an inclusive OR of the values shown in Table 17.2.
</para>

<table frame='topbot'>
<title>Compatibility Map Component Masks</title>
<?dbfo keep-together="always" ?>
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.5*'/>
<colspec colname='c2' colwidth='1.0*'/>
<colspec colname='c3' colwidth='2.0*'/>
<thead>
<row rowsep='1'>
  <entry>Mask</entry>
  <entry>Value</entry>
  <entry>Affecting</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry><emphasis>XkbSymInterpMask</emphasis></entry>
    <entry>(1&lt;&lt;0)</entry>
    <entry>Symbol interpretations</entry>
  </row>
  <row>
    <entry><emphasis>XkbGroupCompatMask</emphasis></entry>
    <entry>(1&lt;&lt;1)</entry>
    <entry>Group maps</entry>
  </row>
  <row>
    <entry><emphasis>XkbAllCompatMask</emphasis></entry>
    <entry>(0x3)</entry>
    <entry>All compatibility map components</entry>
  </row>
</tbody>
</tgroup>
</table>

<para>
If no compatibility map structure is allocated in
<emphasis>xkb</emphasis>
 upon entry,
<function>XkbGetCompatMap</function>
 allocates one. If one already exists, its contents are overwritten with the
returned results.
</para>


<para>
<function>XkbGetCompatMap</function>
 fetches compatibility map information for the device specified by the
<emphasis>device_spec</emphasis>
 field of
<emphasis>xkb</emphasis>.
Unless you have specifically modified this field, it is the default keyboard
device.
<function>XkbGetCompatMap</function>
 returns
<emphasis>Success</emphasis>
 if successful,
<emphasis>BadAlloc</emphasis>
 if it is unable to obtain necessary storage for either the return values or
work space,
<emphasis>BadMatch</emphasis>
 if the
<emphasis>dpy</emphasis>
 field of the
<emphasis>xkb</emphasis>
 argument is non-
<emphasis>NULL</emphasis>
 and does not match the
<emphasis>display</emphasis>
 argument, and
<emphasis>BadLength</emphasis>
 under certain conditions caused by server or Xkb implementation errors.
</para>


</sect1>
<sect1 id='Using_the_Compatibility_Map'>
<title>Using the Compatibility Map</title>

<para>
Xkb provides several functions that make it easier to apply the compatibility
map to configure a client-side Xkb keyboard mapping, given a core protocol
representation of part or all of a keyboard mapping. Obtain a core protocol
representation of a keyboard mapping from an actual server (by using
<emphasis>XGetKeyboardMapping</emphasis>,
for example), a data file, or some other source.
</para>

<para>
To update a local Xkb keyboard map to reflect the mapping expressed by a core
format mapping by calling the function
<function>XkbUpdateMapFromCore</function>.
</para>

<indexterm significance="preferred" zone="XkbUpdateMapFromCore"><primary><function>XkbUpdateMapFromCore</function></primary></indexterm>
<funcsynopsis id="XkbUpdateMapFromCore">
  <funcprototype>
    <funcdef>Bool <function>XkbUpdateMapFromCore</function></funcdef>
<!-- (
<emphasis>xkb</emphasis>,
<emphasis>first_key</emphasis>,
<emphasis>num_keys</emphasis>,
<emphasis>map_width</emphasis>,
<emphasis>core_keysyms</emphasis>,
<emphasis>changes</emphasis>
) -->

    <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
    <paramdef>KeyCode <parameter>first_key</parameter></paramdef>
    <paramdef>int <parameter>num_keys</parameter></paramdef>
    <paramdef>int <parameter>map_width</parameter></paramdef>
    <paramdef>KeySym *<parameter>core_keysyms</parameter></paramdef>
    <paramdef>XkbChangesPtr <parameter>changes</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        keyboard description to update
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>first_key</parameter>
    </term>
    <listitem>
      <para>
        keycode of first key description to update
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>num_keys</parameter>
    </term>
    <listitem>
      <para>
        number of key descriptions to update
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>map_width</parameter>
    </term>
    <listitem>
      <para>
        width of core protocol keymap
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>core_keysyms</parameter>
    </term>
    <listitem>
      <para>
        symbols in core protocol keymap
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>changes</parameter>
    </term>
    <listitem>
      <para>
        backfilled with changes made to Xkb
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XkbUpdateMapFromCore</function>
 interprets input argument information representing a keyboard map in core
format to update the Xkb keyboard description passed in
<emphasis>xkb</emphasis>.
Only a portion of the Xkb map is updated — the portion corresponding to
keys with keycodes in the range
<emphasis>first_key</emphasis>
 through
<emphasis>first_key</emphasis>
 +
<emphasis>num_keys</emphasis>
 - 1. If
<function>XkbUpdateMapFromCore</function>
 is being called in response to a
<emphasis>MappingNotify</emphasis>

event<emphasis>,
first_key</emphasis>
 and
<emphasis>num_keys</emphasis>
 are reported in the
<emphasis>MappingNotify</emphasis>
 event.
<emphasis>core_keysyms</emphasis>
 contains the keysyms corresponding to the keycode range being updated, in core
keyboard description order.
<emphasis>map_width</emphasis>
 is the number of keysyms per key in
<emphasis>core_keysyms</emphasis>.
Thus, the first
<emphasis>map_width</emphasis>
 entries in
<emphasis>core_keysyms</emphasis>
 are for the key with keycode
<emphasis>first_key</emphasis>,
the next
<emphasis>map_width</emphasis>
 entries are for key
<emphasis>first_key</emphasis>
 + 1, and so on.
</para>


<para>
In addition to modifying the Xkb keyboard mapping in
<emphasis>xkb</emphasis>,
<function>XkbUpdateMapFromCore</function>
 backfills the changes structure whose address is passed in
<emphasis>changes</emphasis>
 to indicate the modifications that were made. You may then use
<emphasis>changes</emphasis>
 in subsequent calls such as
<function>XkbSetMap</function>,
to propagate the local modifications to a server.
</para>


<para>
When dealing with core keyboard mappings or descriptions, it is sometimes
necessary to determine the Xkb key types appropriate for the symbols bound to a
key in a core keyboard mapping. Use
<function>XkbKeyTypesForCoreSymbols</function>
 for this purpose:
</para>


<indexterm significance="preferred" zone="XkbKeyTypesForCoreSymbols"><primary><function>XkbKeyTypesForCoreSymbols</function></primary></indexterm>
<funcsynopsis id="XkbKeyTypesForCoreSymbols">
  <funcprototype>
    <funcdef>int <function>XkbKeyTypesForCoreSymbols</function></funcdef>
<!-- (
<emphasis>map_width</emphasis>,
<emphasis>core_syms</emphasis>,
<emphasis>protected, types_inout, xkb_syms_rtrn</emphasis>
) -->

    <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
    <paramdef>int <parameter>map_width</parameter></paramdef>
    <paramdef>KeySym *<parameter>core_syms</parameter></paramdef>
    <paramdef>unsigned int <parameter>protected</parameter></paramdef>
    <paramdef>int *<parameter>types_inout</parameter></paramdef>
    <paramdef>KeySym *<parameter>xkb_syms_rtrn</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        keyboard description in which to place symbols
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>map_width</parameter>
    </term>
    <listitem>
      <para>
        width of core protocol keymap in <parameter>xkb_syms_rtrn</parameter>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>core_syms</parameter>
    </term>
    <listitem>
      <para>
        core protocol format array of KeySyms
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>protected</parameter>
    </term>
    <listitem>
      <para>
        explicit key types
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>types_inout</parameter>
    </term>
    <listitem>
      <para>
        backfilled with the canonical types bound to groups one and two
        for the key
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>xkb_syms_rtrn</parameter>
    </term>
    <listitem>
      <para>
        backfilled with symbols bound to the key in the Xkb mapping
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XkbKeyTypesForCoreSymbols</function>
 expands the symbols in
<emphasis>core_syms</emphasis>
 and types in
<emphasis>types_inout</emphasis>
 according to the rules specified in section 12 of the core protocol, then
chooses canonical key types (canonical key types are defined in section 15.2.1)
for groups 1 and 2 using the rules specified by the Xkb protocol and places
them in
<emphasis>xkb_syms_rtrn</emphasis>,
which will be non-
<emphasis>NULL</emphasis>.
</para>


<para>
A core keymap is a two-dimensional array of keysyms. It has
<emphasis>map_width</emphasis>
 columns and
<emphasis>max_key_code</emphasis>
 rows.
<function>XkbKeyTypesForCoreSymbols</function>
 takes a single row from a core keymap, determines the number of groups
associated with it, the type of each group, and the symbols bound to each
group. The return value is the number of groups,
<emphasis>types_inout</emphasis>
 has the types for each group, and
<emphasis>xkb_syms_rtrn</emphasis>
 has the symbols in Xkb order (that is, groups are contiguous, regardless of
size).
</para>


<para>
<emphasis>protected</emphasis>
 contains the explicitly protected key types. There is one  explicit override
control associated with each of the four possible groups for each Xkb key,
<emphasis>ExplicitKeyType1</emphasis>
 through
<emphasis>ExplicitKeyType4</emphasis>
<emphasis>; protected </emphasis>
is an inclusive OR of these controls.
<emphasis>map_width</emphasis>
 is the width of the core keymap and is not dependent on any Xkb definitions.
<emphasis>types_inout</emphasis>
 is an array of four type indices. On input,
<emphasis>types_inout</emphasis>
 contains the indices of any types already assigned to the key, in case they
are explicitly protected from change.
</para>


<para>
Upon return,
<emphasis>types_inout</emphasis>
 contains any automatically selected (that is, canonical) types plus any
protected types. Canonical types are assigned to all four groups if there are
enough symbols to do so. The four entries in
<emphasis>types_inout</emphasis>
 correspond to the four groups for the key in question.
</para>


<para>
If the groups mapping does not change, but the symbols assigned to an Xkb
keyboard compatibility map do change, the semantics of the key may be modified.
To apply the new compatibility mapping to an individual key to get its
semantics updated, use
<function>XkbApplyCompatMapToKey</function>.
</para>


<indexterm significance="preferred" zone="XkbApplyCompatMapToKey"><primary><function>XkbApplyCompatMapToKey</function></primary></indexterm>
<funcsynopsis id="XkbApplyCompatMapToKey">
  <funcprototype>
    <funcdef>Bool <function>XkbApplyCompatMapToKey</function></funcdef>
<!-- (
<emphasis>xkb</emphasis>,
<emphasis>key</emphasis>,
<emphasis>changes</emphasis>
) -->

    <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
    <paramdef>KeyCode <parameter>key</parameter></paramdef>
    <paramdef>XkbChangesPtr <parameter>changes</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        keyboard description to be updated
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>key</parameter>
    </term>
    <listitem>
      <para>
        key to be updated
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>changes</parameter>
    </term>
    <listitem>
      <para>
        notes changes to the Xkb keyboard description
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XkbApplyCompatMapToKey</function>
 essentially performs the operation described in section 17.1.2 to a specific
key. This updates the behavior, actions, repeat status, and virtual modifier
bindings of the key.
</para>


</sect1>
<sect1 id='Changing_the_Servers_Compatibility_Map'>
<title>Changing the Server’s Compatibility Map</title>

<para>
To modify the server’s compatibility map, first modify a local copy of the
Xkb compatibility map, then call
<function>XkbSetCompatMap</function>.
You may allocate a new compatibility map for this purpose using
<function>XkbAllocCompatMap</function>
 (see section 17.6). You may also use a compatibility map from another server,
although you need to adjust the
<emphasis>device_spec</emphasis>
 field in the
<emphasis>XkbDescRec</emphasis>
 accordingly. Note that symbol interpretations in a compatibility map
(
<emphasis>sym_interpret</emphasis>,
the vector of
<emphasis>XkbSymInterpretRec</emphasis>
 structures) are also allocated using this same function.
</para>

<indexterm significance="preferred" zone="XkbSetCompatMap"><primary><function>XkbSetCompatMap</function></primary></indexterm>
<funcsynopsis id="XkbSetCompatMap">
  <funcprototype>
    <funcdef>Bool <function>XkbSetCompatMap</function></funcdef>
<!-- (
<emphasis>display, which, xkb, update_actions</emphasis>
) -->

    <paramdef>Display *<parameter>display</parameter></paramdef>
    <paramdef>unsigned int <parameter>which</parameter></paramdef>
    <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
    <paramdef>Bool <parameter>update_actions</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>display</parameter>
    </term>
    <listitem>
      <para>
        connection to server
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>which</parameter>
    </term>
    <listitem>
      <para>
        mask of compat map components to set
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        source for compat map components
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>update_actions</parameter>
    </term>
    <listitem>
      <para>
        <emphasis>True</emphasis> =&gt; apply to server’s keyboard map
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XkbSetCompatMap</function>
 copies compatibility map information from the keyboard description in
<emphasis>xkb</emphasis>
 to the server specified in
<emphasis>display</emphasis>
’s compatibility map for the device specified by the
<emphasis>device_spec</emphasis>
 field of
<emphasis>xkb</emphasis>.
Unless you have specifically modified this field, it is the default keyboard
device.
<emphasis>which</emphasis>
 specifies the compatibility map components to be set, and is an inclusive OR
of the bits shown in Table 17.2.
</para>


<para>
After updating its compatibility map for the specified device, if
<emphasis>update_actions</emphasis>
 is
<emphasis>True</emphasis>,
 the server applies the new compatibility map to its entire keyboard for the
device to generate a new set of key semantics, compatibility state, and a new
core keyboard map. If
<emphasis>update_actions</emphasis>
 is
<emphasis>False</emphasis>,
the new compatibility map is not used to generate any modifications to the
current device semantics, state, or core keyboard map. One reason for not
applying the compatibility map immediately would be if one server was being
configured to match another on a piecemeal basis; the map should not be applied
until everything is updated. To force an update at a later time, use
<function>XkbSetCompatMap</function>
 specifying
<emphasis>which</emphasis>
 as zero and
<emphasis>update_actions</emphasis>
 as
<emphasis>True</emphasis>.
</para>


<para>
<function>XkbSetCompatMap</function>
 returns
<emphasis>True</emphasis>
 if successful and
<emphasis>False</emphasis>
 if unsuccessful. The server may report problems it encounters when processing
the request subsequently via protocol errors.
</para>


<para>
To add a symbol interpretation to the list of symbol interpretations in an
<emphasis>XkbCompatRec</emphasis>,
use
<function>XkbAddSymInterpret</function>.
</para>


<indexterm significance="preferred" zone="XkbAddSymInterpret"><primary><function>XkbAddSymInterpret</function></primary></indexterm>
<funcsynopsis id="XkbAddSymInterpret">
  <funcprototype>
    <funcdef>XkbSymInterpretPtr <function>XkbAddSymInterpret</function></funcdef>
<!-- (
<emphasis>xkb, si, updateMap, changes</emphasis>
) -->

    <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
    <paramdef>XkbSymInterpretPtr <parameter>si</parameter></paramdef>
    <paramdef>Bool <parameter>updateMap</parameter></paramdef>
    <paramdef>XkbChangesPtr <parameter>changes</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        keyboard description to be updated
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>si</parameter>
    </term>
    <listitem>
      <para>
        symbol interpretation to be added
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>updateMap</parameter>
    </term>
    <listitem>
      <para>
        <emphasis>True</emphasis>=&gt;apply compatibility map to keys
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>changes</parameter>
    </term>
    <listitem>
      <para>
        changes are put here
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XkbAddSymInterpret</function>
 adds
<emphasis>si</emphasis>
 to the list of symbol interpretations in
<emphasis>xkb</emphasis>.
If
<emphasis>updateMap</emphasis>
 is
<emphasis>True</emphasis>,
it (re)applies the compatibility map to all of the keys on the keyboard. If
<emphasis>changes</emphasis>
 is non-
<emphasis>NULL</emphasis>,
it reports the parts of the keyboard that were affected (unless
<emphasis>updateMap</emphasis>
 is
<emphasis>True</emphasis>,
not much changes).
<function>XkbAddSymInterpret</function>
 returns a pointer to the actual new symbol interpretation in the list or
<emphasis>NULL</emphasis>
 if it failed.
</para>


</sect1>
<sect1 id='Tracking_Changes_to_the_Compatibility_Map'>
<title>Tracking Changes to the Compatibility Map</title>

<para>
The server automatically generates
<emphasis>MappingNotify</emphasis>
 events when the keyboard mapping changes. If you wish to be notified of
changes to the compatibility map, you should select for
<emphasis>XkbCompatMapNotify</emphasis>
 events. If you select for
<emphasis>XkbMapNotify</emphasis>
 events, you no longer receive the automatically generated
<emphasis>MappingNotify</emphasis>
 events. If you subsequently deselect
<emphasis>XkbMapNotifyEvent</emphasis>
 delivery, you again receive
<emphasis>MappingNotify</emphasis>
 events.
</para>


<para>
To receive
<emphasis>XkbCompatMapNotify</emphasis>
 events under all possible conditions, use
<function>XkbSelectEvents</function>
 (see section 4.3) and pass
<emphasis>XkbCompatMapNotifyMask</emphasis>
 in both
<emphasis>bits_to_change</emphasis>
 and
<emphasis>values_for_bits</emphasis>.
</para>


<para>
To receive
<emphasis>XkbCompatMapNotify</emphasis>
 events only under certain conditions, use
<function>XkbSelectEventDetails</function>
 using
<emphasis>XkbCompatMapNotify</emphasis>
 as the
<emphasis>event_type</emphasis>
 and specifying the desired map changes in
<emphasis>bits_to_change</emphasis>
 and
<emphasis>values_for_bits</emphasis>
 using mask bits from Table 17.2.
</para>


<para>
Note that you are notified of changes you make yourself, as well as changes
made by other clients.
</para>


<para>
The structure for the
<emphasis>XkbCompatMapNotifyEvent</emphasis>
 is:
</para>

<para><programlisting>
typedef struct {
      int            type;          /* Xkb extension base event code */
      unsigned long  serial;        /* X server serial number for event */
      Bool           send_event;    /* <emphasis>True</emphasis> =&gt;
                                       synthetically generated */
      Display *      display;       /* server connection where event generated */
      Time           time;          /* server time when event generated */
      int            xkb_type;      /* <emphasis>XkbCompatMapNotify</emphasis> */
      int            device;        /* Xkb device ID, will not be
                                       <emphasis>XkbUseCoreKbd</emphasis> */
      unsigned int   changed_groups;/* number of group maps changed */
      int            first_si;      /* index to 1st changed symbol
                                       interpretation */
      int            num_si;        /* number of changed symbol
                                       interpretations */
      int            num_total_si;  /* total number of valid symbol
                                       interpretations */
} <emphasis>XkbCompatMapNotifyEvent</emphasis>;
</programlisting></para>

<para>
<emphasis>changed_groups</emphasis>
 is the number of group compatibility maps that have changed. If you are
maintaining a corresponding copy of the compatibility map, or get a fresh copy
from the server using
<function>XkbGetCompatMap</function>,
<emphasis>changed_groups</emphasis>
 references
<emphasis>groups</emphasis>
[0..
<emphasis>changed_groups</emphasis>
-1] in the
<emphasis>XkbCompatMapRec</emphasis>
 structure.
</para>


<para>
<emphasis>first_si</emphasis>
 is the index of the first changed symbol interpretation,
<emphasis>num_si</emphasis>
 is the number of changed symbol interpretations, and
<emphasis>num_total_si</emphasis>
 is the total number of valid symbol interpretations. If you are maintaining a
corresponding copy of the compatibility map, or get a fresh copy from the
server using
<function>XkbGetCompatMap</function>,
<emphasis>first_si</emphasis>,
<emphasis>num_si</emphasis>,
and
<emphasis>num_total_si</emphasis>
 are appropriate for use with the
<emphasis>compat.sym_interpret</emphasis>
 vector in this structure.
</para>


</sect1>
<sect1 id='Allocating_and_Freeing_the_Compatibility_Map'>
<title>Allocating and Freeing the Compatibility Map</title>

<para>
If you are modifying the compatibility map, you need to allocate a new
compatibility map if you do not already have one available. To do so, use
<function>XkbAllocCompatMap</function>.
</para>

<indexterm significance="preferred" zone="XkbAllocCompatMap"><primary><function>XkbAllocCompatMap</function></primary></indexterm>
<funcsynopsis id="XkbAllocCompatMap">
  <funcprototype>
    <funcdef>Status <function>XkbAllocCompatMap</function></funcdef>
<!-- (
<emphasis>xkb, which, num_si</emphasis>
) -->

    <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
    <paramdef>unsigned int <parameter>which</parameter></paramdef>
    <paramdef>unsigned int <parameter>num_si</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        keyboard description in which to allocate compat map
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>which</parameter>
    </term>
    <listitem>
      <para>
        mask of compatibility map components to allocate
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>num_si</parameter>
    </term>
    <listitem>
      <para>
        number of symbol interpretations to allocate
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<emphasis>xkb</emphasis>
 specifies the keyboard description for which compatibility maps are to be
allocated. The compatibility map is the
<emphasis>compat</emphasis>
 field in this structure.
</para>


<para>
<emphasis>which</emphasis>
 specifies the compatibility map components to be allocated (see
<function>XkbGetCompatMap</function>,
in section 17.2).
<emphasis>which</emphasis>
 is an inclusive OR of the bits shown in Table 17.2.
</para>


<para>
<emphasis>num_si</emphasis>
 specifies the total number of entries to allocate in the symbol interpretation
vector (
<emphasis>xkb.compat.sym_interpret</emphasis>
).
</para>


<para>
Note that symbol interpretations in a compatibility map (the
<emphasis>sym_interpret</emphasis>
 vector of
<emphasis>XkbSymInterpretRec</emphasis>
 structures) are also allocated using this same function. To ensure that there
is sufficient space in the symbol interpretation vector for entries to be
added, use
<function>XkbAllocCompatMap</function>
 specifying
<emphasis>which</emphasis>
 as
<emphasis>XkbSymInterpretMask</emphasis>
 and the number of free symbol interpretations needed in
<emphasis>num_si</emphasis>.
</para>


<para>
<function>XkbAllocCompatMap</function>
 returns
<emphasis>Success</emphasis>
 if successful,
<emphasis>BadMatch</emphasis>
 if
<emphasis>xkb</emphasis>
 is
<emphasis>NULL</emphasis>,
or
<emphasis>BadAlloc</emphasis>
 if errors are encountered when attempting to allocate storage.
</para>


<para>
To free an entire compatibility map or selected portions of one, use
<function>XkbFreeCompatMap</function>.
</para>


<indexterm significance="preferred" zone="XkbFreeCompatMap"><primary><function>XkbFreeCompatMap</function></primary></indexterm>
<funcsynopsis id="XkbFreeCompatMap">
  <funcprototype>
    <funcdef>void <function>XkbFreeCompatMap</function></funcdef>
<!-- (
<emphasis>xkb, which, free_map</emphasis>
) -->

    <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
    <paramdef>unsigned int <parameter>which</parameter></paramdef>
    <paramdef>Bool <parameter>free_map</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        Xkb description in which to free compatibility map
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>which</parameter>
    </term>
    <listitem>
      <para>
        mask of compatibility map components to free
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>free_map</parameter>
    </term>
    <listitem>
      <para>
        <emphasis>True</emphasis> =&gt; free <emphasis>XkbCompatMap</emphasis>
         structure itself
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<emphasis>which</emphasis>
 specifies the compatibility map components to be freed (see
<function>XkbGetCompatMap</function>,
in section 17.2).
<emphasis>which</emphasis>
 is an inclusive OR of the bits shown in Table 17.2
</para>


<para>
<emphasis>free_map</emphasis>
 indicates whether the
<emphasis>XkbCompatMap</emphasis>
 structure itself should be freed. If
<emphasis>free_map</emphasis>
 is
<emphasis>True</emphasis>,
<emphasis>which</emphasis>
 is ignored, all non-
<emphasis>NULL</emphasis>
 compatibility map components are freed, and the
<emphasis>compat</emphasis>
 field in the
<emphasis>XkbDescRec</emphasis>
 referenced by
<emphasis>xkb</emphasis>
 is set to
<emphasis>NULL</emphasis>.
</para>

</sect1>
</chapter>