head	1.1;
branch	1.1.1;
access;
symbols
	libX11-1-8-12:1.1.1.3
	netbsd-10-1-RELEASE:1.1.1.3
	libX11-1-8-10:1.1.1.3
	libX11-1-8-9:1.1.1.3
	netbsd-8-3-RELEASE:1.1.1.3
	netbsd-9-4-RELEASE:1.1.1.3
	netbsd-10-0-RELEASE:1.1.1.3
	netbsd-10-0-RC6:1.1.1.3
	netbsd-10-0-RC5:1.1.1.3
	netbsd-10-0-RC4:1.1.1.3
	netbsd-10-0-RC3:1.1.1.3
	netbsd-10-0-RC2:1.1.1.3
	netbsd-10-0-RC1:1.1.1.3
	libX11-1-8-7:1.1.1.3
	libX11-1-8-6:1.1.1.3
	libX11-1-8-4:1.1.1.3
	libX11-1-8-3:1.1.1.3
	netbsd-10:1.1.1.3.0.6
	netbsd-10-base:1.1.1.3
	libX11-1-8-2:1.1.1.3
	netbsd-9-3-RELEASE:1.1.1.3
	libX11-1-8-1:1.1.1.3
	libX11-1-7-2:1.1.1.3
	libX11-1-7-1:1.1.1.3
	netbsd-9-2-RELEASE:1.1.1.3
	libX11-1-7-0:1.1.1.3
	netbsd-9-1-RELEASE:1.1.1.3
	libX11-1-6-12:1.1.1.3
	libX11-1-6-10:1.1.1.3
	netbsd-8-2-RELEASE:1.1.1.3
	libX11-1-6-9:1.1.1.3
	netbsd-9-0-RELEASE:1.1.1.3
	netbsd-9-0-RC2:1.1.1.3
	netbsd-9-0-RC1:1.1.1.3
	netbsd-9:1.1.1.3.0.4
	netbsd-9-base:1.1.1.3
	libX11-1-6-8:1.1.1.3
	netbsd-8-1-RELEASE:1.1.1.3
	netbsd-8-1-RC1:1.1.1.3
	libX11-1-6-7:1.1.1.3
	netbsd-7-2-RELEASE:1.1.1.2
	libX11-1-6-6:1.1.1.3
	netbsd-8-0-RELEASE:1.1.1.3
	netbsd-8-0-RC2:1.1.1.3
	netbsd-8-0-RC1:1.1.1.3
	netbsd-7-1-2-RELEASE:1.1.1.2
	netbsd-7-1-1-RELEASE:1.1.1.2
	netbsd-8:1.1.1.3.0.2
	netbsd-8-base:1.1.1.3
	netbsd-7-1:1.1.1.2.0.8
	netbsd-7-1-RELEASE:1.1.1.2
	libX11-1-6-5:1.1.1.3
	netbsd-7-1-RC2:1.1.1.2
	netbsd-7-1-RC1:1.1.1.2
	netbsd-7-0-2-RELEASE:1.1.1.2
	libX11-1-6-4:1.1.1.3
	netbsd-7-0-1-RELEASE:1.1.1.2
	netbsd-7-0:1.1.1.2.0.6
	netbsd-7-0-RELEASE:1.1.1.2
	netbsd-7-0-RC3:1.1.1.2
	netbsd-7-0-RC2:1.1.1.2
	libX11-1-6-3:1.1.1.3
	netbsd-7-0-RC1:1.1.1.2
	netbsd-6-0-6-RELEASE:1.1.1.1
	netbsd-6-1-5-RELEASE:1.1.1.1
	netbsd-7:1.1.1.2.0.4
	netbsd-7-base:1.1.1.2
	netbsd-6-1-4-RELEASE:1.1.1.1
	netbsd-6-0-5-RELEASE:1.1.1.1
	riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.2
	libX11-1-6-2:1.1.1.2
	riastradh-drm2:1.1.1.2.0.2
	riastradh-drm2-base:1.1.1.2
	netbsd-6-1-3-RELEASE:1.1.1.1
	netbsd-6-0-4-RELEASE:1.1.1.1
	netbsd-6-1-2-RELEASE:1.1.1.1
	netbsd-6-0-3-RELEASE:1.1.1.1
	netbsd-6-1-1-RELEASE:1.1.1.1
	libX11-1-6-0:1.1.1.2
	libX11-1-5-99-902:1.1.1.2
	netbsd-6-1:1.1.1.1.0.6
	netbsd-6-0-2-RELEASE:1.1.1.1
	netbsd-6-1-RELEASE:1.1.1.1
	netbsd-6-1-RC4:1.1.1.1
	netbsd-6-1-RC3:1.1.1.1
	netbsd-6-1-RC2:1.1.1.1
	netbsd-6-1-RC1:1.1.1.1
	netbsd-6-0-1-RELEASE:1.1.1.1
	netbsd-6-0:1.1.1.1.0.4
	netbsd-6-0-RELEASE:1.1.1.1
	netbsd-6-0-RC2:1.1.1.1
	netbsd-6-0-RC1:1.1.1.1
	netbsd-6:1.1.1.1.0.2
	netbsd-6-base:1.1.1.1
	libX11-1-4-4:1.1.1.1
	libX11-1-4-3:1.1.1.1
	libX11-1-4-1:1.1.1.1
	xorg:1.1.1;
locks; strict;
comment	@# @;


1.1
date	2011.02.23.07.55.46;	author mrg;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	2011.02.23.07.55.46;	author mrg;	state Exp;
branches;
next	1.1.1.2;

1.1.1.2
date	2013.05.30.23.04.38;	author mrg;	state Exp;
branches;
next	1.1.1.3;
commitid	IUyYawfUjfmA1IRw;

1.1.1.3
date	2015.07.19.08.08.35;	author mrg;	state Exp;
branches;
next	;
commitid	u9SvqCeNOT4JZRty;


desc
@@


1.1
log
@Initial revision
@
text
@<chapter id='complete_keyboard_description'>
<title>Complete Keyboard Description</title>

<para>
The complete Xkb description for a keyboard device is accessed using a single
structure containing pointers to major Xkb components. This chapter describes
this single structure and provides references to other sections of this
document that discuss the major Xkb components in detail.
</para>

<sect1 id='the_xkbdescrec_structure'>
<title>The XkbDescRec Structure</title>

<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 -->
</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;
</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
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
identifies the subsequent sections of this document that discuss the individual
components of the <emphasis>
XkbDescRec</emphasis>
.
</para>

<table frame='none'>
<title>XkbDescRec Component References</title>
<tgroup cols='2'>
<colspec colsep='0'/>
<colspec colsep='0'/>
<thead>
<row rowsep='0'>
  <entry>XkbDescRec Field</entry>
  <entry>For more info</entry>
</row>
</thead>
<tbody>
<row rowsep='0'>
    <entry>ctrls</entry>
    <entry>Chapter 10</entry>
</row>
<row rowsep='0'>
    <entry>server</entry>
    <entry>Chapter 16</entry>
</row>
<row rowsep='0'>
    <entry>map</entry>
    <entry>Chapter 15</entry>
</row>
<row rowsep='0'>
    <entry>indicators</entry>
    <entry>Chapter 8</entry>
</row>
<row rowsep='0'>
    <entry>names</entry>
    <entry>Chapter 18</entry>
</row>
<row rowsep='0'>
    <entry>compat</entry>
    <entry>Chapter 17</entry>
</row>
<row rowsep='0'>
    <entry>geom</entry>
    <entry>Chapter 13</entry>
  </row>
</tbody>
</tgroup>
</table>

<para>
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 -->
</para>

<table frame='none'>
<title>Mask Bits for XkbDescRec</title>
<tgroup cols='3'>
<colspec colsep='0'/>
<colspec colsep='0'/>
<colspec colsep='0'/>
<thead>
<row rowsep='0'>
  <entry>Mask Bit</entry>
  <entry>XkbDescRec Field</entry>
  <entry>Value</entry>
</row>
</thead>
<tbody>
<row rowsep='0'>
    <entry>XkbControlsMask</entry>
    <entry>ctrls</entry>
    <entry>(1L&lt;&lt;0)</entry>
</row>
<row rowsep='0'>
    <entry>XkbServerMapMask</entry>
    <entry>server</entry>
    <entry>(1L&lt;&lt;1)</entry>
</row>
<row rowsep='0'>
    <entry>XkbIClientMapMask</entry>
    <entry>map</entry>
    <entry>(1L&lt;&lt;2)</entry>
</row>
<row rowsep='0'>
    <entry>XkbIndicatorMapMask</entry>
    <entry>indicators</entry>
    <entry>(1L&lt;&lt;3)</entry>
</row>
<row rowsep='0'>
    <entry>XkbNamesMask</entry>
    <entry>names</entry>
    <entry>(1L&lt;&lt;4)</entry>
</row>
<row rowsep='0'>
    <entry>XkbCompatMapMask</entry>
    <entry>compat</entry>
    <entry>(1L&lt;&lt;5)</entry>
</row>
<row rowsep='0'>
    <entry>XkbGeometryMask</entry>
    <entry>geom</entry>
    <entry>(1L&lt;&lt;6)</entry>
</row>
<row rowsep='0'>
    <entry>XkbAllComponentsMask</entry>
    <entry>All Fields</entry>
    <entry>(0x7f)</entry>
  </row>
</tbody>
</tgroup>
</table>

</sect1>
<sect1 id='obtaining_a_keyboard_description_from_the_server'>
<title>Obtaining a Keyboard Description from the Server</title>

<para>
To retrieve one or more components of a keyboard device description, use
<emphasis>
XkbGetKeyboard</emphasis>
 (see also <emphasis>
XkbGetKeyboardbyName</emphasis>
).
</para>

<informaltable frame='none'>
<tgroup cols='1'>
<colspec colsep='0'/>
<tbody>
  <row rowsep='0'>
    <entry role='functiondecl'>
XkbDescPtr <emphasis>
XkbGetKeyboard</emphasis>
(<emphasis>
display, which, device_spec</emphasis>
)
    </entry>
  </row>
  <row rowsep='0'>
    <entry role='functionargdecl'>
Display * <emphasis>
      display</emphasis>
;            /* connection to X server */
    </entry>
  </row>
  <row rowsep='0'>
    <entry role='functionargdecl'>
unsigned int      <emphasis>
which</emphasis>
;            /* mask indicating components to return */
    </entry>
  </row>
  <row rowsep='0'>
    <entry role='functionargdecl'>
unsigned int<emphasis>
      device_spec</emphasis>
;            /* device for which to fetch description, or <emphasis>
XkbUseCoreKbd</emphasis>
 */
    </entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
<emphasis>
XkbGetKeyboard </emphasis>
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 -->
</para>


<para>
<emphasis>
XkbGetKeyboard</emphasis>
 can generate <emphasis>
BadAlloc</emphasis>
 protocol errors.
</para>


<para>
To free the returned keyboard description, use <emphasis>
XkbFreeKeyboard</emphasis>
 (see section 6.4). <!-- xref -->
</para>


</sect1>
<sect1 id='tracking_changes_to_the_keyboard_description_in_the_server'>
<title>Tracking Changes to the Keyboard Description in the Server</title>

<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 -->
tracking changes to the keyboard description.
</para>


</sect1>
<sect1 id='allocating_and_freeing_a_keyboard_description'>
<title>Allocating and Freeing a Keyboard Description</title>

<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>
.
</para>

<informaltable frame='none'>
<tgroup cols='1'>
<colspec colsep='0'/>
<tbody>
  <row rowsep='0'>
    <entry role='functiondecl'>
XkbDescRec * <emphasis>
XkbAllocKeyboard</emphasis>
(void)
    </entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<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
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>
</para>


<informaltable frame='none'>
<tgroup cols='1'>
<colspec colsep='0'/>
<tbody>
  <row rowsep='0'>
    <entry role='functiondecl'>
void <emphasis>
XkbFreeKeyboard</emphasis>
<emphasis>
(xkb, which, free_all</emphasis>
)
    </entry>
  </row>
  <row rowsep='0'>
    <entry role='functionargdecl'>
XkbDescPtr <emphasis>
            xkb</emphasis>
;            /* keyboard description with components to free */
    </entry>
  </row>
  <row rowsep='0'>
    <entry role='functionargdecl'>
unsigned int      <emphasis>
      which</emphasis>
;            /* mask selecting components to free */
    </entry>
  </row>
  <row rowsep='0'>
    <entry role='functionargdecl'>
Bool <emphasis>
            free_all</emphasis>
;            /* <emphasis>
True</emphasis>
 =&gt; free all components and <emphasis>
xkb</emphasis>
 */
    </entry>
</row>
</tbody>
</tgroup>
</informaltable>

<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.
</para>

</sect1>
</chapter>
@


1.1.1.1
log
@initial import of libX11-1.4.1:
- remove support for building without XCB
- many man page updates
- many random bug fixes
- several new nls aliases (need to enable these yet.)
@
text
@@


1.1.1.2
log
@initial import of libX11-1.5.99.902
@
text
@d1 1
a1 1
<chapter id='Complete_Keyboard_Description'>
d11 1
a11 1
<sect1 id='The_XkbDescRec_Structure'>
d80 1
a80 1
<table frame='topbot'>
d82 3
a84 4
<?dbfo keep-together="always" ?>
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<colspec colname='c2' colwidth='2.0*'/>
d86 1
a86 1
<row rowsep='1'>
d92 1
a92 1
<row>
d96 1
a96 1
<row>
d100 1
a100 1
<row>
d104 1
a104 1
<row>
d108 1
a108 1
<row>
d112 1
a112 1
<row>
d116 1
a116 1
<row>
d133 1
a133 1
<table frame='topbot'>
d135 4
a138 5
<?dbfo keep-together="always" ?>
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<colspec colname='c2' colwidth='1.0*'/>
<colspec colname='c3' colwidth='1.0*'/>
d140 1
a140 1
<row rowsep='1'>
d147 1
a147 1
<row>
d152 1
a152 1
<row>
d157 1
a157 1
<row>
d162 1
a162 1
<row>
d167 1
a167 1
<row>
d172 1
a172 1
<row>
d177 1
a177 1
<row>
d182 1
a182 1
<row>
d192 1
a192 1
<sect1 id='Obtaining_a_Keyboard_Description_from_the_Server'>
d205 2
a206 3
<?dbfo keep-together="always" ?>
<tgroup cols='1' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
d208 1
a208 1
  <row>
d217 1
a217 1
  <row>
d224 1
a224 1
  <row>
d231 1
a231 1
  <row>
d280 1
a280 1
<sect1 id='Tracking_Changes_to_the_Keyboard_Description_in_the_Server'>
d291 1
a291 1
<sect1 id='Allocating_and_Freeing_a_Keyboard_Description'>
d309 2
a310 3
<?dbfo keep-together="always" ?>
<tgroup cols='1' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
d312 1
a312 1
  <row>
d347 2
a348 3
<?dbfo keep-together="always" ?>
<tgroup cols='1' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
d350 1
a350 1
  <row>
d359 1
a359 1
  <row>
d366 1
a366 1
  <row>
d373 1
a373 1
  <row>
@


1.1.1.3
log
@initial import of libX11-1.6.3
@
text
@a0 3
<?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">
a13 3
<indexterm significance="preferred" zone="The_XkbDescRec_Structure">
<primary><structname>XkbDescRec</structname></primary></indexterm>

d15 5
a19 5
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>.
d24 24
a47 13
    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;
d51 16
a66 15
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
d73 1
a73 2
are described in detail in other sections of this document.
<link linkend="table6.1">Table 6.1</link>
d75 3
a77 2
components of the
<structname>XkbDescRec</structname>.
d80 1
a80 1
<table id='table6.1' frame='topbot'>
d95 1
a95 1
    <entry><xref linkend="Keyboard_Controls" /></entry>
d99 1
a99 1
    <entry><xref linkend="Xkb_Server_Keyboard_Mapping" /></entry>
d103 1
a103 1
    <entry><xref linkend="Xkb_Client_Keyboard_Mapping" /></entry>
d107 1
a107 1
    <entry><xref linkend="Indicators" /></entry>
d111 1
a111 1
    <entry><xref linkend="Symbolic_Names" /></entry>
d115 1
a115 1
    <entry><xref linkend="The_Xkb_Compatibility_Map" /></entry>
d119 1
a119 1
    <entry><xref linkend="Keyboard_Geometry" /></entry>
d129 3
a131 3
fields in the
<structname>XkbDescRec</structname>
are shown in <link linkend="table6.2">Table 6.2</link>.
d134 1
a134 1
<table id='table6.2' frame='topbot'>
d150 1
a150 1
    <entry><symbol>XkbControlsMask</symbol></entry>
d155 1
a155 1
    <entry><symbol>XkbServerMapMask</symbol></entry>
d165 1
a165 1
    <entry><symbol>XkbIndicatorMapMask</symbol></entry>
d170 1
a170 1
    <entry><symbol>XkbNamesMask</symbol></entry>
d175 1
a175 1
    <entry><symbol>XkbCompatMapMask</symbol></entry>
d180 1
a180 1
    <entry><symbol>XkbGeometryMask</symbol></entry>
d185 1
a185 1
    <entry><symbol>XkbAllComponentsMask</symbol></entry>
d199 5
a203 4
<function>XkbGetKeyboard</function>
(see also
<link linkend="XkbGetKeyboardByName"><function>XkbGetKeyboardByName</function></link>).

d206 40
a245 46
<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>
d248 2
a249 1
<function>XkbGetKeyboard</function>
d251 12
a262 11
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>.
d267 5
a271 4
<function>XkbGetKeyboard</function>
can generate
<errorname>BadAlloc</errorname>
protocol errors.
d276 3
a278 3
To free the returned keyboard description, use
<function>XkbFreeKeyboard</function>
(see <link linkend="Allocating_and_Freeing_a_Keyboard_Description">section 6.4</link>).
d288 1
a288 1
for a device changes. Refer to <link linkend="Tracking_Changes_to_Map_Components">section 14.4</link> for detailed information on
d299 39
a337 30
<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>

<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
<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
d343 72
a414 73
To destroy either an entire an
<structname>XkbDescRec</structname>
or just some of its members, use
<function>XkbFreeKeyboard</function>.
</para>


<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> &rArr; free all components and <parameter>xkb</parameter>
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<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.
@