diff options
Diffstat (limited to 'libX11/specs/XKB/ch14.xml')
| -rw-r--r-- | libX11/specs/XKB/ch14.xml | 2205 |
1 files changed, 1126 insertions, 1079 deletions
diff --git a/libX11/specs/XKB/ch14.xml b/libX11/specs/XKB/ch14.xml index 1fcc76800..cb30105c5 100644 --- a/libX11/specs/XKB/ch14.xml +++ b/libX11/specs/XKB/ch14.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Xkb_Keyboard_Mapping'> <title>Xkb Keyboard Mapping</title> @@ -11,14 +14,21 @@ utilities for manipulating the keyboard mapping. <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 +<firstterm>client map</firstterm> +<indexterm significance="preferred" zone="Xkb_Keyboard_Mapping"> +<primary>client map</primary></indexterm> +<indexterm significance="preferred" zone="Xkb_Keyboard_Mapping"> +<primary>map</primary><secondary>client</secondary></indexterm> +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 +to be used to interpret those symbols. The +<firstterm>server map</firstterm> +<indexterm significance="preferred" zone="Xkb_Keyboard_Mapping"> +<primary>server map</primary></indexterm> +<indexterm significance="preferred" zone="Xkb_Keyboard_Mapping"> +<primary>map</primary><secondary>server</secondary></indexterm> +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> @@ -26,20 +36,25 @@ the virtual modifiers and the per-key virtual modifier mapping. <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." +<xref linkend="Xkb_Client_Keyboard_Mapping" />, and +<xref linkend="Xkb_Server_Keyboard_Mapping" />. </para> <sect1 id='Notation_and_Terminology'> <title>Notation and Terminology</title> +<indexterm significance="preferred" zone="Notation_and_Terminology"> +<primary>level</primary></indexterm> +<indexterm significance="preferred" zone="Notation_and_Terminology"> +<primary>shift level</primary></indexterm> + <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: +logically arranged in groups and levels, where +<structfield>group</structfield> +and +<structfield>level</structfield> +are defined as in the ISO9995 standard: </para> <variablelist> @@ -74,30 +89,32 @@ character the key is capable of generating. <para> -Level is often referred to as "Shift Level". Levels are numbered sequentially -starting at one. +Level is often referred to as <quote>Shift Level</quote>. +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> +in the same way for all keys. For example, the +<symbol>Shift</symbol> +modifier selects shift level 2 on most keys, but for keypad keys the modifier +bound to +<keysym>Num_Lock</keysym> +(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> +<figure id='figure14.1'> + <title>Shift Levels and Groups</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-14.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- @@ -107,15 +124,14 @@ 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> -. +levels. For the first group (Group1), the symbol shift level one is +<keysym>a</keysym>, +and the symbol for shift level two is +<keysym>A</keysym>. +For the second group, the symbol for shift level one is +<keysym>æ</keysym>, +and the symbol for shift level two is +<keysym>Æ</keysym>. </para> <sect2 id='Core_Implementation'> @@ -123,40 +139,38 @@ A</emphasis> <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 +access keys such as the one shown in <link linkend="figure14.1">Figure 14.1</link>. 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. +<symbol>KeyPress</symbol> +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 +In general, the +<symbol>Shift</symbol> +modifier, the +<symbol>Lock</symbol> +modifier, and the modifier bound to the +<keysym>Num_Lock</keysym> +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. +<keysym>Mode_switch</keysym> +key. When the +<keysym>Mode_switch</keysym> +modifier is set, the keyboard is logically in Group 2. When the +<keysym>Mode_switch</keysym> +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. +example, the locking behavior of the +<emphasis>CapsLock</emphasis> +and +<keysym>Num_Lock</keysym> +keys depends on the vendor. </para> @@ -174,14 +188,14 @@ 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). +exception of compatibility mapping, discussed in <xref linkend="The_Xkb_Compatibility_Map" />). </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. +described in detail in <link linkend="Actions_for_Changing_Group_State">section 16.1.4</link>. </para> @@ -193,17 +207,17 @@ type and specifies the modifier combinations necessary to access each level. <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 --> +For example, Xkb allows key types where the +<symbol>Control</symbol> +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 <link linkend="Key_Types">section 15.2</link>. </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 --> +detail in <link linkend="Key_Behavior">section 16.2</link>. </para> @@ -214,148 +228,150 @@ detail in section 16.2. <!-- xref --> <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. +server. The first function, +<function>XkbGetMap</function>, +allocates an +<structname>XkbDescRec</structname> +structure, retrieves mapping components from the server, and stores them in +the +<structname>XkbDescRec</structname> +structure it just allocated. The second function, +<function>XkbGetUpdatedMap</function>, +retrieves mapping components from the server and stores them in an +<structname>XkbDescRec</structname> +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 +To allocate an +<structname>XkbDescRec</structname> +structure and populate it with the server’s keyboard client map and server +map, use +<function>XkbGetMap</function>. +<function>XkbGetMap</function> +is similar to +<function>XkbGetKeyboard</function> +(see <link linkend="Obtaining_a_Keyboard_Description_from_the_Server">section 6.2</link>), but is used only for obtaining the address of an +<structname>XkbDescRec</structname> +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. +populated. +<function>XkbGetKeyboard</function> +always returns fully populated components, while +<function>XkbGetMap</function> +can be instructed to return a partially populated component. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDescPtr <emphasis> -XkbGetMap</emphasis> -(<emphasis> -display, which, device_spec</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - which</emphasis> -; /* mask selecting subcomponents to populate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* device_id, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetMap"><primary><function>XkbGetMap</function></primary></indexterm> +<funcsynopsis id="XkbGetMap"> + <funcprototype> + <funcdef>XkbDescPtr <function>XkbGetMap</function></funcdef> +<!-- ( +<parameter>display, which, device_spec</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting subcomponents to populate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device_id, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -The <emphasis> -which</emphasis> - mask is a bitwise inclusive OR of the masks defined in Table 14.1. Only those +The +<parameter>which</parameter> +mask is a bitwise inclusive OR of the masks defined in +<link linkend="table14.1">Table 14.1</link>. Only those portions of the keyboard server map and the keyboard client maps that are -specified in <emphasis> -which</emphasis> - are allocated and populated. +specified in +<parameter>which</parameter> +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. +<function>XkbGetMap</function> +also sets the +<parameter>device_spec</parameter>, +the +<structfield>min_key_code</structfield>, +and +<structfield>max_key_code</structfield> +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> -. +<function>XkbGetMap</function> +is synchronous; it queries the server for the desired information, waits for a +reply, and then returns. If successful, +<function>XkbGetMap</function> +returns a pointer to the +<structname>XkbDescRec</structname> +structure it allocated. If unsuccessful, +<function>XkbGetMap</function> +returns +<symbol>NULL</symbol>. +When unsuccessful, one of the following protocol errors is also generated: +<errorname>BadAlloc</errorname> +(unable to allocate the +<structname>XkbDescRec</structname> +structure), +<errorname>BadValue</errorname> +(some mask bits in +<parameter>which</parameter> +are undefined), +or +<errorname>BadImplementation</errorname> +(a compatible version of the Xkb extension is not available in the server). To +free the returned data, use +<function>XkbFreeClientMap</function>. </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 +from the server. These functions are specified in the +<quote>convenience functions</quote> +column in <link linkend="table14.1">Table 14.1</link>. +Refer to the sections listed in the table for more information on these functions. </para> -<table frame='topbot'> +<table id='table14.1' frame='topbot'> <title>Xkb Mapping Component Masks and Convenience Functions</title> <?dbfo keep-together="always" ?> <tgroup cols='6' align='left' colsep='0' rowsep='0'> @@ -377,94 +393,94 @@ information on these functions. </thead> <tbody> <row> - <entry><emphasis>XkbKeyTypesMask</emphasis></entry> + <entry><symbol>XkbKeyTypesMask</symbol></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> + <para><structfield>types</structfield></para> + <para><structfield>size_types</structfield></para> + <para><structfield>num_types</structfield></para> </entry> <entry> - <para><emphasis>XkbGetKeyTypes</emphasis></para> - <para><emphasis>XkbResizeKeyType</emphasis></para> - <para><emphasis>XkbCopyKeyType</emphasis></para> - <para><emphasis>XkbCopyKeyTypes</emphasis></para> + <para><function>XkbGetKeyTypes</function></para> + <para><function>XkbResizeKeyType</function></para> + <para><function>XkbCopyKeyType</function></para> + <para><function>XkbCopyKeyTypes</function></para> </entry> - <entry>15.2</entry> + <entry><link linkend="Key_Types">15.2</link></entry> </row> <row> - <entry><emphasis>XkbKeySymsMask</emphasis></entry> + <entry><symbol>XkbKeySymsMask</symbol></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> + <para><structfield>syms</structfield></para> + <para><structfield>size_syms</structfield></para> + <para><structfield>num_syms</structfield></para> + <para><structfield>key_sym_map</structfield></para> </entry> <entry> - <para><emphasis>XkbGetKeySyms</emphasis></para> - <para><emphasis>XkbResizeKeySyms</emphasis></para> - <para><emphasis>XkbChangeTypes­OfKey</emphasis></para> + <para><function>XkbGetKeySyms</function></para> + <para><function>XkbResizeKeySyms</function></para> + <para><function>XkbChangeTypes­OfKey</function></para> </entry> - <entry>15.3</entry> + <entry><link linkend="Key_Symbol_Map">15.3</link></entry> </row> <row> - <entry><emphasis>XkbModifierMapMask</emphasis></entry> + <entry><symbol>XkbModifierMapMask</symbol></entry> <entry>(1<<2)</entry> <entry>client</entry> - <entry><emphasis>modmap</emphasis></entry> - <entry><emphasis>XkbGetKeyModifier­Map</emphasis></entry> - <entry>15.4</entry> + <entry><structfield>modmap</structfield></entry> + <entry><function>XkbGetKeyModifier­Map</function></entry> + <entry><link linkend="The_Per_Key_Modifier_Map">15.4</link></entry> </row> <row> - <entry><emphasis>XkbExplicitComponentsMask</emphasis></entry> + <entry><symbol>XkbExplicitComponentsMask</symbol></entry> <entry>(1<<3)</entry> <entry>server</entry> - <entry><emphasis>explicit</emphasis></entry> - <entry><emphasis>XkbGetKeyExplicit­Components</emphasis></entry> - <entry>16.3</entry> + <entry><structfield>explicit</structfield></entry> + <entry><function>XkbGetKeyExplicit­Components</function></entry> + <entry><link linkend="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">16.3</link></entry> </row> <row> - <entry><emphasis>XkbKeyActionsMask</emphasis></entry> + <entry><symbol>XkbKeyActionsMask</symbol></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> + <para><structfield>key_acts</structfield></para> + <para><structfield>acts</structfield></para> + <para><structfield>num_acts</structfield></para> + <para><structfield>size_acts</structfield></para> </entry> <entry> - <para><emphasis>XkbGetKeyActions</emphasis></para> - <para><emphasis>XkbResizeKey­Actions</emphasis></para> + <para><function>XkbGetKeyActions</function></para> + <para><function>XkbResizeKey­Actions</function></para> </entry> - <entry>16.1</entry> + <entry><link linkend="Key_Actions">16.1</link></entry> </row> <row> - <entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry> + <entry><symbol>XkbKeyBehaviorsMask</symbol></entry> <entry>(1<<5)</entry> <entry>server</entry> - <entry><emphasis>behaviors</emphasis></entry> - <entry><emphasis>XkbGetKey­Behaviors</emphasis></entry> - <entry>16.2</entry> + <entry><structfield>behaviors</structfield></entry> + <entry><function>XkbGetKey­Behaviors</function></entry> + <entry><link linkend="Key_Behavior">16.2</link></entry> </row> <row> - <entry><emphasis>XkbVirtualModsMask</emphasis></entry> + <entry><symbol>XkbVirtualModsMask</symbol></entry> <entry>(1<<6)</entry> <entry>server</entry> - <entry><emphasis>vmods</emphasis></entry> - <entry><emphasis>XkbGetVirtualMods</emphasis></entry> - <entry>16.4</entry> + <entry><structfield>vmods</structfield></entry> + <entry><function>XkbGetVirtualMods</function></entry> + <entry><link linkend="Virtual_Modifier_Mapping">16.4</link></entry> </row> <row> - <entry><emphasis>XkbVirtualModMapMask</emphasis></entry> + <entry><symbol>XkbVirtualModMapMask</symbol></entry> <entry>(1<<7)</entry> <entry>server</entry> - <entry><emphasis>vmodmap</emphasis></entry> - <entry><emphasis>XkbGetVirtualMod­Map</emphasis></entry> - <entry>16.4</entry> + <entry><structfield>vmodmap</structfield></entry> + <entry><function>XkbGetVirtualMod­Map</function></entry> + <entry><link linkend="Virtual_Modifier_Mapping">16.4</link></entry> </row> </tbody> </tgroup> @@ -472,9 +488,8 @@ information on these functions. <para> Xkb defines combinations of these masks for convenience: -</para> -<para><programlisting> +<programlisting> #define XkbResizableInfoMask (XkbKeyTypesMask) #define XkbAllClientInfoMask (XkbKeyTypesMask | XkbKeySymsMask | XkbModifierMapMask) @@ -493,88 +508,95 @@ these components and handle the interdependencies. <para> To update the client or server map information in an existing keyboard -description, use <emphasis>XkbGetUpdatedMap</emphasis>. +description, use <function>XkbGetUpdatedMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetUpdatedMap</emphasis> -(<emphasis> -display, which, xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask selecting subcomponents to populate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description to be updated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetUpdatedMap"><primary><function>XkbGetUpdatedMap</function></primary></indexterm> +<funcsynopsis id="XkbGetUpdatedMap"> + <funcprototype> + <funcdef>Status <function>XkbGetUpdatedMap</function></funcdef> +<!-- ( +<parameter>display, which, xkb</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting subcomponents to populate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to be updated + </para> + </listitem> + </varlistentry> +</variablelist> <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. +The +<parameter>which</parameter> +parameter is a bitwise inclusive OR of the masks in +<link linkend="table14.1">Table 14.1</link>. +If the needed components of the +<parameter>xkb</parameter> +structure are not already allocated, +<function>XkbGetUpdatedMap</function> +allocates them. +<function>XkbGetUpdatedMap</function> +fetches the requested information for the device specified in the +<structname>XkbDescRec</structname> +passed in the +<parameter>xkb</parameter> +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 +<function>XkbGetUpdatedMap</function> +is synchronous; it queries the server for the desired information, waits for a +reply, and then returns. If successful, +<function>XkbGetUpdatedMap</function> +returns +<symbol>Success</symbol>. +If unsuccessful, +<function>XkbGetUpdatedMap</function> +returns one of the following: +<errorname>BadAlloc</errorname> +(unable to allocate a component in the +<structname>XkbDescRec</structname> +structure), +<errorname>BadValue</errorname> +(some mask bits in +<parameter>which</parameter> +are undefined), +<errorname>BadImplementation</errorname> +(a compatible version of the Xkb extension is not available in the server or the reply from the server was invalid). </para> @@ -584,183 +606,190 @@ the reply from the server was invalid). <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>. +copy of the keyboard map and call +<function>XkbSetMap</function> +to send the modified map to the server, or, to reduce network traffic, use +an +<structname>XkbMapChangesRec</structname> +structure and call <function>XkbChangeMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask selecting subcomponents to update */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* description from which new values are taken */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSetMap"><primary><function>XkbSetMap</function></primary></indexterm> +<funcsynopsis id="XkbSetMap"> + <funcprototype> + <funcdef>Bool <function>XkbSetMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting subcomponents to update + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + description from which new values are taken + </para> + </listitem> + </varlistentry> +</variablelist> <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>. +Use +<function>XkbSetMap</function> +to send a complete new set of values for entire components (for example, all +symbols, all actions, and so on) to the server. The +<parameter>which</parameter> +parameter specifies the components to be sent to the server, and is a bitwise +inclusive OR of the masks listed in +<link linkend="table14.1">Table 14.1</link>. The +<parameter>xkb</parameter> +parameter is a pointer to an +<structname>XkbDescRec</structname> +structure and contains the information to be copied to the server. For each +bit set in the +<parameter>which</parameter> +parameter, +<function>XkbSetMap</function> +takes the corresponding structure values from the +<parameter>xkb</parameter> +parameter and sends it to the server specified by +<parameter>dpy</parameter>. </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. +If any components specified by +<parameter>which</parameter> +are not present in the +<parameter>xkb</parameter> +parameter, +<function>XkbSetMap</function> +returns +<symbol>False</symbol>. +Otherwise, it sends the update request to the server and returns +<symbol>True</symbol>. +<function>XkbSetMap</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadLength</errorname>, +and +<errorname>BadValue</errorname> +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 +these components and handle the interdependencies. +<link linkend="table14.1">Table 14.1</link> lists these helper functions and provides a pointer to where they are defined. </para> <sect2 id='The_XkbMapChangesRec_Structure'> <title>The XkbMapChangesRec Structure</title> +<indexterm significance="preferred" zone="The_XkbMapChangesRec_Structure"> +<primary><structname>XkbMapChangesRec</structname></primary></indexterm> <para> -Use the <emphasis> -XkbMapChangesRec</emphasis> - structure to identify and track partial modifications to the mapping +Use the +<structname>XkbMapChangesRec</structname> +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; + 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 <structfield>type</structfield> + modified */ + unsigned char num_types; /* # types modified */ + KeyCode first_key_sym; /* first key whose <structfield>key_sym_map</structfield> + changed */ + unsigned char num_key_syms; /* # <structfield>key_sym_map</structfield> + entries changed */ + KeyCode first_key_act; /* first key whose <structfield>key_acts</structfield> + entry changed */ + unsigned char num_key_acts; /* # <structfield>key_acts</structfield> + entries changed */ + KeyCode first_key_behavior; /* first key whose <structfield>behaviors</structfield> + changed */ + unsigned char num_key_behaviors; /* # <structfield>behaviors</structfield> + entries changed */ + KeyCode first_key_explicit; /* first key whose <structfield>explicit</structfield> + entry changed */ + unsigned char num_key_explicit; /* # <structfield>explicit</structfield> + entries changed */ + KeyCode first_modmap_key; /* first key whose <structfield>modmap</structfield> + entry changed */ + unsigned char num_modmap_keys; /* # <structfield>modmap</structfield> + entries changed */ + KeyCode first_vmodmap_key; /* first key whose <structfield>vmodmap</structfield> + changed */ + unsigned char num_vmodmap_keys; /* # <structfield>vmodmap</structfield> + entries changed */ + unsigned char pad1; /* reserved */ + unsigned short vmods; /* mask indicating which <structfield>vmods</structfield> + changed */ +} <structname>XkbMapChangesRec</structname>, *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 +The +<structfield>changed</structfield> +field identifies the map components that have changed in an +<structname>XkbDescRec</structname> +structure and may contain any of the bits in +<link linkend="table14.1">Table 14.1</link>, which are also shown +in <link linkend="table14.2">Table 14.2</link>. Every 1 bit in +<structfield>changed</structfield> +also identifies which other fields in the +<structname>XkbMapChangesRec</structname> +structure contain valid values, as indicated in +<link linkend="table14.2">Table 14.2</link>. The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +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> -. +<structname>XkbMapChangesRec</structname>. </para> -<table frame='topbot'> +<table id='table14.2' frame='topbot'> <title>XkbMapChangesRec Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -776,85 +805,85 @@ XkbMapChangesRec</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbKeyTypesMask</emphasis></entry> + <entry><symbol>XkbKeyTypesMask</symbol></entry> <entry> -<para>first_type</para>, -<para>num_types</para> +<structfield>first_type</structfield>, +<structfield>num_types</structfield> </entry> <entry> -<para>map->type[first_type] ..</para> -<para>map->type[first_type + num_types - 1]</para> +<structfield>map->type[first_type]</structfield> .. +<structfield>map->type[first_type + num_types - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbKeySymsMask</emphasis></entry> + <entry><symbol>XkbKeySymsMask</symbol></entry> <entry> -<para>first_key_sym</para>, -<para>num_key_syms</para> +<structfield>first_key_sym</structfield>, +<structfield>num_key_syms</structfield> </entry> <entry> -<para>map->key_sym_map[first_key_sym] ..</para> -<para>map->key_sym_map[first_key_sym + num_key_syms - 1]</para> +<structfield>map->key_sym_map[first_key_sym]</structfield> .. +<structfield>map->key_sym_map[first_key_sym + num_key_syms - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbModifierMapMask</emphasis></entry> + <entry><symbol>XkbModifierMapMask</symbol></entry> <entry> -<para>first_modmap_key</para>, -<para>num_modmap_keys</para> +<structfield>first_modmap_key</structfield>, +<structfield>num_modmap_keys</structfield> </entry> <entry> -<para>map->modmap[first_modmap_key] ..</para> -<para>map->modmap[first_modmap_key + num_modmap_keys-1]</para> +<structfield>map->modmap[first_modmap_key]</structfield> .. +<structfield>map->modmap[first_modmap_key + num_modmap_keys-1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbExplicitComponentsMask</emphasis></entry> + <entry><symbol>XkbExplicitComponentsMask</symbol></entry> <entry> -<para>first_key_explicit</para>, -<para>num_key_explicit</para> +<structfield>first_key_explicit</structfield>, +<structfield>num_key_explicit</structfield> </entry> <entry> -<para>server->explicit[first_key_explicit] ..</para> -<para>server->explicit[first_key_explicit + num_key_explicit - 1]</para> +<structfield>server->explicit[first_key_explicit]</structfield> .. +<structfield>server->explicit[first_key_explicit + num_key_explicit - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbKeyActionsMask</emphasis></entry> + <entry><symbol>XkbKeyActionsMask</symbol></entry> <entry> -<para>first_key_act,</para> -<para>num_key_acts</para> +<structfield>first_key_act</structfield>, +<structfield>num_key_acts</structfield> </entry> <entry> -<para>server->key_acts[first_key_act] ..</para> -<para>server->key_acts[first_key_act + num_key_acts - 1]</para> +<structfield>server->key_acts[first_key_act]</structfield> .. +<structfield>server->key_acts[first_key_act + num_key_acts - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry> + <entry><symbol>XkbKeyBehaviorsMask</symbol></entry> <entry> -<para>first_key_behavior,</para> -<para>num_key_behaviors</para> +<structfield>first_key_behavior</structfield>, +<structfield>num_key_behaviors</structfield> </entry> <entry> -<para>server->behaviors[first_key_behavior] ..</para> -<para>server->behaviors[first_key_behavior + num_key_behaviors - 1]</para> +<structfield>server->behaviors[first_key_behavior]</structfield> .. +<structfield>server->behaviors[first_key_behavior + num_key_behaviors - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbVirtuawModsMask</emphasis></entry> - <entry>vmods</entry> - <entry>server->vmods[*]</entry> + <entry><symbol>XkbVirtualModsMask</symbol></entry> + <entry><structfield>vmods</structfield></entry> + <entry><structfield>server->vmods[*]</structfield></entry> </row> <row> - <entry><emphasis>XkbVirtualModMapMask</emphasis></entry> + <entry><symbol>XkbVirtualModMapMask</symbol></entry> <entry> -<para>first_vmodmap_key,</para> -<para>num_vmodmap_keys</para> +<structfield>first_vmodmap_key</structfield>, +<structfield>num_vmodmap_keys</structfield> </entry> <entry> -<para>server->vmodmap[first_vmodmap_key] ..</para> -<para>server->vmodmap[first_vmodmap_key + num_vmodmap_keys - 1]</para> +<structfield>server->vmodmap[first_vmodmap_key]</structfield> .. +<structfield>server->vmodmap[first_vmodmap_key + num_vmodmap_keys - 1]</structfield> </entry> </row> </tbody> @@ -864,94 +893,94 @@ XkbMapChangesRec</emphasis> <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. +keyboard description, then call +<function>XkbChangeMap</function> +with an +<structname>XkbMapChangesRec</structname> +structure indicating which components have changed. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -,<emphasis> - changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* description from which new values are taken */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbMapChangesPtr <emphasis> - changes</emphasis> -; /*identifies component parts to update */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbChangeMap"><primary><function>XkbChangeMap</function></primary></indexterm> +<funcsynopsis id="XkbChangeMap"> + <funcprototype> + <funcdef>Bool <function>XkbChangeMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter>, +<parameter>changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbMapChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + description from which new values are taken + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + identifies component parts to update + </para> + </listitem> + </varlistentry> +</variablelist> <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> -. +<function>XkbChangeMap</function> +copies any components specified by the +<parameter>changes</parameter> +structure from the keyboard description, +<parameter>xkb</parameter>, +to the X server specified by +<parameter>dpy</parameter>. </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> -. +If any components specified by +<parameter>changes</parameter> +are not present in the +<parameter>xkb</parameter> +parameter, +<function>XkbChangeMap</function> +returns +<symbol>False</symbol>. +Otherwise, it sends a request to the server and returns +<symbol>True</symbol>. </para> <para> -<emphasis> -XkbChangeMap</emphasis> - can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadLength</emphasis> -, and <emphasis> -BadValue</emphasis> - protocol errors. +<function>XkbChangeMap</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadLength</errorname>, +and +<errorname>BadValue</errorname> +protocol errors. </para> @@ -960,97 +989,102 @@ BadValue</emphasis> <sect1 id='Tracking_Changes_to_Map_Components'> <title>Tracking Changes to Map Components</title> +<indexterm significance="preferred" zone="Tracking_Changes_to_Map_Components"> +<primary>events</primary><secondary><symbol>XkbMapNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Map_Components"> +<primary><structname>XkbMapNotifyEvent</structname></primary></indexterm> + <para> -The Xkb extension reports <emphasis> -XkbMapNotify</emphasis> - events to clients wanting notification whenever a map component of the Xkb +The Xkb extension reports +<symbol>XkbMapNotify</symbol> +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. +change. The event detail masks are identical to the masks listed in +<link linkend="table14.1">Table 14.1</link>. </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> -. +To receive +<symbol>XkbMapNotify</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass +<symbol>XkbMapNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </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. +To receive +<symbol>XkbMapNotify</symbol> +events only under certain conditions, use +<function>XkbSelectEventDetails</function> +using +<symbol>XkbMapNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying the desired map changes in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +using mask bits from <link linkend="table14.1">Table 14.1</link>. </para> <para> -The structure for <emphasis> -XkbMapNotify</emphasis> - events is: -</para> +The structure for +<symbol>XkbMapNotify</symbol> +events is: -<para><programlisting> +<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>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbMapNotify</symbol> */ + int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed; /* identifies valid fields in rest of event */ + unsigned int resized; /* reserved */ + int first_type; /* index of first key <structfield>type</structfield> 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 <structfield>key_sym_map</structfield> changed */ + KeyCode first_key_act; /* first key whose <structfield>key_acts</structfield> entry changed */ + KeyCode first_key_behavior; /* first key whose <structfield>behaviors</structfield> changed */ + KeyCode first_key_explicit; /* first key whose <structfield>explicit</structfield> entry changed */ + KeyCode first_modmap_key; /* first key whose <structfield>modmap</structfield> entry changed */ + KeyCode first_vmodmap_key; /* # <structfield>modmap</structfield> entries changed */ + int num_key_syms; /* # <structfield>key_sym_map</structfield> entries changed */ + int num_key_acts; /* # <structfield>key_acts</structfield> entries changed */ + int num_key_behaviors; /* # <structfield>behaviors</structfield> entries changed */ + int num_key_explicit; /* # <structfield>explicit</structfield> entries changed */ + int num_modmap_keys; /* # <structfield>modmap</structfield> entries changed */ + int num_vmodmap_keys; /* # <structfield>vmodmap</structfield> entries changed */ + unsigned int vmods; /* mask indicating which <structfield>vmods</structfield> changed */ +} <structname>XkbMapNotifyEvent</structname>; </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. +The +<structfield>changed</structfield> +field specifies the map components that have changed and is the bitwise +inclusive OR of the mask bits defined in +<link linkend="table14.1">Table 14.1</link>. The other fields in this +event are interpreted as the like-named fields in an +<structname>XkbMapChangesRec</structname> +(see <link linkend="The_XkbMapChangesRec_Structure">section 14.3.1</link>). The +<structname>XkbMapNotifyEvent</structname> +structure also has an additional +<structfield>resized</structfield> +field that is reserved for future use. </para> @@ -1059,9 +1093,9 @@ resized</emphasis> <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 +Calling +<function>XkbGetMap</function> +(see <link linkend="Getting_Map_Components_from_the_Server">section 14.2</link>) 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> @@ -1070,28 +1104,26 @@ allocate client and server maps. <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> -. +components directly using +<function>malloc</function> +or +<function>Xmalloc</function>. +Instead, use the Xkb allocators, +<function>XkbAllocClientMap</function>, +and +<function>XkbAllocServerMap</function>. </para> <para> -Similarly, use the Xkb destructors, <emphasis> -XkbFreeClientMap,</emphasis> - and <emphasis> -XkbFreeServerMap</emphasis> - instead of <emphasis> -free</emphasis> - or <emphasis> -Xfree</emphasis> -. +Similarly, use the Xkb destructors, +<function>XkbFreeClientMap</function>, +and +<function>XkbFreeServerMap</function> +instead of +<function>free</function> +or +<function>Xfree</function>. </para> @@ -1100,66 +1132,69 @@ Xfree</emphasis> <para> To allocate and initialize an empty client map description record, use -<emphasis> -XkbAllocClientMap.</emphasis> +<function>XkbAllocClientMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocClientMap</emphasis> -(<emphasis> -xkb, which, type_count</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description in which to allocate client map */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask selecting map components to allocate */ - </entry> - </row> - <row> - <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> +<indexterm significance="preferred" zone="XkbAllocClientMap"><primary><function>XkbAllocClientMap</function></primary></indexterm> +<funcsynopsis id="XkbAllocClientMap"> + <funcprototype> + <funcdef>Status <function>XkbAllocClientMap</function></funcdef> +<!-- ( +<parameter>xkb, which, type_count</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>type_count</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description in which to allocate client map + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting map components to allocate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>type_count</parameter> + </term> + <listitem> + <para> + value of <structfield>num_types</structfield> field in map to be allocated + </para> + </listitem> + </varlistentry> +</variablelist> <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 +<function>XkbAllocClientMap</function> +allocates and initializes an empty client map in the +<structfield>map</structfield> +field of the keyboard description specified by +<parameter>xkb</parameter>. +The +<parameter>which</parameter> +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. +masks shown in <link linkend="table14.3">Table 14.3</link>. </para> -<table frame='topbot'> +<table id='table14.3' frame='topbot'> <title>XkbAllocClientMap Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1173,116 +1208,115 @@ masks shown in Table 14.3. </thead> <tbody> <row> - <entry>XkbKeyTypesMask</entry> + <entry><symbol>XkbKeyTypesMask</symbol></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>. +The +<parameter>type_count</parameter> +field specifies the number of entries to preallocate for the +<structfield>types</structfield> +field of the client map. If the +<parameter>type_count</parameter> +field is less than +<symbol>XkbNumRequiredTypes</symbol> +(see <link linkend="The_Canonical_Key_Types">section 15.2.1</link>), returns +<errorname>BadValue</errorname>. </entry> </row> <row> - <entry>XkbKeySymsMask</entry> + <entry><symbol>XkbKeySymsMask</symbol></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. +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>syms</structfield> +and +<structfield>key_sym_map</structfield> +fields of the client map. The fields are allocated to contain the maximum +number of entries necessary for +<structfield>max_key_code</structfield> +− +<structfield>min_key_code</structfield> ++ 1 keys. </entry> </row> <row> - <entry>XkbModifierMapMask</entry> + <entry><symbol>XkbModifierMapMask</symbol></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. +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>modmap</structfield> +field of the client map. The field is allocated to contain the maximum number +of entries necessary for +<structfield>max_key_code</structfield> +− +<structfield>min_key_code</structfield> ++ 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> +<note><para>The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter must be legal values if the +<symbol>XkbKeySymsMask</symbol> +or +<symbol>XkbModifierMapMask</symbol> +masks are set in the +<parameter>which</parameter> +parameter. If they are not valid, +<function>XkbAllocClientMap</function> +returns +<errorname>BadValue</errorname>. +</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. +If the client map of the keyboard description is not +<symbol>NULL</symbol>, +and any fields are already allocated in the client map, +<function>XkbAllocClientMap</function> +does not overwrite the existing values; it simply ignores that part of the +request. The only exception is the +<structfield>types</structfield> +array. If +<parameter>type_count</parameter> +is greater than the current +<structfield>num_types</structfield> +field of the client map, +<function>XkbAllocClientMap</function> +resizes the +<structfield>types</structfield> +array and resets the +<structfield>num_types</structfield> +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. +If +<function>XkbAllocClientMap</function> +is successful, it returns +<symbol>Success</symbol>. +Otherwise, it can return either +<errorname>BadMatch</errorname>, +<errorname>BadAlloc</errorname>, +or +<errorname>BadValue</errorname> +errors. </para> @@ -1291,91 +1325,96 @@ BadValue</emphasis> <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> +To free memory used by the client map member of an +<structname>XkbDescRec</structname> +structure, use +<function>XkbFreeClientMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeClientMap</emphasis> -(<emphasis> -xkb, which, free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description containing client map to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask identifying components of map to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free all client components and map itself */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbFreeClientMap"><primary><function>XkbFreeClientMap</function></primary></indexterm> +<funcsynopsis id="XkbFreeClientMap"> + <funcprototype> + <funcdef>void <function>XkbFreeClientMap</function></funcdef> +<!-- ( +<parameter>xkb, which, free_all</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description containing client map to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask identifying components of map to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> + ⇒ free all client components and map itself + </para> + </listitem> + </varlistentry> +</variablelist> <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. +<function>XkbFreeClientMap</function> +frees the components of client map specified by +<parameter>which</parameter> +in the +<structname>XkbDescRec</structname> +structure specified by the +<parameter>xkb</parameter> +parameter and sets the corresponding structure component values to +<symbol>NULL</symbol>. +The +<parameter>which</parameter> +parameter specifies a combination of the client map masks shown in +<link linkend="table14.3">Table 14.3</link>. </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> +If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +<parameter>which</parameter> +is ignored; +<function>XkbFreeClientMap</function> +frees every non- +<symbol>NULL</symbol> +structure component in the client map, frees the +<structname>XkbClientMapRec</structname> +structure referenced by the +<structfield>map</structfield> +member of the +<parameter>xkb</parameter> +parameter, and sets the +<structfield>map</structfield> +member to +<symbol>NULL</symbol>. </para> @@ -1385,65 +1424,68 @@ NULL.</emphasis> <para> To allocate and initialize an empty server map description record, use -<emphasis> -XkbAllocServerMap.</emphasis> +<function>XkbAllocServerMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocServerMap</emphasis> -(<emphasis> -xkb, which, count_acts</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description in which to allocate server map */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask selecting map components to allocate */ - </entry> - </row> - <row> - <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> +<indexterm significance="preferred" zone="XkbAllocServerMap"><primary><function>XkbAllocServerMap</function></primary></indexterm> +<funcsynopsis id="XkbAllocServerMap"> + <funcprototype> + <funcdef>Status <function>XkbAllocServerMap</function></funcdef> +<!-- ( +<parameter>xkb, which, count_acts</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>count_acts</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description in which to allocate server map + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting map components to allocate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count_acts</parameter> + </term> + <listitem> + <para> + value of <structfield>num_acts</structfield> field in map to be allocated + </para> + </listitem> + </varlistentry> +</variablelist> <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. +<function>XkbAllocServerMap</function> +allocates and initializes an empty server map in the +<structfield>server</structfield> +field of the keyboard description specified by +<parameter>xkb</parameter>. +The +<parameter>which</parameter> +parameter specifies the particular components of the server map structure to +allocate, as specified in <link linkend="table14.4">Table 14.4</link>. </para> -<table frame='topbot'> +<table id='table14.4' frame='topbot'> <title>XkbAllocServerMap Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1457,62 +1499,62 @@ allocate, as specified in Table 14.4. </thead> <tbody> <row> - <entry>XkbExplicitComponentsMask</entry> + <entry><symbol>XkbExplicitComponentsMask</symbol></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> +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>explicit</structfield> field of the server map. </entry> </row> <row> - <entry>XkbKeyActionsMask</entry> + <entry><symbol>XkbKeyActionsMask</symbol></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. +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>key_acts</structfield> +field of the server map. The +<parameter>count_acts</parameter> +parameter is used to allocate the +<structfield>acts</structfield> +field of the server map. </entry> </row> <row> - <entry>XkbKeyBehaviorsMask</entry> + <entry><symbol>XkbKeyBehaviorsMask</symbol></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> +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>behaviors</structfield> field of the server map. </entry> </row> <row> - <entry>XkbVirtualModMapMask</entry> + <entry><symbol>XkbVirtualModMapMask</symbol></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> +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>vmodmap</structfield> field of the server map. </entry> </row> @@ -1520,50 +1562,49 @@ field of the server map. </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> +<note><para>The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter must be legal values. If they are not valid, +<function>XkbAllocServerMap</function> +returns +<errorname>BadValue</errorname>. +</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> +If the server map of the keyboard description is not +<symbol>NULL</symbol> +and any fields are already allocated in the server map, +<function>XkbAllocServerMap</function> +does not overwrite the existing values. The only exception is with the +<structfield>acts</structfield> +array. If the +<parameter>count_acts</parameter> +parameter is greater than the current +<structfield>num_acts</structfield> +field of the server map, +<function>XkbAllocServerMap</function> +resizes the +<structfield>acts</structfield> +array and resets the +<structfield>num_acts</structfield> 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. +If +<function>XkbAllocServerMap</function> +is successful, it returns +<symbol>Success</symbol>. +Otherwise, it can return either +<errorname>BadMatch</errorname> +or +<errorname>BadAlloc</errorname> +errors. </para> @@ -1572,85 +1613,91 @@ BadAlloc</emphasis> <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> +To free memory used by the server member of an +<structname>XkbDescRec</structname> +structure, use +<function>XkbFreeServerMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeServerMap</emphasis> -(<emphasis> -xkb, which, free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description containing server map to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask identifying components of map to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free all server map components and server itself */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbFreeServerMap"><primary><function>XkbFreeServerMap</function></primary></indexterm> +<funcsynopsis id="XkbFreeServerMap"> + <funcprototype> + <funcdef>void <function>XkbFreeServerMap</function></funcdef> +<!-- ( +<parameter>xkb, which, free_all</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description containing server map to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask identifying components of map to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> + ⇒ free all server map components and server itself + </para> + </listitem> + </varlistentry> +</variablelist> <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> +The +<function>XkbFreeServerMap</function> +function frees the specified components of server map in the +<structname>XkbDescRec</structname> +structure specified by the +<parameter>xkb</parameter> +parameter and sets the corresponding structure component values to +<symbol>NULL</symbol>. +The +<parameter>which</parameter> +parameter specifies a combination of the server map masks and is a bitwise +inclusive OR of the masks listed in +<link linkend="table14.4">Table 14.4</link>. If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +<parameter>which</parameter> +is ignored and +<function>XkbFreeServerMap</function> +frees every non- +<symbol>NULL</symbol> +structure component in the server map, frees the +<structname>XkbServerMapRec</structname> +structure referenced by the +<structfield>server</structfield> +member of the +<parameter>xkb</parameter> +parameter, and sets the +<structfield>server</structfield> +member to +<symbol>NULL</symbol>. </para> </sect2> |