diff options
Diffstat (limited to 'libX11/specs/XKB/ch06.xml')
| -rw-r--r-- | libX11/specs/XKB/ch06.xml | 464 |
1 files changed, 226 insertions, 238 deletions
diff --git a/libX11/specs/XKB/ch06.xml b/libX11/specs/XKB/ch06.xml index 422e6d23b..b3b58da28 100644 --- a/libX11/specs/XKB/ch06.xml +++ b/libX11/specs/XKB/ch06.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='Complete_Keyboard_Description'> <title>Complete Keyboard Description</title> @@ -11,73 +14,64 @@ document that discuss the major Xkb components in detail. <sect1 id='The_XkbDescRec_Structure'> <title>The XkbDescRec Structure</title> +<indexterm significance="preferred" zone="The_XkbDescRec_Structure"> +<primary><structname>XkbDescRec</structname></primary></indexterm> + <para> -The complete description of an Xkb keyboard is given by an <emphasis> -XkbDescRec</emphasis> -. The component structures in the <emphasis> -XkbDescRec</emphasis> - represent the major Xkb components outlined in Figure 1.1. <!-- xref --> +The complete description of an Xkb keyboard is given by an +<structname>XkbDescRec</structname>. +The component structures in the +<structname>XkbDescRec</structname> +represent the major Xkb components outlined in <link linkend="figure1.1">Figure 1.1</link>. </para> <para><programlisting> typedef struct { - struct _XDisplay * display; /* connection to -X server */ - unsigned short flags; /* private to Xkb, do -not modify */ - unsigned short device_spec; /* device of -interest */ - KeyCode min_key_code; /* minimum keycode for -device */ - KeyCode max_key_code; /* maximum keycode for -device */ - XkbControlsPtr ctrls; /* controls */ - XkbServerMapPtr server; /* server keymap */ - XkbClientMapPtr map; /* client keymap */ - XkbIndicatorPtr indicators; /* indicator map -*/ - XkbNamesPtr names; /* names for all -components */ - XkbCompatMapPtr compat; /* compatibility map -*/ - XkbGeometryPtr geom; /* physical geometry of -keyboard */ -} <emphasis> -XkbDescRec</emphasis> -, *XkbDescPtr; + struct _XDisplay * display; /* connection to X server */ + unsigned short flags; /* private to Xkb, do not modify */ + unsigned short device_spec; /* device of interest */ + KeyCode min_key_code; /* minimum keycode for device */ + KeyCode max_key_code; /* maximum keycode for device */ + XkbControlsPtr ctrls; /* controls */ + XkbServerMapPtr server; /* server keymap */ + XkbClientMapPtr map; /* client keymap */ + XkbIndicatorPtr indicators; /* indicator map */ + XkbNamesPtr names; /* names for all components */ + XkbCompatMapPtr compat; /* compatibility map */ + XkbGeometryPtr geom; /* physical geometry of keyboard */ +} <structname>XkbDescRec</structname>, *XkbDescPtr; </programlisting></para> <para> -The <emphasis> -display</emphasis> - field points to an X display structure. The <emphasis> -flags</emphasis> - field is private to the library: modifying <emphasis> -flags</emphasis> - may yield unpredictable results. The <emphasis> -device_spec</emphasis> - field specifies the device identifier of the keyboard input device, or -<emphasis> -XkbUseCoreKeyboard</emphasis> -, which specifies the core keyboard device. The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields specify the least and greatest keycode that can be returned by the +The +<parameter>display</parameter> +field points to an X display structure. The +<structfield>flags</structfield> +field is private to the library: modifying +<structfield>flags</structfield> +may yield unpredictable results. The +<parameter>device_spec</parameter> +field specifies the device identifier of the keyboard input device, or +<symbol>XkbUseCoreKbd</symbol>, +which specifies the core keyboard device. The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields specify the least and greatest keycode that can be returned by the keyboard. </para> <para> The other fields specify structure components of the keyboard description and -are described in detail in other sections of this document. Table 6.1 +are described in detail in other sections of this document. +<link linkend="table6.1">Table 6.1</link> identifies the subsequent sections of this document that discuss the individual -components of the <emphasis> -XkbDescRec</emphasis> -. +components of the +<structname>XkbDescRec</structname>. </para> -<table frame='topbot'> +<table id='table6.1' frame='topbot'> <title>XkbDescRec Component References</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -92,31 +86,31 @@ XkbDescRec</emphasis> <tbody> <row> <entry>ctrls</entry> - <entry>Chapter 10</entry> + <entry><xref linkend="Keyboard_Controls" /></entry> </row> <row> <entry>server</entry> - <entry>Chapter 16</entry> + <entry><xref linkend="Xkb_Server_Keyboard_Mapping" /></entry> </row> <row> <entry>map</entry> - <entry>Chapter 15</entry> + <entry><xref linkend="Xkb_Client_Keyboard_Mapping" /></entry> </row> <row> <entry>indicators</entry> - <entry>Chapter 8</entry> + <entry><xref linkend="Indicators" /></entry> </row> <row> <entry>names</entry> - <entry>Chapter 18</entry> + <entry><xref linkend="Symbolic_Names" /></entry> </row> <row> <entry>compat</entry> - <entry>Chapter 17</entry> + <entry><xref linkend="The_Xkb_Compatibility_Map" /></entry> </row> <row> <entry>geom</entry> - <entry>Chapter 13</entry> + <entry><xref linkend="Keyboard_Geometry" /></entry> </row> </tbody> </tgroup> @@ -126,12 +120,12 @@ XkbDescRec</emphasis> Each structure component has a corresponding mask bit that is used in function calls to indicate that the structure should be manipulated in some manner, such as allocating it or freeing it. These masks and their relationships to the -fields in the <emphasis> -XkbDescRec</emphasis> - are shown in Table 6.2. <!-- xref --> +fields in the +<structname>XkbDescRec</structname> +are shown in <link linkend="table6.2">Table 6.2</link>. </para> -<table frame='topbot'> +<table id='table6.2' frame='topbot'> <title>Mask Bits for XkbDescRec</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -147,12 +141,12 @@ XkbDescRec</emphasis> </thead> <tbody> <row> - <entry>XkbControlsMask</entry> + <entry><symbol>XkbControlsMask</symbol></entry> <entry>ctrls</entry> <entry>(1L<<0)</entry> </row> <row> - <entry>XkbServerMapMask</entry> + <entry><symbol>XkbServerMapMask</symbol></entry> <entry>server</entry> <entry>(1L<<1)</entry> </row> @@ -162,27 +156,27 @@ XkbDescRec</emphasis> <entry>(1L<<2)</entry> </row> <row> - <entry>XkbIndicatorMapMask</entry> + <entry><symbol>XkbIndicatorMapMask</symbol></entry> <entry>indicators</entry> <entry>(1L<<3)</entry> </row> <row> - <entry>XkbNamesMask</entry> + <entry><symbol>XkbNamesMask</symbol></entry> <entry>names</entry> <entry>(1L<<4)</entry> </row> <row> - <entry>XkbCompatMapMask</entry> + <entry><symbol>XkbCompatMapMask</symbol></entry> <entry>compat</entry> <entry>(1L<<5)</entry> </row> <row> - <entry>XkbGeometryMask</entry> + <entry><symbol>XkbGeometryMask</symbol></entry> <entry>geom</entry> <entry>(1L<<6)</entry> </row> <row> - <entry>XkbAllComponentsMask</entry> + <entry><symbol>XkbAllComponentsMask</symbol></entry> <entry>All Fields</entry> <entry>(0x7f)</entry> </row> @@ -196,86 +190,88 @@ XkbDescRec</emphasis> <para> To retrieve one or more components of a keyboard device description, use -<emphasis> -XkbGetKeyboard</emphasis> - (see also <emphasis> -XkbGetKeyboardbyName</emphasis> -). +<function>XkbGetKeyboard</function> +(see also +<link linkend="XkbGetKeyboardByName"><function>XkbGetKeyboardByName</function></link>). + </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> -XkbGetKeyboard</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 indicating components to return */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - device_spec</emphasis> -; /* device for which to fetch description, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetKeyboard"><primary><function>XkbGetKeyboard</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyboard"> + <funcprototype> + <funcdef>XkbDescPtr <function>XkbGetKeyboard</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 indicating components to return + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device for which to fetch description, or +<symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyboard </emphasis> +<function>XkbGetKeyboard</function> allocates and returns a pointer to a keyboard description. It queries the -server for those components specified in the <emphasis> -which</emphasis> - parameter for device <emphasis> -device_spec</emphasis> - and copies the results to the <emphasis> -XkbDescRec</emphasis> - it allocated. The remaining fields in the keyboard description are set to -<emphasis> -NULL</emphasis> -. The valid masks for <emphasis> -which</emphasis> - are those listed in Table 6.2. <!-- xref --> +server for those components specified in the +<parameter>which</parameter> +parameter for device +<parameter>device_spec</parameter> +and copies the results to the +<structname>XkbDescRec</structname> +it allocated. The remaining fields in the keyboard description are set to +<symbol>NULL</symbol>. +The valid masks for +<parameter>which</parameter> +are those listed in <link linkend="table6.2">Table 6.2</link>. </para> <para> -<emphasis> -XkbGetKeyboard</emphasis> - can generate <emphasis> -BadAlloc</emphasis> - protocol errors. +<function>XkbGetKeyboard</function> +can generate +<errorname>BadAlloc</errorname> +protocol errors. </para> <para> -To free the returned keyboard description, use <emphasis> -XkbFreeKeyboard</emphasis> - (see section 6.4). <!-- xref --> +To free the returned keyboard description, use +<function>XkbFreeKeyboard</function> +(see <link linkend="Allocating_and_Freeing_a_Keyboard_Description">section 6.4</link>). </para> @@ -285,7 +281,7 @@ XkbFreeKeyboard</emphasis> <para> The server can generate events whenever its copy of the keyboard description -for a device changes. Refer to section 14.4 for detailed information on <!-- xref --> +for a device changes. Refer to <link linkend="Tracking_Changes_to_Map_Components">section 14.4</link> for detailed information on tracking changes to the keyboard description. </para> @@ -296,122 +292,114 @@ tracking changes to the keyboard description. <para> Applications seldom need to directly allocate a keyboard description; calling -<emphasis> -XkbGetKeyboard</emphasis> - usually suffices. In the event you need to create a keyboard description from -scratch, however, use <emphasis> -XkbAllocKeyboard</emphasis> - rather than directly calling <emphasis> -malloc </emphasis> -or <emphasis> -Xmalloc</emphasis> -. +<function>XkbGetKeyboard</function> +usually suffices. In the event you need to create a keyboard description from +scratch, however, use +<function>XkbAllocKeyboard</function> +rather than directly calling +<function>malloc</function> +or +<function>Xmalloc</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'> -XkbDescRec * <emphasis> -XkbAllocKeyboard</emphasis> -(void) - </entry> - </row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbAllocKeyboard"><primary><function>XkbAllocKeyboard</function></primary></indexterm> +<funcsynopsis id="XkbAllocKeyboard"> + <funcprototype> + <funcdef>XkbDescRec *<function>XkbAllocKeyboard</function></funcdef> + <void /> + + </funcprototype> +</funcsynopsis> <para> -If <emphasis> -XkbAllocKeyboard</emphasis> - fails to allocate the keyboard description, it returns <emphasis> -NULL</emphasis> -. Otherwise, it returns a pointer to an empty keyboard description structure. -The <emphasis> -device_spec</emphasis> - field will have been initialized to <emphasis> -XkbUseCoreKbd</emphasis> -. You may then either fill in the structure components or use Xkb functions to +If +<function>XkbAllocKeyboard</function> +fails to allocate the keyboard description, it returns +<symbol>NULL</symbol>. +Otherwise, it returns a pointer to an empty keyboard description structure. +The +<structfield>device_spec</structfield> +field will have been initialized to +<symbol>XkbUseCoreKbd</symbol>. +You may then either fill in the structure components or use Xkb functions to obtain values for the structure components from a keyboard device. </para> <para> -To destroy either an entire an <emphasis> -XkbDescRec</emphasis> - or just some of its members, use <emphasis> -XkbFreeKeyboard.</emphasis> +To destroy either an entire an +<structname>XkbDescRec</structname> +or just some of its members, use +<function>XkbFreeKeyboard</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> -XkbFreeKeyboard</emphasis> -<emphasis> -(xkb, which, free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description with components to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - which</emphasis> -; /* mask selecting components to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free all components and <emphasis> -xkb</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbFreeKeyboard"><primary><function>XkbFreeKeyboard</function></primary></indexterm> +<funcsynopsis id="XkbFreeKeyboard"> + <funcprototype> + <funcdef>void <function>XkbFreeKeyboard</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 with components to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting components to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ free all components and <parameter>xkb</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbFreeKeyboard</emphasis> - frees the components of <emphasis> -xkb</emphasis> - specified by <emphasis> -which</emphasis> - and sets the corresponding values to <emphasis> -NULL</emphasis> -. If <emphasis> -free_all</emphasis> - is <emphasis> -True</emphasis> -, <emphasis> -XkbFreeKeyboard</emphasis> - frees every non-<emphasis> -NULL</emphasis> - component of <emphasis> -xkb</emphasis> - and then frees the <emphasis> -xkb</emphasis> - structure itself. +<function>XkbFreeKeyboard</function> +frees the components of +<parameter>xkb</parameter> +specified by +<parameter>which</parameter> +and sets the corresponding values to +<symbol>NULL</symbol>. +If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +<function>XkbFreeKeyboard</function> +frees every non- +<symbol>NULL</symbol> +component of +<parameter>xkb</parameter> +and then frees the +<parameter>xkb</parameter> +structure itself. </para> </sect1> |