diff options
Diffstat (limited to 'libX11/specs/XKB/ch14.xml')
| -rw-r--r-- | libX11/specs/XKB/ch14.xml | 1637 |
1 files changed, 1637 insertions, 0 deletions
diff --git a/libX11/specs/XKB/ch14.xml b/libX11/specs/XKB/ch14.xml new file mode 100644 index 000000000..cc376dba4 --- /dev/null +++ b/libX11/specs/XKB/ch14.xml @@ -0,0 +1,1637 @@ +<chapter id='xkb_keyboard_mapping'> +<title>Xkb Keyboard Mapping</title> + +<para> +The Xkb keyboard mapping contains all the information the server and clients +need to interpret key events. This chapter provides an overview of the +terminology used to describe an Xkb keyboard mapping and introduces common +utilities for manipulating the keyboard mapping. +</para> + + +<para> +The mapping consists of two components, a server map and a client map. The +<emphasis> +client</emphasis> + map is the collection of information a client needs to interpret key events +from the keyboard. It contains a global list of key types and an array of key +symbol maps, each of which describes the symbols bound to a key and the rules +to be used to interpret those symbols. The <emphasis> +server</emphasis> + map contains the information the server needs to interpret key events. This +includes actions and behaviors for each key, explicit components for a key, and +the virtual modifiers and the per-key virtual modifier mapping. +</para> + + +<para> +For detailed information on particular components of the keyboard map, refer to +Chapter 15, "Xkb Client Keyboard Mapping" and Chapter 16, "Xkb Server Keyboard +Mapping." +</para> + +<sect1 id='notation_and_terminology'> +<title>Notation and Terminology</title> + +<para> +The graphic characters or control functions that may be accessed by one key are +logically arranged in groups and levels, where <emphasis> +group</emphasis> + and <emphasis> +level</emphasis> + are defined as in the ISO9995 standard: +</para> + +<variablelist> + <varlistentry> + <term>Group:</term> + <listitem> + <para> +A logical state of a keyboard providing access to a collection of +graphic characters. Usually these graphic characters logically belong together +and may be arranged on several levels within a group. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Level:</term> + <listitem> + <para> +One of several states (normally 2 or 3) governing which graphic +character is produced when a graphic key is actuated. In certain cases the +level may also affect function keys. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +These definitions, taken from the ISO standard, refer to graphic keys and +characters. In the context of Xkb, Group and Level are not constrained to +graphic keys and characters; they may be used with any key to access any +character the key is capable of generating. +</para> + + +<para> +Level is often referred to as "Shift Level". Levels are numbered sequentially +starting at one. +</para> + +<note><para>Shift level is derived from the modifier state, but not necessarily +in the same way for all keys. For example, the <emphasis> +Shift</emphasis> + modifier selects shift level 2 on most keys, but for keypad keys the modifier +bound to <emphasis> +Num_Lock</emphasis> + (that is, the <emphasis> +NumLock</emphasis> + virtual modifier) also selects shift level 2.</para></note> + +<para> +For example, consider the following key (the gray characters indicate symbols +that are implied or expected but are not actually engraved on the key): +</para> + +<mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-14.svg"/> + </imageobject> +<caption>Shift Levels and Groups</caption> + </mediaobject> + + +<!-- +<H5 CLASS="Figure"> +Shift Levels and Groups</H5> +--> + +<para> +This key has two groups, indicated by the columns, and each group has two shift +levels. For the first group (Group1), the symbol shift level one is <emphasis> +a</emphasis> +, and the symbol for shift level two is <emphasis> +A</emphasis> +. For the second group, the symbol for shift level one is <emphasis> +æ</emphasis> +, and the symbol for shift level two is <emphasis> +Æ</emphasis> +. +</para> + +<sect2 id='core_implementation'> +<title>Core Implementation</title> + +<para> +The standard interpretation rules for the core X keymap only allow clients to +access keys such as the one shown in Figure 14.1. That is, clients using the +standard interpretation rules can only access one of four keysyms for any given +<emphasis> +KeyPress</emphasis> + event — two different symbols in two different groups. +</para> + + +<para> +In general, the <emphasis> +Shift</emphasis> + modifier, the <emphasis> +Lock</emphasis> + modifier, and the modifier bound to the <emphasis> +Num_Lock</emphasis> + key are used to change between shift level 1 and shift level 2. To switch +between groups, the core implementation uses the modifier bound to the +<emphasis> +Mode_switch</emphasis> + key. When the <emphasis> +Mode_switch</emphasis> + modifier is set, the keyboard is logically in Group 2. When the <emphasis> +Mode_switch</emphasis> + modifier is not set, the keyboard is logically in Group 1. +</para> + + +<para> +The core implementation does not clearly specify the behavior of keys. For +example, the locking behavior of the <emphasis> +CapsLock</emphasis> + and <emphasis> +Num_Lock</emphasis> + keys depends on the vendor. +</para> + + +</sect2> +<sect2 id='xkb_implementation'> +<title>Xkb Implementation</title> + +<para> +Xkb extends the core implementation by providing access to up to four keyboard +groups with up to 63 shift levels per key +<footnote><para> +The core implementation restricts the number of symbols per key to 255. +With four groups, this allows for up to 63 symbols (or shift levels) per +group. Most keys will only have a few shift levels. +</para></footnote>. In +addition, Xkb provides precise specifications regarding the behavior of keys. +In Xkb, modifier state and the current group are independent (with the +exception of compatibility mapping, discussed in Chapter 17). +</para> + + +<para> +Xkb handles switching between groups via key actions, independent of any +modifier state information. Key actions are in the server map component and are +described in detail in section 16.1.4. +</para> + + +<para> +Xkb handles shift levels by associating a key type with each group on each key. +Each key type defines the shift levels available for the groups on keys of its +type and specifies the modifier combinations necessary to access each level. +</para> + + +<para> +For example, Xkb allows key types where the <emphasis> +Control</emphasis> + modifier can be used to access the shift level two of a key. Key types are in +the client map component and are described in detail in section 15.2. <!-- xref --> +</para> + + +<para> +Xkb provides precise specification of the behavior of a key using key +behaviors. Key behaviors are in the server map component and are described in +detail in section 16.2. <!-- xref --> +</para> + + +</sect2> +</sect1> +<sect1 id='getting_map_components_from_the_server'> +<title>Getting Map Components from the Server</title> + +<para> +Xkb provides two functions to obtain the keyboard mapping components from the +server. The first function, <emphasis> +XkbGetMap</emphasis> +, allocates an <emphasis> +XkbDescRec</emphasis> + structure, retrieves mapping components from the server, and stores them in +the <emphasis> +XkbDescRec</emphasis> + structure it just allocated. The second function, <emphasis> +XkbGetUpdatedMap</emphasis> +, retrieves mapping components from the server and stores them in an <emphasis> +XkbDescRec</emphasis> + structure that has previously been allocated. +</para> + + +<para> +To allocate an <emphasis> +XkbDescRec</emphasis> + structure and populate it with the server’s keyboard client map and server +map, use <emphasis> +XkbGetMap. XkbGetMap </emphasis> +is similar to <emphasis> +XkbGetKeyboard</emphasis> + (see section 6.2), but is used only for obtaining the address of an <emphasis> +XkbDescRec</emphasis> + structure that is populated with keyboard mapping components. It allows finer +control over which substructures of the keyboard mapping components are to be +populated. <emphasis> +XkbGetKeyboard</emphasis> + always returns fully populated components, while <emphasis> +XkbGetMap</emphasis> + can be instructed to return a partially populated component. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +XkbDescPtr <emphasis> +XkbGetMap</emphasis> +(<emphasis> +display, which, device_spec</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + display</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> + which</emphasis> +; /* mask selecting subcomponents to populate */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> + device_spec</emphasis> +; /* device_id, or <emphasis> +XkbUseCoreKbd</emphasis> + */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +The <emphasis> +which</emphasis> + mask is a bitwise inclusive OR of the masks defined in Table 14.1. Only those +portions of the keyboard server map and the keyboard client maps that are +specified in <emphasis> +which</emphasis> + are allocated and populated. +</para> + + +<para> +In addition to allocating and obtaining the server map and the client map, +<emphasis> +XkbGetMap</emphasis> + also sets the <emphasis> +device_spec</emphasis> +, the <emphasis> +min_key_code</emphasis> +<emphasis> +, </emphasis> +and <emphasis> +max_key_code</emphasis> + fields of the keyboard description. +</para> + + +<para> +<emphasis> +XkbGetMap</emphasis> + is synchronous; it queries the server for the desired information, waits for a +reply, and then returns. If successful<emphasis> +, XkbGetMap</emphasis> + returns a pointer to the <emphasis> +XkbDescRec</emphasis> + structure it allocated. If unsuccessful, <emphasis> +XkbGetMap</emphasis> + returns <emphasis> +NULL</emphasis> +. When unsuccessful, one of the following protocol errors is also generated: +<emphasis> +BadAlloc</emphasis> + (unable to allocate the <emphasis> +XkbDescRec</emphasis> + structure), <emphasis> +BadValue</emphasis> + (some mask bits in <emphasis> +which</emphasis> + are undefined)<emphasis> +,</emphasis> + or <emphasis> +BadImplementation</emphasis> + (a compatible version of the Xkb extension is not available in the server). To +free the returned data, use <emphasis> +XkbFreeClientMap</emphasis> +. +</para> + + +<para> +Xkb also provides convenience functions to get partial component definitions +from the server. These functions are specified in the "convenience functions" +column in Table 14.1. Refer to the sections listed in the table for more +information on these functions. +</para> + +<table frame='none'> +<title>Xkb Mapping Component Masks and Convenience Functions</title> +<tgroup cols='6'> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Mask</entry> + <entry>Value</entry> + <entry>Map</entry> + <entry>Fields</entry> + <entry>Convenience Functions</entry> + <entry>Section</entry> +</row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis>XkbKeyTypesMask</emphasis></entry> + <entry>(1<<0)</entry> + <entry>client</entry> + <entry> + <para><emphasis>types</emphasis></para> + <para><emphasis>size_types</emphasis></para> + <para><emphasis>num_types</emphasis></para> + </entry> + <entry> + <para><emphasis>XkbGetKeyTypes</emphasis></para> + <para><emphasis>XkbResizeKeyType</emphasis></para> + <para><emphasis>XkbCopyKeyType</emphasis></para> + <para><emphasis>XkbCopyKeyTypes</emphasis></para> + </entry> + <entry>15.2</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbKeySymsMask</emphasis></entry> + <entry>(1<<1)</entry> + <entry>client</entry> + <entry> + <para><emphasis>syms</emphasis></para> + <para><emphasis>size_syms</emphasis></para> + <para><emphasis>num_syms</emphasis></para> + <para><emphasis>key_sym_map</emphasis></para> + </entry> + <entry> + <para><emphasis>XkbGetKeySyms</emphasis></para> + <para><emphasis>XkbResizeKeySyms</emphasis></para> + <para><emphasis>XkbChangeTypesOfKey</emphasis></para> + </entry> + <entry>15.3</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbModifierMapMask</emphasis></entry> + <entry>(1<<2)</entry> + <entry>client</entry> + <entry><emphasis>modmap</emphasis></entry> + <entry><emphasis>XkbGetKeyModifierMap</emphasis></entry> + <entry>15.4</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbExplicitComponentsMask</emphasis></entry> + <entry>(1<<3)</entry> + <entry>server</entry> + <entry><emphasis>explicit</emphasis></entry> + <entry><emphasis>XkbGetKeyExplicitComponents</emphasis></entry> + <entry>16.3</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbKeyActionsMask</emphasis></entry> + <entry>(1<<4)</entry> + <entry>server</entry> + <entry> + <para><emphasis>key_acts</emphasis></para> + <para><emphasis>acts</emphasis></para> + <para><emphasis>num_acts</emphasis></para> + <para><emphasis>size_acts</emphasis></para> + </entry> + <entry> + <para><emphasis>XkbGetKeyActions</emphasis></para> + <para><emphasis>XkbResizeKeyActions</emphasis></para> + </entry> + <entry>16.1</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry> + <entry>(1<<5)</entry> + <entry>server</entry> + <entry><emphasis>behaviors</emphasis></entry> + <entry><emphasis>XkbGetKeyBehaviors</emphasis></entry> + <entry>16.2</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbVirtualModsMask</emphasis></entry> + <entry>(1<<6)</entry> + <entry>server</entry> + <entry><emphasis>vmods</emphasis></entry> + <entry><emphasis>XkbGetVirtualMods</emphasis></entry> + <entry>16.4</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbVirtualModMapMask</emphasis></entry> + <entry>(1<<7)</entry> + <entry>server</entry> + <entry><emphasis>vmodmap</emphasis></entry> + <entry><emphasis>XkbGetVirtualModMap</emphasis></entry> + <entry>16.4</entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +Xkb defines combinations of these masks for convenience: +</para> + +<para><programlisting> +#define XkbResizableInfoMask (XkbKeyTypesMask) +#define XkbAllClientInfoMask (XkbKeyTypesMask | XkbKeySymsMask | + XkbModifierMapMask) +#define XkbAllServerInfoMask (XkbExplicitComponentsMask | + XkbKeyActionsMask| XkbKeyBehaviorsMask | + XkbVirtualModsMask | XkbVirtualModMapMask) +#define XkbAllMapComponentsMask (XkbAllClientInfoMask|XkbAllServerInfoMask) +</programlisting></para> + +<para> +Key types, symbol maps, and actions are all interrelated: changes in one +require changes in the others. The convenience functions make it easier to edit +these components and handle the interdependencies. +</para> + + +<para> +To update the client or server map information in an existing keyboard +description, use <emphasis>XkbGetUpdatedMap</emphasis>. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Status <emphasis> +XkbGetUpdatedMap</emphasis> +(<emphasis> +display, which, xkb</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + display</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + which</emphasis> +; /* mask selecting subcomponents to populate */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> +xkb</emphasis> +; /* keyboard description to be updated */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +The <emphasis> +which</emphasis> + parameter is a bitwise inclusive OR of the masks in Table 14.1. If the needed +components of the <emphasis> +xkb</emphasis> + structure are not already allocated, <emphasis> +XkbGetUpdatedMap</emphasis> + allocates them. <emphasis> +XkbGetUpdatedMap</emphasis> + fetches the requested information for the device specified in the <emphasis> +XkbDescRec</emphasis> + passed in the <emphasis> +xkb</emphasis> + parameter. +</para> + + +<para> +<emphasis> +XkbGetUpdatedMap</emphasis> + is synchronous; it queries the server for the desired information, waits for a +reply, and then returns. If successful<emphasis> +, XkbGetUpdatedMap</emphasis> + returns <emphasis> +Success</emphasis> +. If unsuccessful, <emphasis> +XkbGetUpdatedMap</emphasis> + returns one of the following: <emphasis> +BadAlloc</emphasis> + (unable to allocate a component in the <emphasis> +XkbDescRec</emphasis> + structure), <emphasis> +BadValue</emphasis> + (some mask bits in <emphasis> +which</emphasis> + are undefined), <emphasis> +BadImplementation</emphasis> + (a compatible version of the Xkb extension is not available in the server or +the reply from the server was invalid). +</para> + +</sect1> +<sect1 id='changing_map_components_in_the_server'> +<title>Changing Map Components in the Server</title> + +<para> +There are two ways to make changes to map components: either change a local +copy of the keyboard map and call <emphasis> +XkbSetMap</emphasis> + to send the modified map to the server, or, to reduce network traffic, use +an<emphasis> + XkbMapChangesRec</emphasis> + structure and call <emphasis>XkbChangeMap</emphasis>. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbSetMap</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + which</emphasis> +,<emphasis> + xkb</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display *<emphasis> + dpy</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + which</emphasis> +; /* mask selecting subcomponents to update */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> + xkb</emphasis> +; /* description from which new values are taken */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +Use <emphasis> +XkbSetMap</emphasis> + to send a complete new set of values for entire components (for example, all +symbols, all actions, and so on) to the server. The <emphasis> +which</emphasis> + parameter specifies the components to be sent to the server, and is a bitwise +inclusive OR of the masks listed in Table 14.1. The <emphasis> +xkb</emphasis> + parameter is a pointer to an <emphasis> +XkbDescRec</emphasis> + structure and contains the information to be copied to the server. For each +bit set in the <emphasis> +which</emphasis> + parameter, <emphasis> +XkbSetMap</emphasis> + takes the corresponding structure values from the <emphasis> +xkb</emphasis> + parameter and sends it to the server specified by <emphasis> +dpy</emphasis>. +</para> + +<para> +If any components specified by <emphasis> +which</emphasis> + are not present in the <emphasis> +xkb</emphasis> + parameter, <emphasis> +XkbSetMap</emphasis> + returns <emphasis> +False</emphasis> +. Otherwise, it sends the update request to the server and returns <emphasis> +True</emphasis> +. <emphasis> +XkbSetMap</emphasis> + can generate <emphasis> +BadAlloc</emphasis> +, <emphasis> +BadLength</emphasis> +, and <emphasis> +BadValue</emphasis> + protocol errors. +</para> + + +<para> +Key types, symbol maps, and actions are all interrelated; changes in one +require changes in the others. Xkb provides functions to make it easier to edit +these components and handle the interdependencies. Table 14.1 lists these +helper functions and provides a pointer to where they are defined. +</para> + + +<sect2 id='the_xkbmapchangesrec_structure'> +<title>The XkbMapChangesRec Structure</title> + +<para> +Use the <emphasis> +XkbMapChangesRec</emphasis> + structure to identify and track partial modifications to the mapping +components and to reduce the amount of traffic between the server and clients. +</para> + +<para><programlisting> +typedef struct _XkbMapChanges { + unsigned short changed; /* identifies valid components + in structure */ + KeyCode min_key_code; /* lowest numbered keycode for + device */ + KeyCode max_key_code; /* highest numbered keycode for + device */ + unsigned char first_type; /* index of first key <emphasis>type</emphasis> + modified */ + unsigned char num_types; /* # types modified */ + KeyCode first_key_sym; /* first key whose <emphasis>key_sym_map</emphasis> + changed */ + unsigned char num_key_syms; /* # <emphasis>key_sym_map</emphasis> + entries changed */ + KeyCode first_key_act; /* first key whose <emphasis>key_acts</emphasis> + entry changed */ + unsigned char num_key_acts; /* # <emphasis>key_acts</emphasis> + entries changed */ + KeyCode first_key_behavior; /* first key whose <emphasis>behaviors</emphasis> + changed */ + unsigned char num_key_behaviors; /* # <emphasis>behaviors</emphasis> + entries changed */ + KeyCode first_key_explicit; /* first key whose <emphasis>explicit</emphasis> + entry changed */ + unsigned char num_key_explicit; /* # <emphasis> explicit</emphasis> + entries changed */ + KeyCode first_modmap_key; /* first key whose <emphasis>modmap</emphasis> + entry changed */ + unsigned char num_modmap_keys; /* # <emphasis>modmap</emphasis> + entries changed */ + KeyCode first_vmodmap_key; /* first key whose <emphasis>vmodmap</emphasis> + changed */ + unsigned char num_vmodmap_keys; /* # <emphasis> vmodmap</emphasis> + entries changed */ + unsigned char pad1; /* reserved */ + unsigned short vmods; /* mask indicating which <emphasis>vmods</emphasis> + changed */ +} <emphasis>XkbMapChangesRec</emphasis>,*XkbMapChangesPtr; +</programlisting></para> + +<para> +The <emphasis> +changed</emphasis> + field identifies the map components that have changed in an <emphasis> +XkbDescRec</emphasis> + structure and may contain any of the bits in Table 14.1, which are also shown +in Table 14.2. Every 1 bit in <emphasis> +changed</emphasis> + also identifies which other fields in the <emphasis> +XkbMapChangesRec</emphasis> + structure contain valid values, as indicated in Table 14.2. The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields are for reference only; they are ignored on any requests sent to the +server and are always updated by the server whenever it returns the data for an +<emphasis> +XkbMapChangesRec</emphasis> +. +</para> + +<table frame='none'> +<title>XkbMapChangesRec Masks</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Mask</entry> + <entry>Valid XkbMapChangesRec Fields</entry> + <entry>XkbDescRec Field Containing Changed Data</entry> +</row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis>XkbKeyTypesMask</emphasis></entry> + <entry> +<para>first_type</para>, +<para>num_types</para> + </entry> + <entry> +<para>map->type[first_type] ..</para> +<para>map->type[first_type + num_types - 1]</para> + </entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbKeySymsMask</emphasis></entry> + <entry> +<para>first_key_sym</para>, +<para>num_key_syms</para> + </entry> + <entry> +<para>map->key_sym_map[first_key_sym] ..</para> +<para>map->key_sym_map[first_key_sym + num_key_syms - 1]</para> + </entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbModifierMapMask</emphasis></entry> + <entry> +<para>first_modmap_key</para>, +<para>num_modmap_keys</para> + </entry> + <entry> +<para>map->modmap[first_modmap_key] ..</para> +<para>map->modmap[first_modmap_key + num_modmap_keys-1]</para> + </entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbExplicitComponentsMask</emphasis></entry> + <entry> +<para>first_key_explicit</para>, +<para>num_key_explicit</para> + </entry> + <entry> +<para>server->explicit[first_key_explicit] ..</para> +<para>server->explicit[first_key_explicit + num_key_explicit - 1]</para> + </entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbKeyActionsMask</emphasis></entry> + <entry> +<para>first_key_act,</para> +<para>num_key_acts</para> + </entry> + <entry> +<para>server->key_acts[first_key_act] ..</para> +<para>server->key_acts[first_key_act + num_key_acts - 1]</para> + </entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry> + <entry> +<para>first_key_behavior,</para> +<para>num_key_behaviors</para> + </entry> + <entry> +<para>server->behaviors[first_key_behavior] ..</para> +<para>server->behaviors[first_key_behavior + num_key_behaviors - 1]</para> + </entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbVirtuawModsMask</emphasis></entry> + <entry>vmods</entry> + <entry>server->vmods[*]</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbVirtualModMapMask</emphasis></entry> + <entry> +<para>first_vmodmap_key,</para> +<para>num_vmodmap_keys</para> + </entry> + <entry> +<para>server->vmodmap[first_vmodmap_key] ..</para> +<para>server->vmodmap[first_vmodmap_key + num_vmodmap_keys - 1]</para> + </entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +To update only partial components of a keyboard description, modify the +appropriate fields in the server and map components of a local copy of the +keyboard description, then call <emphasis> +XkbChangeMap</emphasis> + with an <emphasis> +XkbMapChangesRec</emphasis> + structure indicating which components have changed. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbChangeMap</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + xkb</emphasis> +,<emphasis> + changes</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display *<emphasis> + dpy</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> + xkb</emphasis> +; /* description from which new values are taken */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbMapChangesPtr <emphasis> + changes</emphasis> +; /*identifies component parts to update */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbChangeMap</emphasis> + copies any components specified by the <emphasis> +changes</emphasis> + structure from the keyboard description, <emphasis> +xkb</emphasis> +, to the X server specified by <emphasis> +dpy</emphasis> +. +</para> + + +<para> +If any components specified by <emphasis> +changes</emphasis> + are not present in the <emphasis> +xkb</emphasis> + parameter, <emphasis> +XkbChangeMap</emphasis> + returns <emphasis> +False</emphasis> +. Otherwise, it sends a request to the server and returns <emphasis> +True</emphasis> +. +</para> + + +<para> +<emphasis> +XkbChangeMap</emphasis> + can generate <emphasis> +BadAlloc</emphasis> +, <emphasis> +BadLength</emphasis> +, and <emphasis> +BadValue</emphasis> + protocol errors. +</para> + + +</sect2> +</sect1> +<sect1 id='tracking_changes_to_map_components'> +<title>Tracking Changes to Map Components</title> + +<para> +The Xkb extension reports <emphasis> +XkbMapNotify</emphasis> + events to clients wanting notification whenever a map component of the Xkb +description for a device changes. There are many different types of Xkb +keyboard map changes. Xkb uses an event detail mask to identify each type of +change. The event detail masks are identical to the masks listed in Table 14.1. +</para> + + +<para> +To receive <emphasis> +XkbMapNotify</emphasis> + events under all possible conditions, use <emphasis> +XkbSelectEvents</emphasis> + (see section 4.3) and pass <emphasis> +XkbMapNotifyMask</emphasis> + in both <emphasis> +bits_to_change</emphasis> + and <emphasis> +values_for_bits</emphasis> +. +</para> + + +<para> +To receive <emphasis> +XkbMapNotify</emphasis> + events only under certain conditions, use <emphasis> +XkbSelectEventDetails</emphasis> + using <emphasis> +XkbMapNotify</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 14.1. +</para> + + +<para> +The structure for <emphasis> +XkbMapNotify</emphasis> + events 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> => synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <emphasis> XkbMapNotify</emphasis> */ + int device; /* Xkb device ID, will not be <emphasis>XkbUseCoreKbd</emphasis> */ + unsigned int changed; /* identifies valid fields in rest of event */ + unsigned int resized; /* reserved */ + int first_type; /* index of first key <emphasis> type</emphasis> modified */ + int num_types /* # types modified */ + KeyCode min_key_code; /* minimum keycode for device */ + KeyCode max_key_code; /* maximum keycode for device */ + KeyCode first_key_sym; /* first key whose <emphasis>key_sym_map</emphasis> changed */ + KeyCode first_key_act; /* first key whose <emphasis> key_acts</emphasis> entry changed */ + KeyCode first_key_behavior; /* first key whose <emphasis> behaviors</emphasis> changed */ + KeyCode first_key_explicit; /* first key whose <emphasis> explicit </emphasis> entry changed */ + KeyCode first_modmap_key; /* first key whose <emphasis> modmap</emphasis> entry changed */ + KeyCode first_vmodmap_key; /* # <emphasis> modmap</emphasis> entries changed */ + int num_key_syms; /* # <emphasis>key_sym_map</emphasis> entries changed */ + int num_key_acts; /* # <emphasis> key_acts</emphasis> entries changed */ + int num_key_behaviors; /* # <emphasis> behaviors</emphasis> entries changed */ + int num_key_explicit; /* # <emphasis> explicit</emphasis> entries changed */ + int num_modmap_keys; /* # <emphasis> modmap</emphasis> entries changed */ + int num_vmodmap_keys; /* # <emphasis> vmodmap</emphasis> entries changed */ + unsigned in t vmods; /* mask indicating which <emphasis> vmods</emphasis> changed */ +} <emphasis>XkbMapNotifyEvent</emphasis>; +</programlisting></para> + +<para> +The <emphasis> +changed</emphasis> + field specifies the map components that have changed and is the bitwise +inclusive OR of the mask bits defined in Table 14.1. The other fields in this +event are interpreted as the like-named fields in an <emphasis> +XkbMapChangesRec</emphasis> + (see section 14.3.1). The <emphasis> +XkbMapNotifyEvent</emphasis> + structure also has an additional <emphasis> +resized</emphasis> + field that is reserved for future use. +</para> + + +</sect1> +<sect1 id='allocating_and_freeing_client_and_server_maps'> +<title>Allocating and Freeing Client and Server Maps</title> + +<para> +Calling <emphasis> +XkbGetMap</emphasis> + (see section 14.2) should be sufficient for most applications to get client +and server maps. As a result, most applications do not need to directly +allocate client and server maps. +</para> + + +<para> +If you change the number of key types or construct map components without +loading the necessary components from the X server, do not allocate any map +components directly using <emphasis> +malloc</emphasis> + or <emphasis> +Xmalloc</emphasis> +. Instead, use the Xkb allocators, <emphasis> +XkbAllocClientMap,</emphasis> + and <emphasis> +XkbAllocServerMap</emphasis> +. +</para> + + +<para> +Similarly, use the Xkb destructors, <emphasis> +XkbFreeClientMap,</emphasis> + and <emphasis> +XkbFreeServerMap</emphasis> + instead of <emphasis> +free</emphasis> + or <emphasis> +Xfree</emphasis> +. +</para> + + +<sect2 id='allocating_an_empty_client_map'> +<title>Allocating an Empty Client Map</title> + +<para> +To allocate and initialize an empty client map description record, use +<emphasis> +XkbAllocClientMap.</emphasis> +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Status <emphasis> +XkbAllocClientMap</emphasis> +(<emphasis> +xkb, which, type_count</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> + xkb</emphasis> +; /* keyboard description in which to allocate client map */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + which</emphasis> +; /* mask selecting map components to allocate */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + type_count</emphasis> +; /* value of <emphasis> +num_types</emphasis> + field in map to be allocated */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbAllocClientMap</emphasis> + allocates and initializes an empty client map in the <emphasis> +map</emphasis> + field of the keyboard description specified by <emphasis> +xkb</emphasis> +. The <emphasis> +which</emphasis> + parameter specifies the particular components of the client map structure to +allocate and is a mask composed by a bitwise inclusive OR of one or more of the +masks shown in Table 14.3. +</para> + +<table frame='none'> +<title>XkbAllocClientMap Masks</title> +<tgroup cols='2'> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Mask</entry> + <entry>Effect</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbKeyTypesMask</entry> + <entry> +The <emphasis> +type_count </emphasis> +field specifies the number of entries to preallocate for the <emphasis> +types</emphasis> + field of the client map. If the <emphasis> +type_count </emphasis> +field is less than <emphasis> +XkbNumRequiredTypes</emphasis> + (see section 15.2.1), returns <emphasis> +BadValue</emphasis>. +</entry> + </row> + <row rowsep='0'> + <entry>XkbKeySymsMask</entry> +<entry> +The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields of the <emphasis> +xkb</emphasis> + parameter are used to allocate the <emphasis> +syms</emphasis> + and <emphasis> +key_sym_map</emphasis> + fields of the client map. The fields are allocated to contain the maximum +number of entries necessary for <emphasis> +max_key_code</emphasis> + - <emphasis> +min_key_code</emphasis> + + 1 keys. +</entry> + </row> + <row rowsep='0'> + <entry>XkbModifierMapMask</entry> +<entry> +The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields of the <emphasis> +xkb</emphasis> + parameter are used to allocate the <emphasis> +modmap</emphasis> + field of the client map. The field is allocated to contain the maximum number +of entries necessary for <emphasis> +max_key_code</emphasis> + - <emphasis> +min_key_code</emphasis> + + 1 keys. +</entry> + </row> +</tbody> +</tgroup> +</table> + +<note><para>The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields of the <emphasis> +xkb</emphasis> + parameter must be legal values if the <emphasis> +XkbKeySymsMask</emphasis> + or <emphasis> +XkbModifierMapMask</emphasis> + masks are set in the <emphasis> +which</emphasis> + parameter. If they are not valid, <emphasis> +XkbAllocClientMap</emphasis> + returns <emphasis> +BadValue</emphasis> +. </para></note> + +<para> +If the client map of the keyboard description is not <emphasis> +NULL</emphasis> +, and any fields are already allocated in the client map, <emphasis> +XkbAllocClientMap</emphasis> + does not overwrite the existing values; it simply ignores that part of the +request. The only exception is the <emphasis> +types</emphasis> + array. If <emphasis> +type_count</emphasis> + is greater than the current <emphasis> +num_types</emphasis> + field of the client map, <emphasis> +XkbAllocClientMap</emphasis> + resizes the <emphasis> +types</emphasis> + array and resets the <emphasis> +num_types</emphasis> + field accordingly. +</para> + + +<para> +If <emphasis> +XkbAllocClientMap</emphasis> + is successful, it returns <emphasis> +Success</emphasis> +. Otherwise, it can return either <emphasis> +BadMatch</emphasis> +, <emphasis> +BadAlloc</emphasis> +, or <emphasis> +BadValue</emphasis> + errors. +</para> + + +</sect2> +<sect2 id='freeing_a_client_map'> +<title>Freeing a Client Map</title> + +<para> +To free memory used by the client map member of an <emphasis> +XkbDescRec</emphasis> + structure, use <emphasis> +XkbFreeClientMap.</emphasis> +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +void <emphasis> +XkbFreeClientMap</emphasis> +(<emphasis> +xkb, which, free_all</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> + xkb</emphasis> +; /* keyboard description containing client map to free */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + which</emphasis> +; /* mask identifying components of map to free */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool <emphasis> + free_all</emphasis> +; /* <emphasis> +True</emphasis> + => free all client components and map itself */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbFreeClientMap</emphasis> + frees the components of client map specified by <emphasis> +which</emphasis> + in the <emphasis> +XkbDescRec</emphasis> + structure specified by the <emphasis> +xkb</emphasis> + parameter and sets the corresponding structure component values to <emphasis> +NULL</emphasis> +. The <emphasis> +which</emphasis> + parameter specifies a combination of the client map masks shown in Table 14.3. +</para> + + +<para> +If <emphasis> +free_all</emphasis> + is <emphasis> +True</emphasis> +, <emphasis> +which</emphasis> + is ignored; <emphasis> +XkbFreeClientMap</emphasis> + frees every non-<emphasis> +NULL</emphasis> + structure component in the client map, frees the <emphasis> +XkbClientMapRec</emphasis> + structure referenced by the <emphasis> +map</emphasis> + member of the <emphasis> +xkb</emphasis> + parameter, and sets the <emphasis> +map</emphasis> + member to <emphasis> +NULL.</emphasis> +</para> + + +</sect2> +<sect2 id='allocating_an_empty_server_map'> +<title>Allocating an Empty Server Map</title> + +<para> +To allocate and initialize an empty server map description record, use +<emphasis> +XkbAllocServerMap.</emphasis> +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Status <emphasis> +XkbAllocServerMap</emphasis> +(<emphasis> +xkb, which, count_acts</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> + xkb</emphasis> +; /* keyboard description in which to allocate server map */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + which</emphasis> +; /* mask selecting map components to allocate */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + count_acts</emphasis> +; /* value of <emphasis> +num_acts</emphasis> + field in map to be allocated */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbAllocServerMap</emphasis> + allocates and initializes an empty server map in the <emphasis> +server</emphasis> + field of the keyboard description specified by <emphasis> +xkb</emphasis> +. The <emphasis> +which</emphasis> + parameter specifies the particular components of the server map structure to +allocate, as specified in Table 14.4. +</para> + +<table frame='none'> +<title>XkbAllocServerMap Masks</title> +<tgroup cols='2'> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Mask</entry> + <entry>Effect</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbExplicitComponentsMask</entry> + <entry> +The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields of the <emphasis> +xkb</emphasis> + parameter are used to allocate the <emphasis> +explicit </emphasis> +field of the server map. + </entry> + </row> + <row rowsep='0'> + <entry>XkbKeyActionsMask</entry> + <entry> +The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields of the <emphasis> +xkb</emphasis> + parameter are used to allocate the <emphasis> +key_acts </emphasis> +field of the server map. The <emphasis> +count_acts</emphasis> + parameter is used to allocate the <emphasis> +acts</emphasis> + field of the server map. + </entry> + </row> + <row rowsep='0'> + <entry>XkbKeyBehaviorsMask</entry> + <entry> +The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields of the <emphasis> +xkb</emphasis> + parameter are used to allocate the <emphasis> +behaviors </emphasis> +field of the server map. + </entry> + </row> + <row rowsep='0'> + <entry>XkbVirtualModMapMask</entry> + <entry> +The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields of the <emphasis> +xkb </emphasis> +parameter are used to allocate the <emphasis> +vmodmap </emphasis> +field of the server map. + </entry> + </row> +</tbody> +</tgroup> +</table> + +<note><para>The <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + fields of the <emphasis> +xkb</emphasis> + parameter must be legal values. If they are not valid, <emphasis> +XkbAllocServerMap</emphasis> + returns <emphasis> +BadValue</emphasis> +. </para></note> + +<para> +If the server map of the keyboard description is not <emphasis> +NULL</emphasis> + and any fields are already allocated in the server map, <emphasis> +XkbAllocServerMap</emphasis> + does not overwrite the existing values. The only exception is with the +<emphasis> +acts </emphasis> +array. If the <emphasis> +count_acts </emphasis> +parameter is greater than the current <emphasis> +num_acts </emphasis> +field of the server map, <emphasis> +XkbAllocServerMap</emphasis> + resizes the <emphasis> +acts </emphasis> +array and resets the <emphasis> +num_acts </emphasis> +field accordingly. +</para> + + +<para> +If <emphasis> +XkbAllocServerMap</emphasis> + is successful, it returns <emphasis> +Success</emphasis> +. Otherwise, it can return either <emphasis> +BadMatch</emphasis> + or <emphasis> +BadAlloc</emphasis> + errors. +</para> + + +</sect2> +<sect2 id='freeing_a_server_map'> +<title>Freeing a Server Map</title> + +<para> +To free memory used by the server member of an <emphasis> +XkbDescRec</emphasis> + structure, use <emphasis> +XkbFreeServerMap.</emphasis> +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +void <emphasis> +XkbFreeServerMap</emphasis> +(<emphasis> +xkb, which, free_all</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> + xkb</emphasis> +; /* keyboard description containing server map to free */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int<emphasis> + which</emphasis> +; /* mask identifying components of map to free */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool <emphasis> + free_all</emphasis> +; /* <emphasis> +True</emphasis> + => free all server map components and server itself */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +The <emphasis> +XkbFreeServerMap</emphasis> + function frees the specified components of server map in the <emphasis> +XkbDescRec</emphasis> + structure specified by the <emphasis> +xkb</emphasis> + parameter and sets the corresponding structure component values to <emphasis> +NULL</emphasis> +. The <emphasis> +which</emphasis> + parameter specifies a combination of the server map masks and is a bitwise +inclusive OR of the masks listed in Table 14.4. If <emphasis> +free_all</emphasis> + is <emphasis> +True</emphasis> +, <emphasis> +which</emphasis> + is ignored and <emphasis> +XkbFreeServerMap</emphasis> + frees every non-<emphasis> +NULL</emphasis> + structure component in the server map, frees the <emphasis> +XkbServerMapRec</emphasis> + structure referenced by the <emphasis> +server</emphasis> + member of the <emphasis> +xkb</emphasis> + parameter, and sets the <emphasis> +server</emphasis> + member to <emphasis> +NULL.</emphasis> +</para> + +</sect2> +</sect1> +</chapter> |