xkeyboard-config libX11 pixman mesa git update 25 May 2011

16 files changed, 57818 insertions, 57818 deletions

diff --git a/libX11/specs/libX11/AppC.xml b/libX11/specs/libX11/AppC.xml
index 16f7dfddb..fb08f8592 100644
--- a/libX11/specs/libX11/AppC.xml
+++ b/libX11/specs/libX11/AppC.xml
@@ -1,3342 +1,3342 @@
-<?xml version="1.0" encoding="UTF-8" ?>

-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"

-	  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

-<appendix id="extensions">

-<title>Extensions</title>

-<para>

-<!-- .XE -->

-Because X can evolve by extensions to the core protocol, 

-it is important that extensions not be perceived as second-class citizens.

-At some point, 

-your favorite extensions may be adopted as additional parts of the 

-X Standard.

-</para>

-<para>

-<!-- .LP -->

-Therefore, there should be little to distinguish the use of an extension from 

-that of the core protocol.

-To avoid having to initialize extensions explicitly in application programs, 

-it is also important that extensions perform lazy evaluations,

-automatically initializing themselves when called for the first time.  

-</para>

-<para>

-<!-- .LP -->

-This appendix describes techniques for writing extensions to Xlib that will

-run at essentially the same performance as the core protocol requests.

-</para>

-<!-- .NT -->

-<note><para>

-It is expected that a given extension to X consists of multiple

-requests.

-Defining 10 new features as 10 separate extensions is a bad practice.

-Rather, they should be packaged into a single extension

-and should use minor opcodes to distinguish the requests.

-</para></note>

-<!-- .NE -->

-<para>

-<!-- .LP -->

-The symbols and macros used for writing stubs to Xlib are listed in

-&lt;X11/Xlibint.h&gt; .

-<!-- .SH -->

-Basic Protocol Support Routines

-</para>

-<para>

-The basic protocol requests for extensions are 

-<function>XQueryExtension</function>

-and

-<function>XListExtensions</function>.

-</para>

-<indexterm significance="preferred"><primary>XQueryExtension</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XQueryExtension</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *name</parameter></paramdef>

-  <paramdef>int<parameter> *major_opcode_return</parameter></paramdef>

-  <paramdef>int<parameter> *first_event_return</parameter></paramdef>

-  <paramdef>int<parameter> *first_error_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>display</term>

-    <listitem>

-      <para>Specifies the connection to the X server.</para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>name</term>

-    <listitem>

-      <para>Specifies the extension name.</para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>major_opcode_return</term>

-    <listitem>

-      <para>Returns the major opcode.</para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>first_event_return</term>

-    <listitem>

-      <para>Returns the first event code, if any.</para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>first_error_return</term>

-    <listitem>

-      <para>Returns the first error code, if any.</para>

-    </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryExtension</function>

-function determines if the named extension is present.  

-If the extension is not present,

-<function>XQueryExtension</function>

-returns

-<symbol>False</symbol>;

-otherwise, it returns

-<symbol>True</symbol>.

-If the extension is present,

-<function>XQueryExtension</function>

-returns the major opcode for the extension to major_opcode_return;

-otherwise,

-it returns zero.

-Any minor opcode and the request formats are specific to the

-extension.  

-If the extension involves additional event types, 

-<function>XQueryExtension</function>

-returns the base event type code to first_event_return;

-otherwise, 

-it returns zero.  

-The format of the events is specific to the extension.  

-If the extension involves additional error codes, 

-<function>XQueryExtension</function>

-returns the base error code to first_error_return;

-otherwise, 

-it returns zero.  

-The format of additional data in the errors is specific to the extension.

-</para>

-<para>

-<!-- .LP -->

-If the extension name is not in the Host Portable Character Encoding

-the result is implementation-dependent.

-Uppercase and lowercase matter;

-the strings ``thing'', ``Thing'', and ``thinG'' 

-are all considered different names.

-<indexterm significance="preferred"><primary>XListExtensions</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char **<function>XListExtensions</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> *nextensions_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nextensions_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of extensions listed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XListExtensions</function>

-function returns a list of all extensions supported by the server.

-If the data returned by the server is in the Latin Portable Character Encoding,

-then the returned strings are in the Host Portable Character Encoding.

-Otherwise, the result is implementation-dependent.

-<indexterm significance="preferred"><primary>XFreeExtensionList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeExtensionList</function></funcdef>

-  <paramdef>char<parameter> **list</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the list of extension names.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeExtensionList</function>

-function frees the memory allocated by 

-<function>XListExtensions</function>.

-<!-- .SH -->

-Hooking into Xlib 

-</para>

-<para>

-<!-- .LP -->

-These functions allow you to hook into the library.  

-They are not normally used by application programmers but are used 

-by people who need to extend the core X protocol and

-the X library interface.

-The functions, which generate protocol requests for X, are typically

-called stubs.

-</para>

-<para>

-<!-- .LP -->

-In extensions, stubs first should check to see if they have initialized 

-themselves on a connection.

-If they have not, they then should call 

-<function>XInitExtension</function>

-to attempt to initialize themselves on the connection.

-</para>

-<para>

-<!-- .LP -->

-If the extension needs to be informed of GC/font allocation or

-deallocation or if the extension defines new event types, 

-the functions described here allow the extension to be 

-called when these events occur.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XExtCodes</structname>

-structure returns the information from 

-<function>XInitExtension</function>

-and is defined in

-&lt;X11/Xlib.h&gt; :

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XExtCodes</primary></indexterm>

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<synopsis>

-typedef struct _XExtCodes {	/* public to extension, cannot be changed */

-	int extension;		/* extension number */

-	int major_opcode;	/* major op-code assigned by server */

-	int first_event;	/* first event number for the extension */

-	int first_error;	/* first error number for the extension */

-} XExtCodes;

-</synopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>XInitExtension</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XExtCodes *<function>XInitExtension</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *name</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XInitExtension</function>

-function determines if the named extension exists. 

-Then, it allocates storage for maintaining the 

-information about the extension on the connection, 

-chains this onto the extension list for the connection,

-and returns the information the stub implementor will need to access

-the extension.

-If the extension does not exist,

-<function>XInitExtension</function>

-returns NULL.

-</para>

-<para>

-<!-- .LP -->

-If the extension name is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-Uppercase and lowercase matter;

-the strings ``thing'', ``Thing'', and ``thinG'' 

-are all considered different names.

-</para>

-<para>

-<!-- .LP -->

-The extension number in the 

-<structname>XExtCodes</structname>

-structure is

-needed in the other calls that follow.  

-This extension number is unique only to a single connection.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XAddExtension</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XExtCodes *<function>XAddExtension</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-For local Xlib extensions, the

-<function>XAddExtension</function>

-function allocates the

-<structname>XExtCodes</structname>

-structure, bumps the extension number count,

-and chains the extension onto the extension list.

-(This permits extensions to Xlib without requiring server extensions.)

-<!-- .SH -->

-Hooks into the Library

-</para>

-<para>

-<!-- .LP -->

-These functions allow you to define procedures that are to be

-called when various circumstances occur.

-The procedures include the creation of a new GC for a connection,

-the copying of a GC, the freeing of a GC, the creating and freeing of fonts,

-the conversion of events defined by extensions to and from wire

-format, and the handling of errors.

-</para>

-<para>

-<!-- .LP -->

-All of these functions return the previous procedure defined for this

-extension.

-<indexterm significance="preferred"><primary>XESetCloseDisplay</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XESetCloseDisplay</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when the display is closed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetCloseDisplay</function>

-function defines a procedure to be called whenever

-<function>XCloseDisplay</function>

-is called.  

-It returns any previously defined procedure, usually NULL.

-</para>

-<para>

-<!-- .LP -->

-When 

-<function>XCloseDisplay</function>

-is called, 

-your procedure is called 

-with these arguments:

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-</para>

-<para>

-<indexterm significance="preferred"><primary>XESetCreateGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetCreateGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when a GC is closed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetCreateGC</function>

-function defines a procedure to be called whenever

-a new GC is created.  

-It returns any previously defined procedure, usually NULL.

-</para>

-<para>

-<!-- .LP -->

-When a GC is created, 

-your procedure is called with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>GC <parameter>gc</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-</para>

-<indexterm significance="preferred"><primary>XESetCopyGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetCopyGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when GC components are copied.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetCopyGC</function>

-function defines a procedure to be called whenever

-a GC is copied.  

-It returns any previously defined procedure, usually NULL.

-</para>

-<para>

-<!-- .LP -->

-When a GC is copied, 

-your procedure is called with these arguments:

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>GC <parameter>gc</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-</para>

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetFreeGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when a GC is freed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-The

-<function>XESetFreeGC</function>

-function defines a procedure to be called whenever

-a GC is freed.  

-It returns any previously defined procedure, usually NULL.

-</para>

-<para>

-<!-- .LP -->

-When a GC is freed, 

-your procedure is called with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>GC <parameter>gc</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>XESetCreateFont</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetCreateFont</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when a font is created.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetCreateFont</function>

-function defines a procedure to be called whenever

-<function>XLoadQueryFont</function>

-and

-<function>XQueryFont</function>

-are called.  

-It returns any previously defined procedure, usually NULL.

-</para>

-<para>

-<!-- .LP -->

-When 

-<function>XLoadQueryFont</function>

-or

-<function>XQueryFont</function>

-is called, 

-your procedure is called with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>XFontStruct *<parameter>fs</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>XESetFreeFont</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetFreeFont</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when a font is freed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetFreeFont</function>

-function defines a procedure to be called whenever

-<function>XFreeFont</function>

-is called.  

-It returns any previously defined procedure, usually NULL.

-</para>

-<para>

-<!-- .LP -->

-When 

-<function>XFreeFont</function>

-is called, your procedure is called with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>XFontStruct *<parameter>fs</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XESetWireToEvent</function>

-and

-<function>XESetEventToWire</function>

-functions allow you to define new events to the library.

-An 

-<structname>XEvent</structname>

-structure always has a type code (type

-<type>int</type>)

-as the first component.

-This uniquely identifies what kind of event it is.

-The second component is always the serial number (type

-<type>unsigned</type>

-<type>long</type>)

-of the last request processed by the server.

-The third component is always a Boolean (type

-<type>Bool</type>)

-indicating whether the event came from a

-<systemitem>SendEvent</systemitem>

-protocol request.

-The fourth component is always a pointer to the display

-the event was read from.

-The fifth component is always a resource ID of one kind or another,

-usually a window, carefully selected to be useful to toolkit dispatchers.

-The fifth component should always exist, even if

-the event does not have a natural destination;

-if there is no value

-from the protocol to put in this component, initialize it to zero.

-<!-- .NT -->

-There is an implementation limit such that your host event

-structure size cannot be bigger than the size of the

-<structname>XEvent</structname>

-union of structures.

-There also is no way to guarantee that more than 24 elements or 96 characters

-in the structure will be fully portable between machines.

-<!-- .NE -->

-<indexterm significance="preferred"><primary>XESetWireToEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetWireToEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> event_number</parameter></paramdef>

-  <paramdef>Status<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event code.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when converting an event.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetWireToEvent</function>

-function defines a procedure to be called when an event

-needs to be converted from wire format 

-(<structname>xEvent</structname>)

-to host format 

-(<structname>XEvent</structname>).

-The event number defines which protocol event number to install a

-conversion procedure for.

-<function>XESetWireToEvent</function>

-returns any previously defined procedure.

-<!-- .NT -->

-You can replace a core event conversion function with one

-of your own, although this is not encouraged.

-It would, however, allow you to intercept a core event 

-and modify it before being placed in the queue or otherwise examined.

-<!-- .NE -->

-When Xlib needs to convert an event from wire format to host

-format, your procedure is called with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>XEvent *<parameter>re</parameter></paramdef>

-  <paramdef>xEvent *<parameter>event</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .LP -->

-<!-- .eM -->

-Your procedure must return status to indicate if the conversion succeeded.

-The re argument is a pointer to where the host format event should be stored,

-and the event argument is the 32-byte wire event structure.

-In the 

-<structname>XEvent</structname>

-structure you are creating, 

-you must fill in the five required members of the event structure.

-You should fill in the type member with the type specified for the 

-<structname>xEvent</structname>

-structure.

-You should copy all other members from the 

-<structname>xEvent</structname>

-structure (wire format) to the

-<structname>XEvent</structname>

-structure (host format).

-Your conversion procedure should return 

-<symbol>True</symbol>

-if the event should be placed in the queue or

-<symbol>False</symbol>

-if it should not be placed in the queue.

-</para>

-<para>

-<!-- .LP -->

-To initialize the serial number component of the event, call

-<function>_XSetLastRequestRead</function>

-with the event and use the return value.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>_XSetLastRequestRead</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>unsigned long<function>_XSetLastRequestRead</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>xGenericReply<parameter> *rep</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rep</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the wire event structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>_XSetLastRequestRead</function>

-function computes and returns a complete serial number from the partial

-serial number in the event.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XESetEventToWire</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status *<function>XESetEventToWire</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> event_number</parameter></paramdef>

-  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event code.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when converting an event.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetEventToWire</function>

-function defines a procedure to be called when an event

-needs to be converted from host format

-(<structname>XEvent</structname>)

-to wire format

-(<structname>xEvent</structname>)

-form.  

-The event number defines which protocol event number to install a

-conversion procedure for.

-<function>XESetEventToWire</function>

-returns any previously defined procedure.

-It returns zero if the conversion fails or nonzero otherwise.

-<!-- .NT -->

-You can replace a core event conversion function with one

-of your own, although this is not encouraged.  

-It would, however, allow you to intercept a core event 

-and modify it before being sent to another client.

-<!-- .NE -->

-When Xlib needs to convert an event from host format to wire format, 

-your procedure is called with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>XEvent *<parameter>re</parameter></paramdef>

-  <paramdef>xEvent *<parameter>event</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .LP -->

-<!-- .eM -->

-The re argument is a pointer to the host format event,

-and the event argument is a pointer to where the 32-byte wire event 

-structure should be stored.

-You should fill in the type with the type from the 

-<structname>XEvent</structname>

-structure.

-All other members then should be copied from the host format to the 

-<structname>xEvent</structname>

-structure.

-<indexterm significance="preferred"><primary>XESetWireToError</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool *<function>XESetWireToError</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> error_number</parameter></paramdef>

-  <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>error_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the error code.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when an error is received.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetWireToError</function>

-function defines a procedure to be called when an extension

-error needs to be converted from wire format to host format.

-The error number defines which protocol error code to install

-the conversion procedure for.

-<function>XESetWireToError</function>

-returns any previously defined procedure.

-</para>

-<para>

-<!-- .LP -->

-Use this function for extension errors that contain additional error values

-beyond those in a core X error, when multiple wire errors must be combined

-into a single Xlib error, or when it is necessary to intercept an

-X error before it is otherwise examined.

-</para>

-<para>

-<!-- .LP -->

-When Xlib needs to convert an error from wire format to host format,

-the procedure is called with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>XErrorEvent *<parameter>he</parameter></paramdef>

-  <paramdef>xError *<parameter>we</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .LP -->

-<!-- .eM -->

-The he argument is a pointer to where the host format error should be stored.

-The structure pointed at by he is guaranteed to be as large as an

-<structname>XEvent</structname>

-structure and so can be cast to a type larger than an

-<structname>XErrorEvent</structname>

-to store additional values.

-If the error is to be completely ignored by Xlib

-(for example, several protocol error structures will be combined into

-one Xlib error),

-then the function should return

-<symbol>False</symbol>;

-otherwise, it should return

-<symbol>True</symbol>.

-<indexterm significance="preferred"><primary>XESetError</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetError</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when an error is received.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Inside Xlib, there are times that you may want to suppress the

-calling of the external error handling when an error occurs.

-This allows status to be returned on a call at the cost of the call

-being synchronous (though most such functions are query operations, in any

-case, and are typically programmed to be synchronous).

-</para>

-<para>

-<!-- .LP -->

-When Xlib detects a protocol error in 

-<function>_XReply</function>,

-it calls your procedure with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>xError *<parameter>err</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-  <paramdef>int *<parameter>ret_code</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .LP -->

-<!-- .eM -->

-The err argument is a pointer to the 32-byte wire format error.

-The codes argument is a pointer to the extension codes structure.

-The ret_code argument is the return code you may want 

-<function>_XReply</function>

-returned to.

-</para>

-<para>

-<!-- .LP -->

-If your procedure returns a zero value, 

-the error is not suppressed, and 

-the client's error handler is called.

-(For further information, see section 11.8.2.)

-If your procedure returns nonzero, 

-the error is suppressed, and 

-<function>_XReply</function>

-returns the value of ret_code.

-<indexterm significance="preferred"><primary>XESetErrorString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XESetErrorString</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>char<parameter> *(*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call to obtain an error string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetErrorText</function>

-function returns a string to the user for an error.

-<function>XESetErrorString</function>

-allows you to define a procedure to be called that

-should return a pointer to the error message.

-The following is an example.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>int <parameter>code</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-  <paramdef>char *<parameter>buffer</parameter></paramdef>

-  <paramdef>int <parameter>nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .LP -->

-<!-- .eM -->

-Your procedure is called with the error code for every error detected.

-You should copy nbytes of a null-terminated string containing the

-error message into buffer.

-<indexterm significance="preferred"><primary>XESetPrintErrorValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void *<function>XESetPrintErrorValues</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>void<parameter> (*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when an error is printed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetPrintErrorValues</function>

-function defines a procedure to be called when an extension

-error is printed, to print the error values.

-Use this function for extension errors that contain additional error values

-beyond those in a core X error.

-It returns any previously defined procedure.

-</para>

-<para>

-<!-- .LP -->

-When Xlib needs to print an error,

-the procedure is called with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>XErrorEvent *<parameter>ev</parameter></paramdef>

-  <paramdef>void *<parameter>fp</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .LP -->

-<!-- .eM -->

-The structure pointed at by ev is guaranteed to be as large as an

-<structname>XEvent</structname>

-structure and so can be cast to a type larger than an

-<structname>XErrorEvent</structname>

-to obtain additional values set by using

-<function>XESetWireToError</function>.

-The underlying type of the fp argument is system dependent;

-on a <acronym>POSIX</acronym>-compliant system, fp should be cast to type FILE*.

-<indexterm significance="preferred"><primary>XESetFlushGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetFlushGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> *(*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when a GC is flushed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The procedure set by the

-<function>XESetFlushGC</function>

-function has the same interface as the procedure set by the

-<function>XESetCopyGC</function>

-function, but is called when a GC cache needs to be updated in the server.

-<indexterm significance="preferred"><primary>XESetBeforeFlush</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XESetCopyGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> extension</parameter></paramdef>

-  <paramdef>int<parameter> *(*proc)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extension</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to call when a buffer is flushed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XESetBeforeFlush</function>

-function defines a procedure to be called when data is about to be

-sent to the server.  When data is about to be sent, your procedure is  

-called one or more times with these arguments:

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<!-- .R -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>(*<replaceable>proc</replaceable>)</function></funcdef>

-  <paramdef>Display *<parameter>display</parameter></paramdef>

-  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>

-  <paramdef>char *<parameter>data</parameter></paramdef>

-  <paramdef>long <parameter>len</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .LP -->

-<!-- .eM -->

-The data argument specifies a portion of the outgoing data buffer,

-and its length in bytes is specified by the len argument.

-Your procedure must not alter the contents of the data and must not

-do additional protocol requests to the same display.

-<!-- .SH -->

-Hooks onto Xlib Data Structures

-</para>

-<para>

-<!-- .LP -->

-Various Xlib data structures have provisions for extension procedures

-to chain extension supplied data onto a list.

-These structures are

-<structname>GC</structname>,

-<structname>Visual</structname>,

-<type>Screen</type>,

-<structname>ScreenFormat</structname>,

-<type>Display</type>,

-and 

-<structname>XFontStruct</structname>.

-Because the list pointer is always the first member in the structure, 

-a single set of procedures can be used to manipulate the data

-on these lists.

-</para>

-<para>

-<!-- .LP -->

-The following structure is used in the functions in this section

-and is defined in 

-&lt;X11/Xlib.h&gt;

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XExtData</primary></indexterm>

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<synopsis>

-typedef struct _XExtData {

-	int number;	/* number returned by XInitExtension */

-	struct _XExtData *next;	/* next item on list of data for structure */

-	int (*free_private)();	/* if defined,  called to free private */

-	XPointer private_data;	/* data private to this extension. */

-} XExtData;

-</synopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-When any of the data structures listed above are freed, 

-the list is walked, and the structure's free procedure (if any) is called. 

-If free is NULL, 

-then the library frees both the data pointed to by the private_data member

-and the structure itself. 

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<!-- .TA .5i -->

-<!-- .ta .5i -->

-<synopsis>

-union {	Display *display;

-	GC gc;

-	Visual *visual;

-	Screen *screen;

-	ScreenFormat *pixmap_format;

-	XFontStruct *font } XEDataObject;

-</synopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>XEHeadOfExtensionList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XExtData **<function>XEHeadOfExtensionList</function></funcdef>

-  <paramdef>XEDataObject<parameter> object</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>object</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the object.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XEHeadOfExtensionList</function>

-function returns a pointer to the list of extension structures attached

-to the specified object.

-In concert with 

-<function>XAddToExtensionList</function>,

-<function>XEHeadOfExtensionList</function>

-allows an extension to attach arbitrary data to any of the structures

-of types contained in

-<structname>XEDataObject</structname>.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XAddToExtensionList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAddToExtensionList</function></funcdef>

-  <paramdef>XExtData<parameter> **structure</parameter></paramdef>

-  <paramdef>XExtData<parameter> *ext_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>structure</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ext_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension data structure to add.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The structure argument is a pointer to one of the data structures

-enumerated above.

-You must initialize ext_data-&gt;number with the extension number

-before calling this function.

-<indexterm significance="preferred"><primary>XFindOnExtensionList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XExtData *<function>XFindOnExtensionList</function></funcdef>

-  <paramdef>struct_XExtData<parameter> **structure</parameter></paramdef>

-  <paramdef>int<parameter> number</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>structure</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the extension number from

-<function>XInitExtension</function>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFindOnExtensionList</function>

-function returns the first extension data structure

-for the extension numbered number.

-It is expected that an extension will add at most one extension

-data structure to any single data structure's extension data list.

-There is no way to find additional structures.

-</para>

-<para>

-<!-- .LP -->

-The 

-<function>XAllocID</function>

-macro, which allocates and returns a resource ID, is defined in 

-&lt;X11/Xlib.h&gt;.

-<indexterm significance="preferred"><primary>XAllocID</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAllocID</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-This macro is a call through the 

-<type>Display</type>

-structure to an internal resource ID allocator.

-It returns a resource ID that you can use when creating new resources.

-</para>

-<para>

-<!-- .LP -->

-The 

-<function>XAllocIDs</function>

-macro allocates and returns an array of resource ID.

-<indexterm significance="preferred"><primary>XAllocIDs</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAllocIDs</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XID<parameter> *ids_return</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ids_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the resource IDs.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rep</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of resource IDs requested.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-This macro is a call through the 

-<type>Display</type>

-structure to an internal resource ID allocator.

-It returns resource IDs to the array supplied by the caller.

-To correctly handle automatic reuse of resource IDs, you must call

-<function>XAllocIDs</function>

-when requesting multiple resource IDs.  This call might generate

-protocol requests.

-<!-- .SH -->

-GC Caching

-</para>

-<para>

-<!-- .LP -->

-GCs are cached by the library to allow merging of independent change

-requests to the same GC into single protocol requests.

-This is typically called a write-back cache.

-Any extension procedure whose behavior depends on the contents of a GC

-must flush the GC cache to make sure the server has up-to-date contents

-in its GC.

-</para>

-<para>

-<!-- .LP -->

-The 

-<function>FlushGC</function>

-macro checks the dirty bits in the library's GC structure and calls

-<function>_XFlushGCCache</function>

-if any elements have changed.

-The

-<function>FlushGC</function>

-macro is defined as follows:

-<indexterm significance="preferred"><primary>FlushGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>FlushGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Note that if you extend the GC to add additional resource ID components,

-you should ensure that the library stub sends the change request immediately.

-This is because a client can free a resource immediately after

-using it, so if you only stored the value in the cache without

-forcing a protocol request, the resource might be destroyed before being

-set into the GC.

-You can use the

-<function>_XFlushGCCache</function>

-procedure 

-to force the cache to be flushed.

-The

-<function>_XFlushGCCache</function>

-procedure

-is defined as follows:

-<indexterm significance="preferred"><primary>_XFlushGCCache</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>_XFlushGCCache</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .SH -->

-Graphics Batching

-</para>

-<para>

-<!-- .LP -->

-If you extend X to add more poly graphics primitives, you may be able to

-take advantage of facilities in the library to allow back-to-back 

-single calls to be transformed into poly requests.

-This may dramatically improve performance of programs that are not

-written using poly requests. 

-A pointer to an 

-<structname>xReq</structname>,

-called last_req in the display structure, is the last request being processed.  

-By checking that the last request

-type, drawable, gc, and other options are the same as the new one

-and that there is enough space left in the buffer, you may be able

-to just extend the previous graphics request by extending the length

-field of the request and appending the data to the buffer.  

-This can improve performance by five times or more in naive programs.  

-For example, here is the source for the 

-<function>XDrawPoint</function>

-stub.

-(Writing extension stubs is discussed in the next section.)

-</para>

-<!-- .sM -->

-<!-- .nf -->

-<programlisting>

-#include &lt;X11/Xlibint.h&gt;

-

-/* precompute the maximum size of batching request allowed */

-

-static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);

-

-XDrawPoint(dpy, d, gc, x, y)

-    register Display *dpy;

-    Drawable d;

-    GC gc;

-    int x, y; /* INT16 */

-{

-    xPoint *point;

-    LockDisplay(dpy);

-    FlushGC(dpy, gc);

-    {

-    register xPolyPointReq *req = (xPolyPointReq *) dpy-&gt;last_req;

-    /* if same as previous request, with same drawable, batch requests */

-    if (

-          (req-&gt;reqType == X_PolyPoint)

-       &amp;&amp; (req-&gt;drawable == d)

-       &amp;&amp; (req-&gt;gc == gc-&gt;gid)

-       &amp;&amp; (req-&gt;coordMode == CoordModeOrigin)

-       &amp;&amp; ((dpy-&gt;bufptr + sizeof (xPoint)) &lt;= dpy-&gt;bufmax)

-       &amp;&amp; (((char *)dpy-&gt;bufptr - (char *)req) &lt; size) ) {

-         point = (xPoint *) dpy-&gt;bufptr;

-         req-&gt;length += sizeof (xPoint) &gt;&gt; 2;

-         dpy-&gt;bufptr += sizeof (xPoint);

-         }

-

-    else {

-        GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */

-        req-&gt;drawable = d;

-        req-&gt;gc = gc-&gt;gid;

-        req-&gt;coordMode = CoordModeOrigin;

-        point = (xPoint *) (req + 1);

-        }

-    point-&gt;x = x;

-    point-&gt;y = y;

-    }

-    UnlockDisplay(dpy);

-    SyncHandle();

-}

-</programlisting>

-<!-- .fi -->

-<para>

-<!-- .LP -->

-<!-- .eM -->

-To keep clients from generating very long requests that may monopolize the 

-server,

-there is a symbol defined in

-&lt;X11/Xlibint.h&gt;

-of EPERBATCH on the number of requests batched.

-Most of the performance benefit occurs in the first few merged requests.

-Note that 

-<function>FlushGC</function>

-is called <emphasis remap='I'>before</emphasis> picking up the value of last_req,

-because it may modify this field.

-<!-- .SH -->

-Writing Extension Stubs

-</para>

-<para>

-<!-- .LP -->

-All X requests always contain the length of the request,

-expressed as a 16-bit quantity of 32 bits.

-This means that a single request can be no more than 256K bytes in

-length.

-Some servers may not support single requests of such a length.

-The value of dpy-&gt;max_request_size contains the maximum length as

-defined by the server implementation.

-For further information,

-see ``X Window System Protocol.''

-<!-- .SH -->

-Requests, Replies, and Xproto.h

-</para>

-<para>

-<!-- .LP -->

-The 

-&lt;X11/Xproto.h&gt;

-file contains three sets of definitions that

-are of interest to the stub implementor:  

-request names, request structures, and reply structures.

-</para>

-<para>

-<!-- .LP -->

-You need to generate a file equivalent to 

-&lt;X11/Xproto.h&gt;

-for your extension and need to include it in your stub procedure.

-Each stub procedure also must include 

-&lt;X11/Xlibint.h&gt; .

-</para>

-<para>

-<!-- .LP -->

-The identifiers are deliberately chosen in such a way that, if the

-request is called X_DoSomething, then its request structure is

-xDoSomethingReq, and its reply is xDoSomethingReply.  

-The GetReq family of macros, defined in 

-&lt;X11/Xlibint.h&gt; ,

-takes advantage of this naming scheme.

-</para>

-<para>

-<!-- .LP -->

-For each X request, 

-there is a definition in 

-&lt;X11/Xproto.h&gt;

-that looks similar to this:

-</para>

-<para>

-<!-- .LP -->

-<!-- .R -->

-<programlisting>

-#define X_DoSomething   42

-</programlisting>

-In your extension header file, 

-this will be a minor opcode, 

-instead of a major opcode.

-<!-- .SH -->

-Request Format

-</para>

-<para>

-<!-- .LP -->

-Every request contains an 8-bit major opcode and a 16-bit length field

-expressed in units of 4 bytes.  

-Every request consists of 4 bytes of header

-(containing the major opcode, the length field, and a data byte) followed by

-zero or more additional bytes of data. 

-The length field defines the total length of the request, including the header.

-The length field in a request must equal the minimum length required to contain 

-the request. 

-If the specified length is smaller or larger than the required length, 

-the server should generate a 

-<errorname>BadLength</errorname>

-error.

-Unused bytes in a request are not required to be zero.  

-Extensions should be designed in such a way that long protocol requests

-can be split up into smaller requests,

-if it is possible to exceed the maximum request size of the server.

-The protocol guarantees the maximum request size to be no smaller than

-4096 units (16384 bytes).

-</para>

-<para>

-<!-- .LP -->

-Major opcodes 128 through 255 are reserved for extensions.

-Extensions are intended to contain multiple requests, 

-so extension requests typically have an additional minor opcode encoded 

-in the second data byte in the request header, 

-but the placement and interpretation of this minor opcode as well as all

-other fields in extension requests are not defined by the core protocol.

-Every request is implicitly assigned a sequence number (starting with one)

-used in replies, errors, and events.

-</para>

-<para>

-<!-- .LP -->

-To help but not cure portability problems to certain machines, the

-<symbol>B16</symbol>

-and

-<symbol>B32</symbol>

-macros have been defined so that they can become bitfield specifications 

-on some machines.

-For example, on a Cray,

-these should be used for all 16-bit and 32-bit quantities, as discussed below.

-</para>

-<para>

-<!-- .LP -->

-Most protocol requests have a corresponding structure typedef in

-&lt;X11/Xproto.h&gt;,

-which looks like:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>xDoSomethingReq</primary></indexterm>

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<synopsis>

-typedef struct _DoSomethingReq {

-	CARD8 reqType;		/* X_DoSomething */

-	CARD8 someDatum;	/* used differently in different requests */

-	CARD16 length B16;	/* total # of bytes in request, divided by 4 */

-	...

-	/* request-specific data */

-	...

-} xDoSomethingReq;

-</synopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If a core protocol request has a single 32-bit argument, 

-you need not declare a request structure in your extension header file.

-Instead, such requests use the

-<structname>xResourceReq</structname>

-structure in

-&lt;X11/Xproto.h&gt;.

-This structure is used for any request whose single argument is a 

-<type>Window</type>,

-<type>Pixmap</type>,

-<type>Drawable</type>,

-<type>GContext</type>,

-<type>Font</type>,

-<type>Cursor</type>,

-<type>Colormap</type>,

-<type>Atom</type>,

-or

-<type>VisualID</type>.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>xResourceReq</primary></indexterm>

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<synopsis>

-typedef struct _ResourceReq {

-	CARD8 reqType;	/* the request type, e.g. X_DoSomething */

-	BYTE pad;	/* not used */

-	CARD16 length B16;	/* 2 (= total # of bytes in request, divided by 4) */

-	CARD32 id B32;	/* the Window, Drawable, Font, GContext, etc. */

-} xResourceReq;

-</synopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If convenient,

-you can do something similar in your extension header file. 

-</para>

-<para>

-<!-- .LP -->

-In both of these structures, 

-the reqType field identifies the type of the request (for example, 

-X_MapWindow or X_CreatePixmap).  

-The length field tells how long the request is

-in units of 4-byte longwords. 

-This length includes both the request structure itself and any

-variable-length data, such as strings or lists, that follow the

-request structure.  

-Request structures come in different sizes, 

-but all requests are padded to be multiples of four bytes long.

-</para>

-<para>

-<!-- .LP -->

-A few protocol requests take no arguments at all. 

-Instead, they use the

-<structname>xReq</structname>

-structure in

-&lt;X11/Xproto.h&gt;,

-which contains only a reqType and a length (and a pad byte).

-</para>

-<para>

-<!-- .LP  -->

-If the protocol request requires a reply, 

-then

-&lt;X11/Xproto.h&gt;

-also contains a reply structure typedef:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>xDoSomethingReply</primary></indexterm>

-<!-- .sM -->

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-<synopsis>

-typedef struct _DoSomethingReply {

-	BYTE type;	/* always X_Reply */

-	BYTE someDatum;	/* used differently in different requests */

-	CARD16 sequenceNumber B16;	/* # of requests sent so far */

-	CARD32 length B32;	/* # of additional bytes, divided by 4 */

-	...

-	/* request-specific data */

-	...

-} xDoSomethingReply;

-</synopsis>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Most of these reply structures are 32 bytes long. 

-If there are not that many reply values, 

-then they contain a sufficient number of pad fields

-to bring them up to 32 bytes.  

-The length field is the total number of bytes in the request minus 32, 

-divided by 4.  

-This length will be nonzero only if:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The reply structure is followed by variable-length data,

-such as a list or string.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The reply structure is longer than 32 bytes.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Only 

-<systemitem>GetWindowAttributesl</systemitem>,

-<systemitem>QueryFont</systemitem>,

-<systemitem>QueryKeymap</systemitem>,

-and

-<systemitem>GetKeyboardControl</systemitem>

-have reply structures longer than 32 bytes in the core protocol.

-</para>

-<para>

-<!-- .LP -->

-A few protocol requests return replies that contain no data.  

-&lt;X11/Xproto.h&gt;

-does not define reply structures for these.

-Instead, they use the 

-<structname>xGenericReply</structname>

-structure, which contains only a type, length,

-and sequence number (and sufficient padding to make it 32 bytes long).

-<!-- .SH -->

-Starting to Write a Stub Procedure

-</para>

-<para>

-<!-- .LP -->

-An Xlib stub procedure should start like this:

-</para>

-<para>

-<!-- .LP -->

-<!-- .R -->

-<programlisting>

-#include "&lt;X11/Xlibint.h&gt;

-

-XDoSomething (arguments, ... )

-/* argument declarations */

-{

-

-register XDoSomethingReq *req;

-...

-</programlisting>

-If the protocol request has a reply, 

-then the variable declarations should include the reply structure for the request.

-The following is an example:

-</para>

-<para>

-<!-- .LP -->

-<!-- .R -->

-<programlisting>

-xDoSomethingReply rep;

-</programlisting>

-<!-- .SH -->

-Locking Data Structures

-</para>

-<para>

-<!-- .LP -->

-To lock the display structure for systems that

-want to support multithreaded access to a single display connection,

-each stub will need to lock its critical section.

-Generally, this section is the point from just before the appropriate GetReq

-call until all arguments to the call have been stored into the buffer.

-The precise instructions needed for this locking depend upon the machine

-architecture. 

-Two calls, which are generally implemented as macros, have been provided.

-<indexterm significance="preferred"><primary>LockDisplay</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>LockDisplay</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>UnlockDisplay</primary></indexterm>

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>UnlockDisplay</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .SH -->

-Sending the Protocol Request and Arguments

-</para>

-<para>

-<!-- .LP -->

-After the variable declarations, 

-a stub procedure should call one of four macros defined in 

-&lt;X11/Xlibint.h&gt;:

-<function>GetReq</function>,

-<function>GetReqExtra</function>,

-<function>GetResReq</function>,

-or 

-<function>GetEmptyReq</function>.

-All of these macros take, as their first argument,

-the name of the protocol request as declared in 

-&lt;X11/Xproto.h&gt;

-except with X_ removed.   

-Each one declares a 

-<type>Display</type>

-structure pointer,

-called dpy, and a pointer to a request structure, called req,

-which is of the appropriate type.

-The macro then appends the request structure to the output buffer, 

-fills in its type and length field, and sets req to point to it.

-</para>

-<para>

-<!-- .LP -->

-If the protocol request has no arguments (for instance, X_GrabServer),

-then use 

-<function>GetEmptyReq</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .R  -->

-<programlisting>

-GetEmptyReq (DoSomething, req);

-</programlisting>

-If the protocol request has a single 32-bit argument (such as a

-<type>Pixmap</type>,

-<type>Window</type>,

-<type>Drawable</type>,

-<type>Atom</type>,

-and so on),

-then use 

-<function>GetResReq</function>.

-The second argument to the macro is the 32-bit object.  

-<symbol>X_MapWindow</symbol>

-is a good example.

-</para>

-<para>

-<!-- .LP -->

-<!-- .R -->

-<programlisting>

-GetResReq (DoSomething, rid, req);

-</programlisting>

-The rid argument is the 

-<type>Pixmap</type>,

-<type>Window</type>,

-or other resource ID.

-</para>

-<para>

-<!-- .LP -->

-If the protocol request takes any other argument list, 

-then call 

-<function>GetReq</function>.

-After the 

-<function>GetReq</function>,

-you need to set all the other fields in the request structure,

-usually from arguments to the stub procedure.

-</para>

-<para>

-<!-- .LP -->

-<!-- .R -->

-<programlisting>

-GetReq (DoSomething, req);

-/* fill in arguments here */

-req-&gt;arg1 = arg1;

-req-&gt;arg2 = arg2;

-...

-</programlisting>

-A few stub procedures (such as 

-<function>XCreateGC</function>

-and 

-<function>XCreatePixmap</function>)

-return a resource ID to the caller but pass a resource ID as an argument

-to the protocol request.   

-Such procedures use the macro 

-<function>XAllocID</function>

-to allocate a resource ID from the range of IDs 

-that were assigned to this client when it opened the connection.

-</para>

-<para>

-<!-- .LP -->

-<!-- .R -->

-<programlisting>

-rid = req-&gt;rid = XAllocID();

-...

-return (rid);

-</programlisting>

-Finally, some stub procedures transmit a fixed amount of variable-length

-data after the request.  

-Typically, these procedures (such as

-<function>XMoveWindow</function>

-and 

-<function>XSetBackground</function>)

-are special cases of more general functions like 

-<function>XMoveResizeWindow</function>

-and 

-<function>XChangeGC</function>.

-These procedures use 

-<function>GetReqExtra</function>,

-which is the same as 

-<function>GetReq</function>

-except that it takes an additional argument (the number of

-extra bytes to allocate in the output buffer after the request structure).  

-This number should always be a multiple of four.

-<!-- .SH -->

-Variable Length Arguments

-</para>

-<para>

-<!-- .LP -->

-Some protocol requests take additional variable-length data that

-follow the 

-<type>xDoSomethingReq</type>

-structure.    

-The format of this data varies from request to request. 

-Some requests require a sequence of 8-bit bytes, 

-others a sequence of 16-bit or 32-bit entities, 

-and still others a sequence of structures.

-</para>

-<para>

-<!-- .LP -->

-It is necessary to add the length of any variable-length data to the

-length field of the request structure.  

-That length field is in units of 32-bit longwords.  

-If the data is a string or other sequence of 8-bit bytes, 

-then you must round the length up and shift it before adding:

-</para>

-<para>

-<!-- .LP -->

-<!-- .R -->

-<programlisting>

-req-&gt;length += (nbytes+3)&gt;&gt;2;

-</programlisting>

-To transmit variable-length data, use the 

-<function>Data</function>

-macros.

-If the data fits into the output buffer, 

-then this macro copies it to the buffer.  

-If it does not fit, however,

-the 

-<function>Data</function>

-macro calls 

-<function>_XSend</function>,

-which transmits first the contents of the buffer and then your data.

-The 

-<function>Data</function>

-macros take three arguments:  

-the display, a pointer to the beginning of the data, 

-and the number of bytes to be sent.

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>Data</function></funcdef>

-  <paramdef><parameter> display</parameter></paramdef>

-  <paramdef>(char<parameter> *</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>Data</function>,

-<function>Data16</function>,

-and

-<function>Data32</function>

-are macros that may use their last argument

-more than once, so that argument should be a variable rather than

-an expression such as ``nitems*sizeof(item)''.  

-You should do that kind of computation in a separate statement before calling 

-them.

-Use the appropriate macro when sending byte, short, or long data.

-</para>

-<para>

-<!-- .LP -->

-If the protocol request requires a reply, 

-then call the procedure 

-<function>_XSend</function>

-instead of the 

-<function>Data</function>

-macro.  

-<function>_XSend</function>

-takes the same arguments, but because it sends your data immediately instead of 

-copying it into the output buffer (which would later be flushed

-anyway by the following call on 

-<function>_XReply</function>),

-it is faster.

-<!-- .SH -->

-Replies

-</para>

-<para>

-<!-- .LP -->

-If the protocol request has a reply, 

-then call 

-<function>_XReply</function>

-after you have finished dealing with 

-all the fixed-length and variable-length arguments.  

-<function>_XReply</function>

-flushes the output buffer and waits for an 

-<structname>xReply</structname>

-packet to arrive.  

-If any events arrive in the meantime,

-<function>_XReply</function>

-places them in the queue for later use.

-<indexterm significance="preferred"><primary>_XReply</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>_XReply</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>xReply<parameter> *rep</parameter></paramdef>

-  <paramdef>int<parameter> extra</parameter></paramdef>

-  <paramdef>Bool<parameter> discard</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rep</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the reply structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>extra</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of 32-bit words expected after the replay.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>discard</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies if any data beyond that specified in the extra argument

-should be discarded.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>_XReply</function>

-function waits for a reply packet and copies its contents into the

-specified rep.  

-<function>_XReply</function>

-handles error and event packets that occur before the reply is received.

-<function>_XReply</function>

-takes four arguments:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-A 

-<type>Display</type>

-* structure

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A pointer to a reply structure (which must be cast to an 

-<structname>xReply</structname>

-*)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The number of additional 32-bit words (beyond 

-<function>sizeof( xReply</function>)

-= 32 bytes)

-in the reply structure

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A Boolean that indicates whether

-<function>_XReply</function>

-is to discard any additional bytes

-beyond those it was told to read

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Because most reply structures are 32 bytes long, 

-the third argument is usually 0.  

-The only core protocol exceptions are the replies to 

-<systemitem>GetWindowAttributesl</systemitem>,

-<systemitem>QueryFont</systemitem>,

-<systemitem>QueryKeymap</systemitem>,

-and 

-<systemitem>GetKeyboardControl</systemitem>,

-which have longer replies.

-</para>

-<para>

-<!-- .LP -->

-The last argument should be 

-<symbol>False</symbol>

-if the reply structure is followed

-by additional variable-length data (such as a list or string).  

-It should be 

-<symbol>True</symbol>

-if there is not any variable-length data.

-<!-- .NT -->

-This last argument is provided for upward-compatibility reasons

-to allow a client to communicate properly with a hypothetical later

-version of the server that sends more data than the client expected.

-For example, some later version of 

-<systemitem>GetWindowAttributesl</systemitem>

-might use a

-larger, but compatible, 

-<structname>xGetWindowAttributesReply</structname>

-that contains additional attribute data at the end.

-<!-- .NE -->

-<function>_XReply</function>

-returns 

-<symbol>True</symbol>

-if it received a reply successfully or 

-<symbol>False</symbol>

-if it received any sort of error. 

-</para>

-<para>

-<!-- .LP -->

-For a request with a reply that is not followed by variable-length

-data, you write something like:

-</para>

-<para>

-<!-- .LP -->

-<!-- .R -->

-<programlisting>

-_XReply(display, (xReply *)&amp;rep, 0, True);

-*ret1 = rep.ret1;

-*ret2 = rep.ret2;

-*ret3 = rep.ret3;

-...

-UnlockDisplay(dpy);

-SyncHandle();

-return (rep.ret4);

-}

-</programlisting>

-If there is variable-length data after the reply, 

-change the 

-<symbol>True</symbol>

-to 

-<symbol>False</symbol>,

-and use the appropriate

-<function>_XRead</function>

-function to read the variable-length data.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>_XRead</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *data_return</parameter></paramdef>

-  <paramdef>long<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the buffer.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes required.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>_XRead</function>

-function reads the specified number of bytes into data_return.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>_XRead16</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>short<parameter> *data_return</parameter></paramdef>

-  <paramdef>long<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the buffer.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes required.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>_XRead16</function>

-function reads the specified number of bytes,

-unpacking them as 16-bit quantities,

-into the specified array as shorts.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>_XRead32</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>long<parameter> *data_return</parameter></paramdef>

-  <paramdef>long<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the buffer.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes required.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>_XRead32</function>

-function reads the specified number of bytes,

-unpacking them as 32-bit quantities,

-into the specified array as longs.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>_XRead16Pad</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>short<parameter> *data_return</parameter></paramdef>

-  <paramdef>long<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the buffer.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes required.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>_XRead16Pad</function>

-function reads the specified number of bytes,

-unpacking them as 16-bit quantities,

-into the specified array as shorts.

-If the number of bytes is not a multiple of four,

-<function>_XRead16Pad</function>

-reads and discards up to two additional pad bytes.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>_XReadPad</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *data_return</parameter></paramdef>

-  <paramdef>long<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the buffer.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes required.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>_XReadPad</function>

-function reads the specified number of bytes into data_return.

-If the number of bytes is not a multiple of four,

-<function>_XReadPad</function>

-reads and discards up to three additional pad bytes.

-</para>

-<para>

-<!-- .LP -->

-Each protocol request is a little different. 

-For further information,

-see the Xlib sources for examples.

-<!-- .SH -->

-Synchronous Calling

-</para>

-<para>

-<!-- .LP -->

-Each procedure should have a call, just before returning to the user, 

-to a macro called

-<systemitem>SyncHandle</systemitem>.

-If synchronous mode is enabled (see 

-<function>XSynchronize</function>),

-the request is sent immediately.

-The library, however, waits until any error the procedure could generate

-at the server has been handled.

-<!-- .SH -->

-Allocating and Deallocating Memory

-</para>

-<para>

-<!-- .LP -->

-To support the possible reentry of these procedures, 

-you must observe several conventions when allocating and deallocating memory,

-most often done when returning data to the user from the window

-system of a size the caller could not know in advance

-(for example, a list of fonts or a list of extensions).

-The standard C library functions on many systems

-are not protected against signals or other multithreaded uses.

-The following analogies to standard I/O library functions

-have been defined:

-</para>

-<para>

-<!-- .LP -->

-These should be used in place of any calls you would make to the normal

-C library functions.

-</para>

-<para>

-<!-- .LP -->

-If you need a single scratch buffer inside a critical section 

-(for example, to pack and unpack data to and from the wire protocol),

-the general memory allocators may be too expensive to use

-(particularly in output functions, which are performance critical).  

-The following function returns a scratch buffer for use within a

-critical section:

-<indexterm significance="preferred"><primary>_XAllocScratch</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>_XAllocScratch</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes required.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-This storage must only be used inside of a critical section of your

-stub.  The returned pointer cannot be assumed valid after any call

-that might permit another thread to execute inside Xlib.  For example,

-the pointer cannot be assumed valid after any use of the

-<function>GetReq</function>

-or

-<function>Data</function>

-families of macros,

-after any use of

-<function>_XReply</function>,

-or after any use of the

-<function>_XSend</function>

-or

-<function>_XRead</function>

-families of functions.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-The following function returns a scratch buffer for use across

-critical sections:

-<indexterm significance="preferred"><primary>_XAllocTemp</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>_XAllocTemp</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes required.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-This storage can be used across calls that might permit another thread to

-execute inside Xlib.  The storage must be explicitly returned to Xlib.

-The following function returns the storage:

-<indexterm significance="preferred"><primary>_XFreeTemp</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>_XFreeTemp</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *buf</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buf</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the buffer to return.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size of the buffer.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-You must pass back the same pointer and size that were returned by

-<function>_XAllocTemp</function>.

-<!-- .SH -->

-Portability Considerations

-</para>

-<para>

-<!-- .LP -->

-Many machine architectures, 

-including many of the more recent <acronym>RISC</acronym> architectures,

-do not correctly access data at unaligned locations; 

-their compilers pad out structures to preserve this characteristic.

-Many other machines capable of unaligned references pad inside of structures

-as well to preserve alignment, because accessing aligned data is

-usually much faster.

-Because the library and the server use structures to access data at

-arbitrary points in a byte stream,

-all data in request and reply packets <emphasis remap='I'>must</emphasis> be naturally aligned;

-that is, 16-bit data starts on 16-bit boundaries in the request

-and 32-bit data on 32-bit boundaries.

-All requests <emphasis remap='I'>must</emphasis> be a multiple of 32 bits in length to preserve

-the natural alignment in the data stream.

-You must pad structures out to 32-bit boundaries.

-Pad information does not have to be zeroed unless you want to

-preserve such fields for future use in your protocol requests.

-Floating point varies radically between machines and should be

-avoided completely if at all possible.

-</para>

-<para>

-<!-- .LP -->

-This code may run on machines with 16-bit ints.  

-So, if any integer argument, variable, or return value either can take 

-only nonnegative values or is declared as a

-<type>CARD16</type>

-in the protocol, be sure to declare it as

-<type>unsigned</type>

-<type>int</type>

-and not as

-<type>int</type>.

-(This, of course, does not apply to Booleans or enumerations.)

-</para>

-<para>

-<!-- .LP -->

-Similarly, 

-if any integer argument or return value is declared

-<type>CARD32</type>

-in the protocol, 

-declare it as an

-<type>unsigned</type>

-<type>long</type>

-and not as

-<type>int</type>

-or

-<type>long</type>.

-This also goes for any internal variables that may

-take on values larger than the maximum 16-bit

-<type>unsigned</type>

-<type>int</type>.

-</para>

-<para>

-<!-- .LP -->

-The library currently assumes that a

-<type>char</type>

-is 8 bits, a

-<type>short</type>

-is 16 bits, an

-<type>int</type>

-is 16 or 32 bits, and a

-<type>long</type>

-is 32 bits.  

-The 

-<function>PackData</function>

-macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. 

-However, much more work is needed to make this work properly.

-<!-- .SH -->

-Deriving the Correct Extension Opcode

-</para>

-<para>

-<!-- .LP -->

-The remaining problem a writer of an extension stub procedure faces that

-the core protocol does not face is to map from the call to the proper

-major and minor opcodes.  

-While there are a number of strategies, 

-the simplest and fastest is outlined below.

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Declare an array of pointers, _NFILE long (this is normally found

-in 

-&lt;stdio.h&gt;

-and is the number of file descriptors supported on the system)

-of type 

-<structname>XExtCodes</structname>.

-Make sure these are all initialized to NULL.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-When your stub is entered, your initialization test is just to use

-the display pointer passed in to access the file descriptor and an index

-into the array.  

-If the entry is NULL, then this is the first time you

-are entering the procedure for this display.  

-Call your initialization procedure and pass to it the display pointer.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Once in your initialization procedure, call 

-<function>XInitExtension</function>;

-if it succeeds, store the pointer returned into this array.  

-Make sure to establish a close display handler to allow you to zero the entry.

-Do whatever other initialization your extension requires.

-(For example, install event handlers and so on.)

-Your initialization procedure would normally return a pointer to the

-<structname>XExtCodes</structname>

-structure for this extension, which is what would normally

-be found in your array of pointers.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-After returning from your initialization procedure, 

-the stub can now continue normally, because it has its major opcode safely 

-in its hand in the 

-<structname>XExtCodes</structname>

-structure.

-<!-- .bp -->

-    </para>

-  </listitem>

-</itemizedlist>

-</appendix>

+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+	  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<appendix id="extensions">
+<title>Extensions</title>
+<para>
+<!-- .XE -->
+Because X can evolve by extensions to the core protocol, 
+it is important that extensions not be perceived as second-class citizens.
+At some point, 
+your favorite extensions may be adopted as additional parts of the 
+X Standard.
+</para>
+<para>
+<!-- .LP -->
+Therefore, there should be little to distinguish the use of an extension from 
+that of the core protocol.
+To avoid having to initialize extensions explicitly in application programs, 
+it is also important that extensions perform lazy evaluations,
+automatically initializing themselves when called for the first time.  
+</para>
+<para>
+<!-- .LP -->
+This appendix describes techniques for writing extensions to Xlib that will
+run at essentially the same performance as the core protocol requests.
+</para>
+<!-- .NT -->
+<note><para>
+It is expected that a given extension to X consists of multiple
+requests.
+Defining 10 new features as 10 separate extensions is a bad practice.
+Rather, they should be packaged into a single extension
+and should use minor opcodes to distinguish the requests.
+</para></note>
+<!-- .NE -->
+<para>
+<!-- .LP -->
+The symbols and macros used for writing stubs to Xlib are listed in
+&lt;X11/Xlibint.h&gt; .
+<!-- .SH -->
+Basic Protocol Support Routines
+</para>
+<para>
+The basic protocol requests for extensions are 
+<function>XQueryExtension</function>
+and
+<function>XListExtensions</function>.
+</para>
+<indexterm significance="preferred"><primary>XQueryExtension</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xqueryextension'>
+<funcprototype>
+  <funcdef>Bool <function>XQueryExtension</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *name</parameter></paramdef>
+  <paramdef>int<parameter> *major_opcode_return</parameter></paramdef>
+  <paramdef>int<parameter> *first_event_return</parameter></paramdef>
+  <paramdef>int<parameter> *first_error_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>display</term>
+    <listitem>
+      <para>Specifies the connection to the X server.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>name</term>
+    <listitem>
+      <para>Specifies the extension name.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>major_opcode_return</term>
+    <listitem>
+      <para>Returns the major opcode.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>first_event_return</term>
+    <listitem>
+      <para>Returns the first event code, if any.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>first_error_return</term>
+    <listitem>
+      <para>Returns the first error code, if any.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryExtension</function>
+function determines if the named extension is present.  
+If the extension is not present,
+<function>XQueryExtension</function>
+returns
+<symbol>False</symbol>;
+otherwise, it returns
+<symbol>True</symbol>.
+If the extension is present,
+<function>XQueryExtension</function>
+returns the major opcode for the extension to major_opcode_return;
+otherwise,
+it returns zero.
+Any minor opcode and the request formats are specific to the
+extension.  
+If the extension involves additional event types, 
+<function>XQueryExtension</function>
+returns the base event type code to first_event_return;
+otherwise, 
+it returns zero.  
+The format of the events is specific to the extension.  
+If the extension involves additional error codes, 
+<function>XQueryExtension</function>
+returns the base error code to first_error_return;
+otherwise, 
+it returns zero.  
+The format of additional data in the errors is specific to the extension.
+</para>
+<para>
+<!-- .LP -->
+If the extension name is not in the Host Portable Character Encoding
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG'' 
+are all considered different names.
+<indexterm significance="preferred"><primary>XListExtensions</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlistextensions'>
+<funcprototype>
+  <funcdef>char **<function>XListExtensions</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> *nextensions_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nextensions_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of extensions listed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListExtensions</function>
+function returns a list of all extensions supported by the server.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+<indexterm significance="preferred"><primary>XFreeExtensionList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreeextensionlist'>
+<funcprototype>
+  <funcdef><function>XFreeExtensionList</function></funcdef>
+  <paramdef>char<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the list of extension names.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeExtensionList</function>
+function frees the memory allocated by 
+<function>XListExtensions</function>.
+<!-- .SH -->
+Hooking into Xlib 
+</para>
+<para>
+<!-- .LP -->
+These functions allow you to hook into the library.  
+They are not normally used by application programmers but are used 
+by people who need to extend the core X protocol and
+the X library interface.
+The functions, which generate protocol requests for X, are typically
+called stubs.
+</para>
+<para>
+<!-- .LP -->
+In extensions, stubs first should check to see if they have initialized 
+themselves on a connection.
+If they have not, they then should call 
+<function>XInitExtension</function>
+to attempt to initialize themselves on the connection.
+</para>
+<para>
+<!-- .LP -->
+If the extension needs to be informed of GC/font allocation or
+deallocation or if the extension defines new event types, 
+the functions described here allow the extension to be 
+called when these events occur.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XExtCodes</structname>
+structure returns the information from 
+<function>XInitExtension</function>
+and is defined in
+&lt;X11/Xlib.h&gt; :
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XExtCodes</primary></indexterm>
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<synopsis>
+typedef struct _XExtCodes {	/* public to extension, cannot be changed */
+	int extension;		/* extension number */
+	int major_opcode;	/* major op-code assigned by server */
+	int first_event;	/* first event number for the extension */
+	int first_error;	/* first error number for the extension */
+} XExtCodes;
+</synopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XInitExtension</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xinitextension'>
+<funcprototype>
+  <funcdef>XExtCodes *<function>XInitExtension</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInitExtension</function>
+function determines if the named extension exists. 
+Then, it allocates storage for maintaining the 
+information about the extension on the connection, 
+chains this onto the extension list for the connection,
+and returns the information the stub implementor will need to access
+the extension.
+If the extension does not exist,
+<function>XInitExtension</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+If the extension name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG'' 
+are all considered different names.
+</para>
+<para>
+<!-- .LP -->
+The extension number in the 
+<structname>XExtCodes</structname>
+structure is
+needed in the other calls that follow.  
+This extension number is unique only to a single connection.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XAddExtension</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xaddextension'>
+<funcprototype>
+  <funcdef>XExtCodes *<function>XAddExtension</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For local Xlib extensions, the
+<function>XAddExtension</function>
+function allocates the
+<structname>XExtCodes</structname>
+structure, bumps the extension number count,
+and chains the extension onto the extension list.
+(This permits extensions to Xlib without requiring server extensions.)
+<!-- .SH -->
+Hooks into the Library
+</para>
+<para>
+<!-- .LP -->
+These functions allow you to define procedures that are to be
+called when various circumstances occur.
+The procedures include the creation of a new GC for a connection,
+the copying of a GC, the freeing of a GC, the creating and freeing of fonts,
+the conversion of events defined by extensions to and from wire
+format, and the handling of errors.
+</para>
+<para>
+<!-- .LP -->
+All of these functions return the previous procedure defined for this
+extension.
+<indexterm significance="preferred"><primary>XESetCloseDisplay</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetclosedisplay'>
+<funcprototype>
+  <funcdef>int <function>XESetCloseDisplay</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when the display is closed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetCloseDisplay</function>
+function defines a procedure to be called whenever
+<function>XCloseDisplay</function>
+is called.  
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When 
+<function>XCloseDisplay</function>
+is called, 
+your procedure is called 
+with these arguments:
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+</para>
+<para>
+<indexterm significance="preferred"><primary>XESetCreateGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetcreategc'>
+<funcprototype>
+  <funcdef>int *<function>XESetCreateGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when a GC is closed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetCreateGC</function>
+function defines a procedure to be called whenever
+a new GC is created.  
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When a GC is created, 
+your procedure is called with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>GC <parameter>gc</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+</para>
+<indexterm significance="preferred"><primary>XESetCopyGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetcopygc'>
+<funcprototype>
+  <funcdef>int *<function>XESetCopyGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when GC components are copied.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetCopyGC</function>
+function defines a procedure to be called whenever
+a GC is copied.  
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When a GC is copied, 
+your procedure is called with these arguments:
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>GC <parameter>gc</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+</para>
+<funcsynopsis id='xesetfreegc'>
+<funcprototype>
+  <funcdef>int *<function>XESetFreeGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when a GC is freed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The
+<function>XESetFreeGC</function>
+function defines a procedure to be called whenever
+a GC is freed.  
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When a GC is freed, 
+your procedure is called with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>GC <parameter>gc</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XESetCreateFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetcreatefont'>
+<funcprototype>
+  <funcdef>int *<function>XESetCreateFont</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when a font is created.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetCreateFont</function>
+function defines a procedure to be called whenever
+<function>XLoadQueryFont</function>
+and
+<function>XQueryFont</function>
+are called.  
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When 
+<function>XLoadQueryFont</function>
+or
+<function>XQueryFont</function>
+is called, 
+your procedure is called with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>XFontStruct *<parameter>fs</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XESetFreeFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetfreefont'>
+<funcprototype>
+  <funcdef>int *<function>XESetFreeFont</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when a font is freed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetFreeFont</function>
+function defines a procedure to be called whenever
+<function>XFreeFont</function>
+is called.  
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When 
+<function>XFreeFont</function>
+is called, your procedure is called with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>XFontStruct *<parameter>fs</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XESetWireToEvent</function>
+and
+<function>XESetEventToWire</function>
+functions allow you to define new events to the library.
+An 
+<structname>XEvent</structname>
+structure always has a type code (type
+<type>int</type>)
+as the first component.
+This uniquely identifies what kind of event it is.
+The second component is always the serial number (type
+<type>unsigned</type>
+<type>long</type>)
+of the last request processed by the server.
+The third component is always a Boolean (type
+<type>Bool</type>)
+indicating whether the event came from a
+<systemitem>SendEvent</systemitem>
+protocol request.
+The fourth component is always a pointer to the display
+the event was read from.
+The fifth component is always a resource ID of one kind or another,
+usually a window, carefully selected to be useful to toolkit dispatchers.
+The fifth component should always exist, even if
+the event does not have a natural destination;
+if there is no value
+from the protocol to put in this component, initialize it to zero.
+<!-- .NT -->
+There is an implementation limit such that your host event
+structure size cannot be bigger than the size of the
+<structname>XEvent</structname>
+union of structures.
+There also is no way to guarantee that more than 24 elements or 96 characters
+in the structure will be fully portable between machines.
+<!-- .NE -->
+<indexterm significance="preferred"><primary>XESetWireToEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetwiretoevent'>
+<funcprototype>
+  <funcdef>int *<function>XESetWireToEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> event_number</parameter></paramdef>
+  <paramdef>Status<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event code.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when converting an event.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetWireToEvent</function>
+function defines a procedure to be called when an event
+needs to be converted from wire format 
+(<structname>xEvent</structname>)
+to host format 
+(<structname>XEvent</structname>).
+The event number defines which protocol event number to install a
+conversion procedure for.
+<function>XESetWireToEvent</function>
+returns any previously defined procedure.
+<!-- .NT -->
+You can replace a core event conversion function with one
+of your own, although this is not encouraged.
+It would, however, allow you to intercept a core event 
+and modify it before being placed in the queue or otherwise examined.
+<!-- .NE -->
+When Xlib needs to convert an event from wire format to host
+format, your procedure is called with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>XEvent *<parameter>re</parameter></paramdef>
+  <paramdef>xEvent *<parameter>event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .LP -->
+<!-- .eM -->
+Your procedure must return status to indicate if the conversion succeeded.
+The re argument is a pointer to where the host format event should be stored,
+and the event argument is the 32-byte wire event structure.
+In the 
+<structname>XEvent</structname>
+structure you are creating, 
+you must fill in the five required members of the event structure.
+You should fill in the type member with the type specified for the 
+<structname>xEvent</structname>
+structure.
+You should copy all other members from the 
+<structname>xEvent</structname>
+structure (wire format) to the
+<structname>XEvent</structname>
+structure (host format).
+Your conversion procedure should return 
+<symbol>True</symbol>
+if the event should be placed in the queue or
+<symbol>False</symbol>
+if it should not be placed in the queue.
+</para>
+<para>
+<!-- .LP -->
+To initialize the serial number component of the event, call
+<function>_XSetLastRequestRead</function>
+with the event and use the return value.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>_XSetLastRequestRead</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetlastrequestread'>
+<funcprototype>
+  <funcdef>unsigned long<function>_XSetLastRequestRead</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>xGenericReply<parameter> *rep</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rep</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the wire event structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XSetLastRequestRead</function>
+function computes and returns a complete serial number from the partial
+serial number in the event.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XESetEventToWire</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xeseteventtowire'>
+<funcprototype>
+  <funcdef>Status *<function>XESetEventToWire</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> event_number</parameter></paramdef>
+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event code.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when converting an event.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetEventToWire</function>
+function defines a procedure to be called when an event
+needs to be converted from host format
+(<structname>XEvent</structname>)
+to wire format
+(<structname>xEvent</structname>)
+form.  
+The event number defines which protocol event number to install a
+conversion procedure for.
+<function>XESetEventToWire</function>
+returns any previously defined procedure.
+It returns zero if the conversion fails or nonzero otherwise.
+<!-- .NT -->
+You can replace a core event conversion function with one
+of your own, although this is not encouraged.  
+It would, however, allow you to intercept a core event 
+and modify it before being sent to another client.
+<!-- .NE -->
+When Xlib needs to convert an event from host format to wire format, 
+your procedure is called with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>XEvent *<parameter>re</parameter></paramdef>
+  <paramdef>xEvent *<parameter>event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .LP -->
+<!-- .eM -->
+The re argument is a pointer to the host format event,
+and the event argument is a pointer to where the 32-byte wire event 
+structure should be stored.
+You should fill in the type with the type from the 
+<structname>XEvent</structname>
+structure.
+All other members then should be copied from the host format to the 
+<structname>xEvent</structname>
+structure.
+<indexterm significance="preferred"><primary>XESetWireToError</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetwiretoerror'>
+<funcprototype>
+  <funcdef>Bool *<function>XESetWireToError</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> error_number</parameter></paramdef>
+  <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>error_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the error code.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when an error is received.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetWireToError</function>
+function defines a procedure to be called when an extension
+error needs to be converted from wire format to host format.
+The error number defines which protocol error code to install
+the conversion procedure for.
+<function>XESetWireToError</function>
+returns any previously defined procedure.
+</para>
+<para>
+<!-- .LP -->
+Use this function for extension errors that contain additional error values
+beyond those in a core X error, when multiple wire errors must be combined
+into a single Xlib error, or when it is necessary to intercept an
+X error before it is otherwise examined.
+</para>
+<para>
+<!-- .LP -->
+When Xlib needs to convert an error from wire format to host format,
+the procedure is called with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>XErrorEvent *<parameter>he</parameter></paramdef>
+  <paramdef>xError *<parameter>we</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .LP -->
+<!-- .eM -->
+The he argument is a pointer to where the host format error should be stored.
+The structure pointed at by he is guaranteed to be as large as an
+<structname>XEvent</structname>
+structure and so can be cast to a type larger than an
+<structname>XErrorEvent</structname>
+to store additional values.
+If the error is to be completely ignored by Xlib
+(for example, several protocol error structures will be combined into
+one Xlib error),
+then the function should return
+<symbol>False</symbol>;
+otherwise, it should return
+<symbol>True</symbol>.
+<indexterm significance="preferred"><primary>XESetError</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xeseterror'>
+<funcprototype>
+  <funcdef>int *<function>XESetError</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when an error is received.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Inside Xlib, there are times that you may want to suppress the
+calling of the external error handling when an error occurs.
+This allows status to be returned on a call at the cost of the call
+being synchronous (though most such functions are query operations, in any
+case, and are typically programmed to be synchronous).
+</para>
+<para>
+<!-- .LP -->
+When Xlib detects a protocol error in 
+<function>_XReply</function>,
+it calls your procedure with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>xError *<parameter>err</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+  <paramdef>int *<parameter>ret_code</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .LP -->
+<!-- .eM -->
+The err argument is a pointer to the 32-byte wire format error.
+The codes argument is a pointer to the extension codes structure.
+The ret_code argument is the return code you may want 
+<function>_XReply</function>
+returned to.
+</para>
+<para>
+<!-- .LP -->
+If your procedure returns a zero value, 
+the error is not suppressed, and 
+the client's error handler is called.
+(For further information, see section 11.8.2.)
+If your procedure returns nonzero, 
+the error is suppressed, and 
+<function>_XReply</function>
+returns the value of ret_code.
+<indexterm significance="preferred"><primary>XESetErrorString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xeseterrorstring'>
+<funcprototype>
+  <funcdef>char *<function>XESetErrorString</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>char<parameter> *(*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call to obtain an error string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetErrorText</function>
+function returns a string to the user for an error.
+<function>XESetErrorString</function>
+allows you to define a procedure to be called that
+should return a pointer to the error message.
+The following is an example.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>int <parameter>code</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+  <paramdef>char *<parameter>buffer</parameter></paramdef>
+  <paramdef>int <parameter>nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .LP -->
+<!-- .eM -->
+Your procedure is called with the error code for every error detected.
+You should copy nbytes of a null-terminated string containing the
+error message into buffer.
+<indexterm significance="preferred"><primary>XESetPrintErrorValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetprinterrorvalues'>
+<funcprototype>
+  <funcdef>void *<function>XESetPrintErrorValues</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>void<parameter> (*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when an error is printed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetPrintErrorValues</function>
+function defines a procedure to be called when an extension
+error is printed, to print the error values.
+Use this function for extension errors that contain additional error values
+beyond those in a core X error.
+It returns any previously defined procedure.
+</para>
+<para>
+<!-- .LP -->
+When Xlib needs to print an error,
+the procedure is called with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>XErrorEvent *<parameter>ev</parameter></paramdef>
+  <paramdef>void *<parameter>fp</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .LP -->
+<!-- .eM -->
+The structure pointed at by ev is guaranteed to be as large as an
+<structname>XEvent</structname>
+structure and so can be cast to a type larger than an
+<structname>XErrorEvent</structname>
+to obtain additional values set by using
+<function>XESetWireToError</function>.
+The underlying type of the fp argument is system dependent;
+on a <acronym>POSIX</acronym>-compliant system, fp should be cast to type FILE*.
+<indexterm significance="preferred"><primary>XESetFlushGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xesetflushgc'>
+<funcprototype>
+  <funcdef>int *<function>XESetFlushGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> *(*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when a GC is flushed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The procedure set by the
+<function>XESetFlushGC</function>
+function has the same interface as the procedure set by the
+<function>XESetCopyGC</function>
+function, but is called when a GC cache needs to be updated in the server.
+<indexterm significance="preferred"><primary>XESetBeforeFlush</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int *<function>XESetCopyGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> extension</parameter></paramdef>
+  <paramdef>int<parameter> *(*proc)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extension</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to call when a buffer is flushed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XESetBeforeFlush</function>
+function defines a procedure to be called when data is about to be
+sent to the server.  When data is about to be sent, your procedure is  
+called one or more times with these arguments:
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<!-- .R -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>(*<replaceable>proc</replaceable>)</function></funcdef>
+  <paramdef>Display *<parameter>display</parameter></paramdef>
+  <paramdef>XExtCodes *<parameter>codes</parameter></paramdef>
+  <paramdef>char *<parameter>data</parameter></paramdef>
+  <paramdef>long <parameter>len</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .LP -->
+<!-- .eM -->
+The data argument specifies a portion of the outgoing data buffer,
+and its length in bytes is specified by the len argument.
+Your procedure must not alter the contents of the data and must not
+do additional protocol requests to the same display.
+<!-- .SH -->
+Hooks onto Xlib Data Structures
+</para>
+<para>
+<!-- .LP -->
+Various Xlib data structures have provisions for extension procedures
+to chain extension supplied data onto a list.
+These structures are
+<structname>GC</structname>,
+<structname>Visual</structname>,
+<type>Screen</type>,
+<structname>ScreenFormat</structname>,
+<type>Display</type>,
+and 
+<structname>XFontStruct</structname>.
+Because the list pointer is always the first member in the structure, 
+a single set of procedures can be used to manipulate the data
+on these lists.
+</para>
+<para>
+<!-- .LP -->
+The following structure is used in the functions in this section
+and is defined in 
+&lt;X11/Xlib.h&gt;
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XExtData</primary></indexterm>
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<synopsis>
+typedef struct _XExtData {
+	int number;	/* number returned by XInitExtension */
+	struct _XExtData *next;	/* next item on list of data for structure */
+	int (*free_private)();	/* if defined,  called to free private */
+	XPointer private_data;	/* data private to this extension. */
+} XExtData;
+</synopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When any of the data structures listed above are freed, 
+the list is walked, and the structure's free procedure (if any) is called. 
+If free is NULL, 
+then the library frees both the data pointed to by the private_data member
+and the structure itself. 
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+<synopsis>
+union {	Display *display;
+	GC gc;
+	Visual *visual;
+	Screen *screen;
+	ScreenFormat *pixmap_format;
+	XFontStruct *font } XEDataObject;
+</synopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XEHeadOfExtensionList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xeheadofextensionlist'>
+<funcprototype>
+  <funcdef>XExtData **<function>XEHeadOfExtensionList</function></funcdef>
+  <paramdef>XEDataObject<parameter> object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>object</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the object.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XEHeadOfExtensionList</function>
+function returns a pointer to the list of extension structures attached
+to the specified object.
+In concert with 
+<function>XAddToExtensionList</function>,
+<function>XEHeadOfExtensionList</function>
+allows an extension to attach arbitrary data to any of the structures
+of types contained in
+<structname>XEDataObject</structname>.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XAddToExtensionList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xaddtoextensionlist'>
+<funcprototype>
+  <funcdef><function>XAddToExtensionList</function></funcdef>
+  <paramdef>XExtData<parameter> **structure</parameter></paramdef>
+  <paramdef>XExtData<parameter> *ext_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>structure</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ext_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension data structure to add.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The structure argument is a pointer to one of the data structures
+enumerated above.
+You must initialize ext_data-&gt;number with the extension number
+before calling this function.
+<indexterm significance="preferred"><primary>XFindOnExtensionList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfindonextensionlist'>
+<funcprototype>
+  <funcdef>XExtData *<function>XFindOnExtensionList</function></funcdef>
+  <paramdef>struct_XExtData<parameter> **structure</parameter></paramdef>
+  <paramdef>int<parameter> number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>structure</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the extension number from
+<function>XInitExtension</function>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFindOnExtensionList</function>
+function returns the first extension data structure
+for the extension numbered number.
+It is expected that an extension will add at most one extension
+data structure to any single data structure's extension data list.
+There is no way to find additional structures.
+</para>
+<para>
+<!-- .LP -->
+The 
+<function>XAllocID</function>
+macro, which allocates and returns a resource ID, is defined in 
+&lt;X11/Xlib.h&gt;.
+<indexterm significance="preferred"><primary>XAllocID</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xallocid'>
+<funcprototype>
+  <funcdef><function>XAllocID</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This macro is a call through the 
+<type>Display</type>
+structure to an internal resource ID allocator.
+It returns a resource ID that you can use when creating new resources.
+</para>
+<para>
+<!-- .LP -->
+The 
+<function>XAllocIDs</function>
+macro allocates and returns an array of resource ID.
+<indexterm significance="preferred"><primary>XAllocIDs</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xallocids'>
+<funcprototype>
+  <funcdef><function>XAllocIDs</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XID<parameter> *ids_return</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ids_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the resource IDs.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rep</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of resource IDs requested.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This macro is a call through the 
+<type>Display</type>
+structure to an internal resource ID allocator.
+It returns resource IDs to the array supplied by the caller.
+To correctly handle automatic reuse of resource IDs, you must call
+<function>XAllocIDs</function>
+when requesting multiple resource IDs.  This call might generate
+protocol requests.
+<!-- .SH -->
+GC Caching
+</para>
+<para>
+<!-- .LP -->
+GCs are cached by the library to allow merging of independent change
+requests to the same GC into single protocol requests.
+This is typically called a write-back cache.
+Any extension procedure whose behavior depends on the contents of a GC
+must flush the GC cache to make sure the server has up-to-date contents
+in its GC.
+</para>
+<para>
+<!-- .LP -->
+The 
+<function>FlushGC</function>
+macro checks the dirty bits in the library's GC structure and calls
+<function>_XFlushGCCache</function>
+if any elements have changed.
+The
+<function>FlushGC</function>
+macro is defined as follows:
+<indexterm significance="preferred"><primary>FlushGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='flushgc'>
+<funcprototype>
+  <funcdef><function>FlushGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Note that if you extend the GC to add additional resource ID components,
+you should ensure that the library stub sends the change request immediately.
+This is because a client can free a resource immediately after
+using it, so if you only stored the value in the cache without
+forcing a protocol request, the resource might be destroyed before being
+set into the GC.
+You can use the
+<function>_XFlushGCCache</function>
+procedure 
+to force the cache to be flushed.
+The
+<function>_XFlushGCCache</function>
+procedure
+is defined as follows:
+<indexterm significance="preferred"><primary>_XFlushGCCache</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='_xflushgccache'>
+<funcprototype>
+  <funcdef><function>_XFlushGCCache</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .SH -->
+Graphics Batching
+</para>
+<para>
+<!-- .LP -->
+If you extend X to add more poly graphics primitives, you may be able to
+take advantage of facilities in the library to allow back-to-back 
+single calls to be transformed into poly requests.
+This may dramatically improve performance of programs that are not
+written using poly requests. 
+A pointer to an 
+<structname>xReq</structname>,
+called last_req in the display structure, is the last request being processed.  
+By checking that the last request
+type, drawable, gc, and other options are the same as the new one
+and that there is enough space left in the buffer, you may be able
+to just extend the previous graphics request by extending the length
+field of the request and appending the data to the buffer.  
+This can improve performance by five times or more in naive programs.  
+For example, here is the source for the 
+<function>XDrawPoint</function>
+stub.
+(Writing extension stubs is discussed in the next section.)
+</para>
+<!-- .sM -->
+<!-- .nf -->
+<programlisting>
+#include &lt;X11/Xlibint.h&gt;
+
+/* precompute the maximum size of batching request allowed */
+
+static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
+
+XDrawPoint(dpy, d, gc, x, y)
+    register Display *dpy;
+    Drawable d;
+    GC gc;
+    int x, y; /* INT16 */
+{
+    xPoint *point;
+    LockDisplay(dpy);
+    FlushGC(dpy, gc);
+    {
+    register xPolyPointReq *req = (xPolyPointReq *) dpy-&gt;last_req;
+    /* if same as previous request, with same drawable, batch requests */
+    if (
+          (req-&gt;reqType == X_PolyPoint)
+       &amp;&amp; (req-&gt;drawable == d)
+       &amp;&amp; (req-&gt;gc == gc-&gt;gid)
+       &amp;&amp; (req-&gt;coordMode == CoordModeOrigin)
+       &amp;&amp; ((dpy-&gt;bufptr + sizeof (xPoint)) &lt;= dpy-&gt;bufmax)
+       &amp;&amp; (((char *)dpy-&gt;bufptr - (char *)req) &lt; size) ) {
+         point = (xPoint *) dpy-&gt;bufptr;
+         req-&gt;length += sizeof (xPoint) &gt;&gt; 2;
+         dpy-&gt;bufptr += sizeof (xPoint);
+         }
+
+    else {
+        GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
+        req-&gt;drawable = d;
+        req-&gt;gc = gc-&gt;gid;
+        req-&gt;coordMode = CoordModeOrigin;
+        point = (xPoint *) (req + 1);
+        }
+    point-&gt;x = x;
+    point-&gt;y = y;
+    }
+    UnlockDisplay(dpy);
+    SyncHandle();
+}
+</programlisting>
+<!-- .fi -->
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To keep clients from generating very long requests that may monopolize the 
+server,
+there is a symbol defined in
+&lt;X11/Xlibint.h&gt;
+of EPERBATCH on the number of requests batched.
+Most of the performance benefit occurs in the first few merged requests.
+Note that 
+<function>FlushGC</function>
+is called <emphasis remap='I'>before</emphasis> picking up the value of last_req,
+because it may modify this field.
+<!-- .SH -->
+Writing Extension Stubs
+</para>
+<para>
+<!-- .LP -->
+All X requests always contain the length of the request,
+expressed as a 16-bit quantity of 32 bits.
+This means that a single request can be no more than 256K bytes in
+length.
+Some servers may not support single requests of such a length.
+The value of dpy-&gt;max_request_size contains the maximum length as
+defined by the server implementation.
+For further information,
+see ``X Window System Protocol.''
+<!-- .SH -->
+Requests, Replies, and Xproto.h
+</para>
+<para>
+<!-- .LP -->
+The 
+&lt;X11/Xproto.h&gt;
+file contains three sets of definitions that
+are of interest to the stub implementor:  
+request names, request structures, and reply structures.
+</para>
+<para>
+<!-- .LP -->
+You need to generate a file equivalent to 
+&lt;X11/Xproto.h&gt;
+for your extension and need to include it in your stub procedure.
+Each stub procedure also must include 
+&lt;X11/Xlibint.h&gt; .
+</para>
+<para>
+<!-- .LP -->
+The identifiers are deliberately chosen in such a way that, if the
+request is called X_DoSomething, then its request structure is
+xDoSomethingReq, and its reply is xDoSomethingReply.  
+The GetReq family of macros, defined in 
+&lt;X11/Xlibint.h&gt; ,
+takes advantage of this naming scheme.
+</para>
+<para>
+<!-- .LP -->
+For each X request, 
+there is a definition in 
+&lt;X11/Xproto.h&gt;
+that looks similar to this:
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+#define X_DoSomething   42
+</programlisting>
+In your extension header file, 
+this will be a minor opcode, 
+instead of a major opcode.
+<!-- .SH -->
+Request Format
+</para>
+<para>
+<!-- .LP -->
+Every request contains an 8-bit major opcode and a 16-bit length field
+expressed in units of 4 bytes.  
+Every request consists of 4 bytes of header
+(containing the major opcode, the length field, and a data byte) followed by
+zero or more additional bytes of data. 
+The length field defines the total length of the request, including the header.
+The length field in a request must equal the minimum length required to contain 
+the request. 
+If the specified length is smaller or larger than the required length, 
+the server should generate a 
+<errorname>BadLength</errorname>
+error.
+Unused bytes in a request are not required to be zero.  
+Extensions should be designed in such a way that long protocol requests
+can be split up into smaller requests,
+if it is possible to exceed the maximum request size of the server.
+The protocol guarantees the maximum request size to be no smaller than
+4096 units (16384 bytes).
+</para>
+<para>
+<!-- .LP -->
+Major opcodes 128 through 255 are reserved for extensions.
+Extensions are intended to contain multiple requests, 
+so extension requests typically have an additional minor opcode encoded 
+in the second data byte in the request header, 
+but the placement and interpretation of this minor opcode as well as all
+other fields in extension requests are not defined by the core protocol.
+Every request is implicitly assigned a sequence number (starting with one)
+used in replies, errors, and events.
+</para>
+<para>
+<!-- .LP -->
+To help but not cure portability problems to certain machines, the
+<symbol>B16</symbol>
+and
+<symbol>B32</symbol>
+macros have been defined so that they can become bitfield specifications 
+on some machines.
+For example, on a Cray,
+these should be used for all 16-bit and 32-bit quantities, as discussed below.
+</para>
+<para>
+<!-- .LP -->
+Most protocol requests have a corresponding structure typedef in
+&lt;X11/Xproto.h&gt;,
+which looks like:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>xDoSomethingReq</primary></indexterm>
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<synopsis>
+typedef struct _DoSomethingReq {
+	CARD8 reqType;		/* X_DoSomething */
+	CARD8 someDatum;	/* used differently in different requests */
+	CARD16 length B16;	/* total # of bytes in request, divided by 4 */
+	...
+	/* request-specific data */
+	...
+} xDoSomethingReq;
+</synopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If a core protocol request has a single 32-bit argument, 
+you need not declare a request structure in your extension header file.
+Instead, such requests use the
+<structname>xResourceReq</structname>
+structure in
+&lt;X11/Xproto.h&gt;.
+This structure is used for any request whose single argument is a 
+<type>Window</type>,
+<type>Pixmap</type>,
+<type>Drawable</type>,
+<type>GContext</type>,
+<type>Font</type>,
+<type>Cursor</type>,
+<type>Colormap</type>,
+<type>Atom</type>,
+or
+<type>VisualID</type>.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>xResourceReq</primary></indexterm>
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<synopsis>
+typedef struct _ResourceReq {
+	CARD8 reqType;	/* the request type, e.g. X_DoSomething */
+	BYTE pad;	/* not used */
+	CARD16 length B16;	/* 2 (= total # of bytes in request, divided by 4) */
+	CARD32 id B32;	/* the Window, Drawable, Font, GContext, etc. */
+} xResourceReq;
+</synopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If convenient,
+you can do something similar in your extension header file. 
+</para>
+<para>
+<!-- .LP -->
+In both of these structures, 
+the reqType field identifies the type of the request (for example, 
+X_MapWindow or X_CreatePixmap).  
+The length field tells how long the request is
+in units of 4-byte longwords. 
+This length includes both the request structure itself and any
+variable-length data, such as strings or lists, that follow the
+request structure.  
+Request structures come in different sizes, 
+but all requests are padded to be multiples of four bytes long.
+</para>
+<para>
+<!-- .LP -->
+A few protocol requests take no arguments at all. 
+Instead, they use the
+<structname>xReq</structname>
+structure in
+&lt;X11/Xproto.h&gt;,
+which contains only a reqType and a length (and a pad byte).
+</para>
+<para>
+<!-- .LP  -->
+If the protocol request requires a reply, 
+then
+&lt;X11/Xproto.h&gt;
+also contains a reply structure typedef:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>xDoSomethingReply</primary></indexterm>
+<!-- .sM -->
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+<synopsis>
+typedef struct _DoSomethingReply {
+	BYTE type;	/* always X_Reply */
+	BYTE someDatum;	/* used differently in different requests */
+	CARD16 sequenceNumber B16;	/* # of requests sent so far */
+	CARD32 length B32;	/* # of additional bytes, divided by 4 */
+	...
+	/* request-specific data */
+	...
+} xDoSomethingReply;
+</synopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Most of these reply structures are 32 bytes long. 
+If there are not that many reply values, 
+then they contain a sufficient number of pad fields
+to bring them up to 32 bytes.  
+The length field is the total number of bytes in the request minus 32, 
+divided by 4.  
+This length will be nonzero only if:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The reply structure is followed by variable-length data,
+such as a list or string.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The reply structure is longer than 32 bytes.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Only 
+<systemitem>GetWindowAttributesl</systemitem>,
+<systemitem>QueryFont</systemitem>,
+<systemitem>QueryKeymap</systemitem>,
+and
+<systemitem>GetKeyboardControl</systemitem>
+have reply structures longer than 32 bytes in the core protocol.
+</para>
+<para>
+<!-- .LP -->
+A few protocol requests return replies that contain no data.  
+&lt;X11/Xproto.h&gt;
+does not define reply structures for these.
+Instead, they use the 
+<structname>xGenericReply</structname>
+structure, which contains only a type, length,
+and sequence number (and sufficient padding to make it 32 bytes long).
+<!-- .SH -->
+Starting to Write a Stub Procedure
+</para>
+<para>
+<!-- .LP -->
+An Xlib stub procedure should start like this:
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+#include "&lt;X11/Xlibint.h&gt;
+
+XDoSomething (arguments, ... )
+/* argument declarations */
+{
+
+register XDoSomethingReq *req;
+...
+</programlisting>
+If the protocol request has a reply, 
+then the variable declarations should include the reply structure for the request.
+The following is an example:
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+xDoSomethingReply rep;
+</programlisting>
+<!-- .SH -->
+Locking Data Structures
+</para>
+<para>
+<!-- .LP -->
+To lock the display structure for systems that
+want to support multithreaded access to a single display connection,
+each stub will need to lock its critical section.
+Generally, this section is the point from just before the appropriate GetReq
+call until all arguments to the call have been stored into the buffer.
+The precise instructions needed for this locking depend upon the machine
+architecture. 
+Two calls, which are generally implemented as macros, have been provided.
+<indexterm significance="preferred"><primary>LockDisplay</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='lockdisplay'>
+<funcprototype>
+  <funcdef><function>LockDisplay</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>UnlockDisplay</primary></indexterm>
+<funcsynopsis id='unlockdisplay'>
+<funcprototype>
+  <funcdef><function>UnlockDisplay</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .SH -->
+Sending the Protocol Request and Arguments
+</para>
+<para>
+<!-- .LP -->
+After the variable declarations, 
+a stub procedure should call one of four macros defined in 
+&lt;X11/Xlibint.h&gt;:
+<function>GetReq</function>,
+<function>GetReqExtra</function>,
+<function>GetResReq</function>,
+or 
+<function>GetEmptyReq</function>.
+All of these macros take, as their first argument,
+the name of the protocol request as declared in 
+&lt;X11/Xproto.h&gt;
+except with X_ removed.   
+Each one declares a 
+<type>Display</type>
+structure pointer,
+called dpy, and a pointer to a request structure, called req,
+which is of the appropriate type.
+The macro then appends the request structure to the output buffer, 
+fills in its type and length field, and sets req to point to it.
+</para>
+<para>
+<!-- .LP -->
+If the protocol request has no arguments (for instance, X_GrabServer),
+then use 
+<function>GetEmptyReq</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .R  -->
+<programlisting>
+GetEmptyReq (DoSomething, req);
+</programlisting>
+If the protocol request has a single 32-bit argument (such as a
+<type>Pixmap</type>,
+<type>Window</type>,
+<type>Drawable</type>,
+<type>Atom</type>,
+and so on),
+then use 
+<function>GetResReq</function>.
+The second argument to the macro is the 32-bit object.  
+<symbol>X_MapWindow</symbol>
+is a good example.
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+GetResReq (DoSomething, rid, req);
+</programlisting>
+The rid argument is the 
+<type>Pixmap</type>,
+<type>Window</type>,
+or other resource ID.
+</para>
+<para>
+<!-- .LP -->
+If the protocol request takes any other argument list, 
+then call 
+<function>GetReq</function>.
+After the 
+<function>GetReq</function>,
+you need to set all the other fields in the request structure,
+usually from arguments to the stub procedure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+GetReq (DoSomething, req);
+/* fill in arguments here */
+req-&gt;arg1 = arg1;
+req-&gt;arg2 = arg2;
+...
+</programlisting>
+A few stub procedures (such as 
+<function>XCreateGC</function>
+and 
+<function>XCreatePixmap</function>)
+return a resource ID to the caller but pass a resource ID as an argument
+to the protocol request.   
+Such procedures use the macro 
+<function>XAllocID</function>
+to allocate a resource ID from the range of IDs 
+that were assigned to this client when it opened the connection.
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+rid = req-&gt;rid = XAllocID();
+...
+return (rid);
+</programlisting>
+Finally, some stub procedures transmit a fixed amount of variable-length
+data after the request.  
+Typically, these procedures (such as
+<function>XMoveWindow</function>
+and 
+<function>XSetBackground</function>)
+are special cases of more general functions like 
+<function>XMoveResizeWindow</function>
+and 
+<function>XChangeGC</function>.
+These procedures use 
+<function>GetReqExtra</function>,
+which is the same as 
+<function>GetReq</function>
+except that it takes an additional argument (the number of
+extra bytes to allocate in the output buffer after the request structure).  
+This number should always be a multiple of four.
+<!-- .SH -->
+Variable Length Arguments
+</para>
+<para>
+<!-- .LP -->
+Some protocol requests take additional variable-length data that
+follow the 
+<type>xDoSomethingReq</type>
+structure.    
+The format of this data varies from request to request. 
+Some requests require a sequence of 8-bit bytes, 
+others a sequence of 16-bit or 32-bit entities, 
+and still others a sequence of structures.
+</para>
+<para>
+<!-- .LP -->
+It is necessary to add the length of any variable-length data to the
+length field of the request structure.  
+That length field is in units of 32-bit longwords.  
+If the data is a string or other sequence of 8-bit bytes, 
+then you must round the length up and shift it before adding:
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+req-&gt;length += (nbytes+3)&gt;&gt;2;
+</programlisting>
+To transmit variable-length data, use the 
+<function>Data</function>
+macros.
+If the data fits into the output buffer, 
+then this macro copies it to the buffer.  
+If it does not fit, however,
+the 
+<function>Data</function>
+macro calls 
+<function>_XSend</function>,
+which transmits first the contents of the buffer and then your data.
+The 
+<function>Data</function>
+macros take three arguments:  
+the display, a pointer to the beginning of the data, 
+and the number of bytes to be sent.
+<!-- .sM -->
+<funcsynopsis id='data'>
+<funcprototype>
+  <funcdef><function>Data</function></funcdef>
+  <paramdef><parameter> display</parameter></paramdef>
+  <paramdef>(char<parameter> *</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>Data</function>,
+<function>Data16</function>,
+and
+<function>Data32</function>
+are macros that may use their last argument
+more than once, so that argument should be a variable rather than
+an expression such as ``nitems*sizeof(item)''.  
+You should do that kind of computation in a separate statement before calling 
+them.
+Use the appropriate macro when sending byte, short, or long data.
+</para>
+<para>
+<!-- .LP -->
+If the protocol request requires a reply, 
+then call the procedure 
+<function>_XSend</function>
+instead of the 
+<function>Data</function>
+macro.  
+<function>_XSend</function>
+takes the same arguments, but because it sends your data immediately instead of 
+copying it into the output buffer (which would later be flushed
+anyway by the following call on 
+<function>_XReply</function>),
+it is faster.
+<!-- .SH -->
+Replies
+</para>
+<para>
+<!-- .LP -->
+If the protocol request has a reply, 
+then call 
+<function>_XReply</function>
+after you have finished dealing with 
+all the fixed-length and variable-length arguments.  
+<function>_XReply</function>
+flushes the output buffer and waits for an 
+<structname>xReply</structname>
+packet to arrive.  
+If any events arrive in the meantime,
+<function>_XReply</function>
+places them in the queue for later use.
+<indexterm significance="preferred"><primary>_XReply</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='_xreply'>
+<funcprototype>
+  <funcdef>Status <function>_XReply</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>xReply<parameter> *rep</parameter></paramdef>
+  <paramdef>int<parameter> extra</parameter></paramdef>
+  <paramdef>Bool<parameter> discard</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rep</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the reply structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>extra</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of 32-bit words expected after the replay.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>discard</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies if any data beyond that specified in the extra argument
+should be discarded.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XReply</function>
+function waits for a reply packet and copies its contents into the
+specified rep.  
+<function>_XReply</function>
+handles error and event packets that occur before the reply is received.
+<function>_XReply</function>
+takes four arguments:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+A 
+<type>Display</type>
+* structure
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A pointer to a reply structure (which must be cast to an 
+<structname>xReply</structname>
+*)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The number of additional 32-bit words (beyond 
+<function>sizeof( xReply</function>)
+= 32 bytes)
+in the reply structure
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A Boolean that indicates whether
+<function>_XReply</function>
+is to discard any additional bytes
+beyond those it was told to read
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Because most reply structures are 32 bytes long, 
+the third argument is usually 0.  
+The only core protocol exceptions are the replies to 
+<systemitem>GetWindowAttributesl</systemitem>,
+<systemitem>QueryFont</systemitem>,
+<systemitem>QueryKeymap</systemitem>,
+and 
+<systemitem>GetKeyboardControl</systemitem>,
+which have longer replies.
+</para>
+<para>
+<!-- .LP -->
+The last argument should be 
+<symbol>False</symbol>
+if the reply structure is followed
+by additional variable-length data (such as a list or string).  
+It should be 
+<symbol>True</symbol>
+if there is not any variable-length data.
+<!-- .NT -->
+This last argument is provided for upward-compatibility reasons
+to allow a client to communicate properly with a hypothetical later
+version of the server that sends more data than the client expected.
+For example, some later version of 
+<systemitem>GetWindowAttributesl</systemitem>
+might use a
+larger, but compatible, 
+<structname>xGetWindowAttributesReply</structname>
+that contains additional attribute data at the end.
+<!-- .NE -->
+<function>_XReply</function>
+returns 
+<symbol>True</symbol>
+if it received a reply successfully or 
+<symbol>False</symbol>
+if it received any sort of error. 
+</para>
+<para>
+<!-- .LP -->
+For a request with a reply that is not followed by variable-length
+data, you write something like:
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+_XReply(display, (xReply *)&amp;rep, 0, True);
+*ret1 = rep.ret1;
+*ret2 = rep.ret2;
+*ret3 = rep.ret3;
+...
+UnlockDisplay(dpy);
+SyncHandle();
+return (rep.ret4);
+}
+</programlisting>
+If there is variable-length data after the reply, 
+change the 
+<symbol>True</symbol>
+to 
+<symbol>False</symbol>,
+and use the appropriate
+<function>_XRead</function>
+function to read the variable-length data.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis id='_xread'>
+<funcprototype>
+  <funcdef><function>_XRead</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *data_return</parameter></paramdef>
+  <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the buffer.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes required.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XRead</function>
+function reads the specified number of bytes into data_return.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis id='_xread16'>
+<funcprototype>
+  <funcdef><function>_XRead16</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>short<parameter> *data_return</parameter></paramdef>
+  <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the buffer.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes required.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XRead16</function>
+function reads the specified number of bytes,
+unpacking them as 16-bit quantities,
+into the specified array as shorts.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis id='_xread32'>
+<funcprototype>
+  <funcdef><function>_XRead32</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>long<parameter> *data_return</parameter></paramdef>
+  <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the buffer.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes required.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XRead32</function>
+function reads the specified number of bytes,
+unpacking them as 32-bit quantities,
+into the specified array as longs.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis id='_xread16pad'>
+<funcprototype>
+  <funcdef><function>_XRead16Pad</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>short<parameter> *data_return</parameter></paramdef>
+  <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the buffer.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes required.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XRead16Pad</function>
+function reads the specified number of bytes,
+unpacking them as 16-bit quantities,
+into the specified array as shorts.
+If the number of bytes is not a multiple of four,
+<function>_XRead16Pad</function>
+reads and discards up to two additional pad bytes.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis id='_xreadpad'>
+<funcprototype>
+  <funcdef><function>_XReadPad</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *data_return</parameter></paramdef>
+  <paramdef>long<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the buffer.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes required.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>_XReadPad</function>
+function reads the specified number of bytes into data_return.
+If the number of bytes is not a multiple of four,
+<function>_XReadPad</function>
+reads and discards up to three additional pad bytes.
+</para>
+<para>
+<!-- .LP -->
+Each protocol request is a little different. 
+For further information,
+see the Xlib sources for examples.
+<!-- .SH -->
+Synchronous Calling
+</para>
+<para>
+<!-- .LP -->
+Each procedure should have a call, just before returning to the user, 
+to a macro called
+<systemitem>SyncHandle</systemitem>.
+If synchronous mode is enabled (see 
+<function>XSynchronize</function>),
+the request is sent immediately.
+The library, however, waits until any error the procedure could generate
+at the server has been handled.
+<!-- .SH -->
+Allocating and Deallocating Memory
+</para>
+<para>
+<!-- .LP -->
+To support the possible reentry of these procedures, 
+you must observe several conventions when allocating and deallocating memory,
+most often done when returning data to the user from the window
+system of a size the caller could not know in advance
+(for example, a list of fonts or a list of extensions).
+The standard C library functions on many systems
+are not protected against signals or other multithreaded uses.
+The following analogies to standard I/O library functions
+have been defined:
+</para>
+<para>
+<!-- .LP -->
+These should be used in place of any calls you would make to the normal
+C library functions.
+</para>
+<para>
+<!-- .LP -->
+If you need a single scratch buffer inside a critical section 
+(for example, to pack and unpack data to and from the wire protocol),
+the general memory allocators may be too expensive to use
+(particularly in output functions, which are performance critical).  
+The following function returns a scratch buffer for use within a
+critical section:
+<indexterm significance="preferred"><primary>_XAllocScratch</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='_xallocscratch'>
+<funcprototype>
+  <funcdef>char *<function>_XAllocScratch</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes required.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This storage must only be used inside of a critical section of your
+stub.  The returned pointer cannot be assumed valid after any call
+that might permit another thread to execute inside Xlib.  For example,
+the pointer cannot be assumed valid after any use of the
+<function>GetReq</function>
+or
+<function>Data</function>
+families of macros,
+after any use of
+<function>_XReply</function>,
+or after any use of the
+<function>_XSend</function>
+or
+<function>_XRead</function>
+families of functions.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The following function returns a scratch buffer for use across
+critical sections:
+<indexterm significance="preferred"><primary>_XAllocTemp</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='_xalloctemp'>
+<funcprototype>
+  <funcdef>char *<function>_XAllocTemp</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes required.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This storage can be used across calls that might permit another thread to
+execute inside Xlib.  The storage must be explicitly returned to Xlib.
+The following function returns the storage:
+<indexterm significance="preferred"><primary>_XFreeTemp</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='_xfreetemp'>
+<funcprototype>
+  <funcdef>void <function>_XFreeTemp</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *buf</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buf</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the buffer to return.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size of the buffer.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+You must pass back the same pointer and size that were returned by
+<function>_XAllocTemp</function>.
+<!-- .SH -->
+Portability Considerations
+</para>
+<para>
+<!-- .LP -->
+Many machine architectures, 
+including many of the more recent <acronym>RISC</acronym> architectures,
+do not correctly access data at unaligned locations; 
+their compilers pad out structures to preserve this characteristic.
+Many other machines capable of unaligned references pad inside of structures
+as well to preserve alignment, because accessing aligned data is
+usually much faster.
+Because the library and the server use structures to access data at
+arbitrary points in a byte stream,
+all data in request and reply packets <emphasis remap='I'>must</emphasis> be naturally aligned;
+that is, 16-bit data starts on 16-bit boundaries in the request
+and 32-bit data on 32-bit boundaries.
+All requests <emphasis remap='I'>must</emphasis> be a multiple of 32 bits in length to preserve
+the natural alignment in the data stream.
+You must pad structures out to 32-bit boundaries.
+Pad information does not have to be zeroed unless you want to
+preserve such fields for future use in your protocol requests.
+Floating point varies radically between machines and should be
+avoided completely if at all possible.
+</para>
+<para>
+<!-- .LP -->
+This code may run on machines with 16-bit ints.  
+So, if any integer argument, variable, or return value either can take 
+only nonnegative values or is declared as a
+<type>CARD16</type>
+in the protocol, be sure to declare it as
+<type>unsigned</type>
+<type>int</type>
+and not as
+<type>int</type>.
+(This, of course, does not apply to Booleans or enumerations.)
+</para>
+<para>
+<!-- .LP -->
+Similarly, 
+if any integer argument or return value is declared
+<type>CARD32</type>
+in the protocol, 
+declare it as an
+<type>unsigned</type>
+<type>long</type>
+and not as
+<type>int</type>
+or
+<type>long</type>.
+This also goes for any internal variables that may
+take on values larger than the maximum 16-bit
+<type>unsigned</type>
+<type>int</type>.
+</para>
+<para>
+<!-- .LP -->
+The library currently assumes that a
+<type>char</type>
+is 8 bits, a
+<type>short</type>
+is 16 bits, an
+<type>int</type>
+is 16 or 32 bits, and a
+<type>long</type>
+is 32 bits.  
+The 
+<function>PackData</function>
+macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. 
+However, much more work is needed to make this work properly.
+<!-- .SH -->
+Deriving the Correct Extension Opcode
+</para>
+<para>
+<!-- .LP -->
+The remaining problem a writer of an extension stub procedure faces that
+the core protocol does not face is to map from the call to the proper
+major and minor opcodes.  
+While there are a number of strategies, 
+the simplest and fastest is outlined below.
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Declare an array of pointers, _NFILE long (this is normally found
+in 
+&lt;stdio.h&gt;
+and is the number of file descriptors supported on the system)
+of type 
+<structname>XExtCodes</structname>.
+Make sure these are all initialized to NULL.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+When your stub is entered, your initialization test is just to use
+the display pointer passed in to access the file descriptor and an index
+into the array.  
+If the entry is NULL, then this is the first time you
+are entering the procedure for this display.  
+Call your initialization procedure and pass to it the display pointer.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Once in your initialization procedure, call 
+<function>XInitExtension</function>;
+if it succeeds, store the pointer returned into this array.  
+Make sure to establish a close display handler to allow you to zero the entry.
+Do whatever other initialization your extension requires.
+(For example, install event handlers and so on.)
+Your initialization procedure would normally return a pointer to the
+<structname>XExtCodes</structname>
+structure for this extension, which is what would normally
+be found in your array of pointers.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+After returning from your initialization procedure, 
+the stub can now continue normally, because it has its major opcode safely 
+in its hand in the 
+<structname>XExtCodes</structname>
+structure.
+<!-- .bp -->
+    </para>
+  </listitem>
+</itemizedlist>
+</appendix>
diff --git a/libX11/specs/libX11/AppD.xml b/libX11/specs/libX11/AppD.xml
index 0d060069e..afe65907d 100644
--- a/libX11/specs/libX11/AppD.xml
+++ b/libX11/specs/libX11/AppD.xml
@@ -1,1889 +1,1889 @@
-<?xml version="1.0" encoding="UTF-8" ?>

-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"

-	  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

-<appendix id="compatibility_functions">

-<title>Compatibility Functions</title>

-<para>

-The X Version 11 and X Version 10 functions discussed in this appendix 

-are obsolete, have been superseded by newer X Version 11 functions,

-and are maintained for compatibility reasons only.

-</para>

-<sect1 id="X_Version_11_Compatibility_Functions">

-<title>X Version 11 Compatibility Functions</title>

-<para>

-You can use the X Version 11 compatibility functions to:

-<itemizedlist>

-  <listitem>

-    <para>

-Set standard properties 

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and get window sizing hints 

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and get an

-<structname>XStandardColormap</structname>

-structure 

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Parse window geometry

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Get X environment defaults

-    </para>

-  </listitem>

-</itemizedlist>

-</para>

-<sect2 id="Setting_Standard_Properties">

-<title>Setting Standard Properties</title>

-<para>

-To specify a minimum set of properties describing the simplest application,

-use

-<function>XSetStandardProperties</function>.

-This function has been superseded by

-<function>XSetWMProperties</function>

-and sets all or portions of the 

-<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_COMMAND</property>, 

-and <property>WM_NORMAL_HINTS</property> properties.

-<indexterm significance="preferred"><primary>XSetStandardProperties</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetStandardProperties</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>char<parameter> *window_name</parameter></paramdef>

-  <paramdef>char<parameter> *icon_name</parameter></paramdef>

-  <paramdef>Pixmap<parameter> icon_pixmap</parameter></paramdef>

-  <paramdef>char<parameter> **argv</parameter></paramdef>

-  <paramdef>int<parameter> argc</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>window_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window name,

-which should be a null-terminated string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>icon_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the icon name,

-which should be a null-terminated string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>icon_pixmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the bitmap that is to be used for the icon or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argv</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the application's argument list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of arguments.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the size hints for the window in its normal state.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetStandardProperties</function>

-function provides a means by which simple applications set the

-most essential properties with a single call.

-<function>XSetStandardProperties</function>

-should be used to give a window manager some information about 

-your program's preferences. 

-It should not be used by applications that need

-to communicate more information than is possible with

-<function>XSetStandardProperties</function>.

-(Typically, argv is the argv array of your main program.)

-If the strings are not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetStandardProperties</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Setting_and_Getting_Window_Sizing_Hints">

-<title>Setting and Getting Window Sizing Hints</title>

-<para>

-Xlib provides functions that you can use to set or get window sizing hints.

-The functions discussed in this section use the flags and the

-<structname>XSizeHints</structname>

-structure, as defined in the

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-header file and use the <property>WM_NORMAL_HINTS</property> property.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the size hints for a given window in its normal state, use

-<function>XSetNormalHints</function>.

-This function has been superseded by

-<function>XSetWMNormalHints</function>.

-<indexterm significance="preferred"><primary>XSetNormalHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetNormalHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the size hints for the window in its normal state.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetNormalHints</function>

-function sets the size hints structure for the specified window.

-Applications use

-<function>XSetNormalHints</function>

-to inform the window manager of the size

-or position desirable for that window.

-In addition, 

-an application that wants to move or resize itself should call

-<function>XSetNormalHints</function>

-and specify its new desired location and size

-as well as making direct Xlib calls to move or resize.  

-This is because window managers may ignore redirected

-configure requests, but they pay attention to property changes.

-</para>

-<para>

-<!-- .LP -->

-To set size hints, 

-an application not only must assign values to the appropriate members

-in the hints structure but also must set the flags member of the structure 

-to indicate which information is present and where it came from.  

-A call to

-<function>XSetNormalHints</function>

-is meaningless, unless the flags member is set to indicate which members of

-the structure have been assigned values.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetNormalHints</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return the size hints for a window in its normal state, use

-<function>XGetNormalHints</function>.

-This function has been superseded by

-<function>XGetWMNormalHints</function>.

-<indexterm significance="preferred"><primary>XGetNormalHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetNormalHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the size hints for the window in its normal state.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetNormalHints</function>

-function returns the size hints for a window in its normal state.

-It returns a nonzero status if it succeeds or zero if

-the application specified no normal size hints for this window.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetNormalHints</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-The next two functions set and read the <property>WM_ZOOM_HINTS</property> property.

-</para>

-<para>

-<!-- .LP -->

-To set the zoom hints for a window, use

-<function>XSetZoomHints</function>.

-This function is no longer supported by the

-<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

-<indexterm significance="preferred"><primary>XSetZoomHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetZoomHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *zhints</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>zhints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the zoom hints.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Many window managers think of windows in one of three states:

-iconic, normal, or zoomed.

-The

-<function>XSetZoomHints</function>

-function provides the window manager with information for the window in the

-zoomed state.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetZoomHints</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To read the zoom hints for a window, use

-<function>XGetZoomHints</function>.

-This function is no longer supported by the

-<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

-<indexterm significance="preferred"><primary>XGetZoomHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetZoomHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *zhints_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>zhints_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the zoom hints.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetZoomHints</function>

-function returns the size hints for a window in its zoomed state.

-It returns a nonzero status if it succeeds or zero if

-the application specified no zoom size hints for this window.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetZoomHints</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the value of any property of type <property>WM_SIZE_HINTS</property>, use

-<function>XSetSizeHints</function>.

-This function has been superseded by

-<function>XSetWMSizeHints</function>.

-<indexterm significance="preferred"><primary>XSetSizeHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetSizeHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the size hints.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetSizeHints</function>

-function sets the

-<structname>XSizeHints</structname>

-structure for the named property and the specified window.

-This is used by

-<function>XSetNormalHints</function>

-and

-<function>XSetZoomHints</function>

-and can be used to set the value of any property of type <property>WM_SIZE_HINTS</property>.

-Thus, it may be useful if other properties of that type get defined.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetSizeHints</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadAtom</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To read the value of any property of type <property>WM_SIZE_HINTS</property>, use

-<function>XGetSizeHints</function>.

-This function has been superseded by

-<function>XGetWMSizeHints</function>.

-<indexterm significance="preferred"><primary>XGetSizeHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetSizeHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the size hints.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetSizeHints</function>

-function returns the

-<structname>XSizeHints</structname>

-structure for the named property and the specified window.

-This is used by

-<function>XGetNormalHints</function>

-and

-<function>XGetZoomHints</function>.

-It also can be used to retrieve the value of any property of type

-<property>WM_SIZE_HINTS</property>.

-Thus, it may be useful if other properties of that type get defined.

-<function>XGetSizeHints</function>

-returns a nonzero status if a size hint was defined

-or zero otherwise.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetSizeHints</function>

-can generate

-<errorname>BadAtom</errorname>

-and 

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Getting_and_Setting_an_XStandardColormap_Structure">

-<title>Getting and Setting an XStandardColormap Structure</title>

-<para>

-To get the 

-<structname>XStandardColormap</structname>

-structure associated with one of the described atoms, use

-<function>XGetStandardColormap</function>.

-This function has been superseded by

-<function>XGetRGBColormaps</function>.

-<indexterm significance="preferred"><primary>XGetStandardColormap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetStandardColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XStandardColormap<parameter> *colormap_return</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the colormap associated with the specified atom.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetStandardColormap</function>

-function returns the colormap definition associated with the atom supplied

-as the property argument.

-<function>XGetStandardColormap</function>

-returns a nonzero status if successful and zero otherwise.

-For example,

-to fetch the standard

-<symbol>GrayScale</symbol>

-colormap for a display,

-you use

-<function>XGetStandardColormap</function>

-with the following syntax:

-<programlisting>

-XGetStandardColormap(dpy, DefaultRootWindow(dpy), &amp;cmap, XA_RGB_GRAY_MAP);

-</programlisting>

-See section 14.3 for the semantics of standard colormaps.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetStandardColormap</function>

-can generate

-<errorname>BadAtom</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set a standard colormap, use

-<function>XSetStandardColormap</function>.

-This function has been superseded by

-<function>XSetRGBColormaps</function>.

-<indexterm significance="preferred"><primary>XSetStandardColormap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetStandardColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XStandardColormap<parameter> *colormap</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetStandardColormap</function>

-function usually is only used by window or session managers.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetStandardColormap</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadAtom</errorname>,

-<errorname>BadDrawable</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Parsing_Window_Geometry">

-<title>Parsing Window Geometry</title>

-<para>

-To parse window geometry given a user-specified position 

-and a default position, use

-<function>XGeometry</function>.

-This function has been superseded by

-<function>XWMGeometry</function>.

-<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGeometry</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XGeometry</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> screen</parameter></paramdef>

-  <paramdef>char*position,<parameter> *default_position</parameter></paramdef>

-  <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>

-  <paramdef>unsignedintfwidth,<parameter> fheight</parameter></paramdef>

-  <paramdef>intxadder,<parameter> yadder</parameter></paramdef>

-  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>

-  <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>position</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>default_position</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the geometry specifications.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bwidth</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the border width.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>fheight</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>fwidth</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the font height and width in pixels (increment size).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>xadder</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>yadder</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify additional interior padding needed in the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the x and y offsets.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the width and height determined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-You pass in the border width (bwidth),

-size of the increments fwidth and fheight

-(typically font width and height),

-and any additional interior space (xadder and yadder)

-to make it easy to compute the resulting size.

-The

-<function>XGeometry</function>

-function returns the position the window should be placed given a position and

-a default position.

-<function>XGeometry</function>

-determines the placement of

-a window using a geometry specification as specified by

-<function>XParseGeometry</function>

-and the additional information about the window.

-Given a fully qualified default geometry specification and

-an incomplete geometry specification, 

-<function>XParseGeometry</function>

-returns a bitmask value as defined above in the 

-<function>XParseGeometry</function>

-call,

-by using the position argument.

-</para>

-<para>

-<!-- .LP -->

-The returned width and height will be the width and height specified

-by default_position as overridden by any user-specified position.

-They are not affected by fwidth, fheight, xadder, or yadder.

-The x and y coordinates are computed by using the border width,

-the screen width and height, padding as specified by xadder and yadder,

-and the fheight and fwidth times the width and height from the

-geometry specifications.

-</para>

-</sect2>

-<sect2 id="Getting_the_X_Environment_Defaults">

-<title>Getting the X Environment Defaults</title>

-<para>

-The

-<function>XGetDefault</function>

-function provides a primitive interface to the resource manager facilities 

-discussed in chapter 15. <!-- xref -->

-It is only useful in very simple applications.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-<indexterm significance="preferred"><primary>XGetDefault</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XGetDefault</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *program</parameter></paramdef>

-  <paramdef>char<parameter> *option</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>program</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the program name for the Xlib defaults (usually argv[0] 

-of the main program).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>option</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the option name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetDefault</function>

-function returns the value of the resource <emphasis remap='I'>prog</emphasis>.<emphasis remap='I'>option</emphasis>,

-where <emphasis remap='I'>prog</emphasis> is the program argument with the directory prefix removed

-and <emphasis remap='I'>option</emphasis> must be a single component.

-Note that multilevel resources cannot be used with

-<function>XGetDefault</function>.

-The class "Program.Name" is always used for the resource lookup.

-If the specified option name does not exist for this program,

-<function>XGetDefault</function>

-returns NULL.

-The strings returned by

-<function>XGetDefault</function>

-are owned by Xlib and should not be modified or freed by the client.

-</para>

-<para>

-<!-- .LP -->

-If a database has been set with 

-<function>XrmSetDatabase</function>,

-that database is used for the lookup.

-Otherwise, a database is created

-and is set in the display (as if by calling 

-<function>XrmSetDatabase</function>).

-The database is created in the current locale.

-To create a database,

-<function>XGetDefault</function>

-uses resources from the RESOURCE_MANAGER property on the root

-window of screen zero.

-If no such property exists,

-a resource file in the user's home directory is used.

-On a <acronym>POSIX</acronym>-conformant system,

-this file is

-<function>"$HOME/.Xdefaults"</function>.

-<indexterm><primary>Files</primary><secondary><filename>$HOME/.Xdefaults</filename></secondary></indexterm>

-After loading these defaults,

-<function>XGetDefault</function>

-merges additional defaults specified by the XENVIRONMENT

-environment variable.

-If XENVIRONMENT is defined,

-it contains a full path name for the additional resource file.

-If XENVIRONMENT is not defined,

-<function>XGetDefault</function>

-looks for

-"<filename>$HOME/.Xdefaults-<replaceable>name</replaceable></filename>" ,

-where <replaceable>name</replaceable> specifies the name of the machine on which the application

-is running.

-</para>

-</sect2>

-</sect1>

-<sect1 id="X_Version_10_Compatibility_Functions">

-<title>X Version 10 Compatibility Functions</title>

-<para>

-You can use the X Version 10 compatibility functions to:

-<itemizedlist>

-  <listitem>

-    <para>

-Draw and fill polygons and curves

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Associate user data with a value

-    </para>

-  </listitem>

-</itemizedlist>

-</para>

-<sect2 id="Drawing_and_Filling_Polygons_and_Curves">

-<title>Drawing and Filling Polygons and Curves</title>

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to draw or fill

-arbitrary polygons or curves.  

-These functions are provided mainly for compatibility with X Version 10 

-and have no server support.  

-That is, they call other Xlib functions, not the server directly.  

-Thus, if you just have straight lines to draw, using 

-<function>XDrawLines</function>

-<indexterm><primary>XDrawLines</primary></indexterm>

-or

-<function>XDrawSegments</function>

-<indexterm><primary>XDrawSegments</primary></indexterm>

-is much faster.

-</para>

-<para>

-<!-- .LP -->

-The functions discussed here provide all the functionality of the 

-X Version 10 functions 

-<function>XDraw</function>,

-<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>

-<function>XDrawFilled</function>,

-<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>

-<function>XDrawPatterned</function>,

-<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>

-<function>XDrawDashed</function>,

-<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>

-and

-<function>XDrawTiled</function>.

-<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>

-They are as compatible as possible given X Version 11's new line-drawing 

-functions.  

-One thing to note, however, is that

-<function>VertexDrawLastPoint</function>

-is no longer supported. 

-Also, the error status returned is the opposite of what it was under 

-X Version 10 (this is the X Version 11 standard error status).  

-<function>XAppendVertex</function>

-and 

-<function>XClearVertexFlag</function>

-from X Version 10 also are not supported.

-</para>

-<para>

-<!-- .LP -->

-Just how the graphics context you use is set up actually

-determines whether you get dashes or not, and so on.  

-Lines are properly joined if they connect and include

-the closing of a closed figure  (see 

-<function>XDrawLines</function>).

-The functions discussed here fail (return zero) only if they run out of memory

-or are passed a 

-<structname>Vertex</structname>

-list that has a 

-<structname>Vertex</structname>

-with 

-<symbol>VertexStartClosed</symbol>

-set that is not followed by a 

-<structname>Vertex</structname>

-with 

-<symbol>VertexEndClosed</symbol>

-set.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To achieve the effects of the X Version 10

-<function>XDraw</function>,

-<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>

-<function>XDrawDashed</function>,

-<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>

-and 

-<function>XDrawPatterned</function>,

-<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>

-use

-<function>XDraw</function>.

-</para>

-

-<para>

-#include &lt;X11/X10.h&gt;

-</para>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XDraw</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>Vertex<parameter> *vlist</parameter></paramdef>

-  <paramdef>int<parameter> vcount</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>vlist</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the list of vertices that indicate what to draw.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>vcount</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies how many vertices are in vlist.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDraw</function>

-function draws an arbitrary polygon or curve.  

-The figure drawn is defined by the specified list of vertices (vlist).

-The points are connected by lines as specified in the flags in the

-vertex structure.

-</para>

-<para>

-<!-- .LP -->

-Each Vertex, as defined in

-<filename class="headerfile">&lt;X11/X10.h&gt;</filename>,

-<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X10.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X10.h&gt;</filename></secondary></indexterm>

-is a structure with the following members:

-<indexterm significance="preferred"><primary>Vertex</primary></indexterm>

-<synopsis>

-typedef struct _Vertex {

-	short x,y;

-	unsigned short flags;

-} Vertex;

-</synopsis>

-The x and y members are the coordinates of the vertex 

-that are relative to either the upper left inside corner of the drawable 

-(if 

-<symbol>VertexRelative</symbol>

-is zero) or the previous vertex (if 

-<symbol>VertexRelative</symbol>

-is one).

-</para>

-<para>

-<!-- .LP -->

-The flags, as defined in 

-<filename class="headerfile">&lt;X11/X10.h&gt;</filename>,

-<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X10.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X10.h&gt;</filename></secondary></indexterm>

-are as follows:

-<indexterm significance="preferred"><primary>VertexRelative</primary></indexterm>

-<indexterm significance="preferred"><primary>VertexDontDraw</primary></indexterm>

-<indexterm significance="preferred"><primary>VertexCurved</primary></indexterm>

-<indexterm significance="preferred"><primary>VertexStartClosed</primary></indexterm>

-<indexterm significance="preferred"><primary>VertexEndClosed</primary></indexterm>

-<!-- .sM -->

-

-<synopsis>

-VertexRelative     0x0001     /* else absolute */

-VertexDontDraw     0x0002     /* else draw */

-VertexCurved       0x0004     /* else straight */

-VertexStartClosed  0x0008     /* else not */

-VertexEndClosed    0x0010     /* else not */

-</synopsis>

-

-<itemizedlist>

-  <listitem>

-    <para>

-If 

-<symbol>VertexRelative</symbol>

-is not set,  

-the coordinates are absolute (that is, relative to the drawable's origin).  

-The first vertex must be an absolute vertex.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If

-<symbol>VertexDontDraw</symbol>

-is one, 

-no line or curve is drawn from the previous vertex to this one.  

-This is analogous to picking up the pen and moving to another place 

-before drawing another line.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If 

-<symbol>VertexCurved</symbol>

-is one, 

-a spline algorithm is used to draw a smooth curve from the previous vertex

-through this one to the next vertex.  

-Otherwise, a straight line is drawn from the previous vertex to this one.  

-It makes sense to set 

-<symbol>VertexCurved</symbol>

-to one only if a previous and next vertex are both defined

-(either explicitly in the array or through the definition of a closed 

-curve).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-It is permissible for 

-<symbol>VertexDontDraw</symbol>

-bits and 

-<symbol>VertexCurved</symbol>

-bits both to be one. 

-This is useful if you want to define the previous point for the smooth curve

-but do not want an actual curve drawing to start until this point.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If 

-<symbol>VertexStartClosed</symbol>

-is one, 

-then this point marks the beginning of a closed curve.  

-This vertex must be followed later in the array by another vertex 

-whose effective coordinates are identical

-and that has a

-<symbol>VertexEndClosed</symbol>

-bit of one.

-The points in between form a cycle to determine predecessor 

-and successor vertices for the spline algorithm.

-    </para>

-  </listitem>

-</itemizedlist>

-</para>

-<para>

-<!-- .LP -->

-This function uses these GC components:

-function, plane-mask, line-width, line-style, cap-style, join-style,

-fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and

-clip-mask.

-It also uses these GC mode-dependent components: 

-foreground, background, tile, stipple,

-tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To achieve the effects of the X Version 10

-<function>XDrawTiled</function>

-<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>

-and 

-<function>XDrawFilled</function>,

-<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>

-use

-<function>XDrawFilled</function>.

-</para>

-

-<para>#include &lt;X11/X10.h&gt;</para>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XDrawFilled</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>Vertex<parameter> *vlist</parameter></paramdef>

-  <paramdef>int<parameter> vcount</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>vlist</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the list of vertices that indicate what to draw.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>vcount</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies how many vertices are in vlist.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDrawFilled</function>

-function draws arbitrary polygons or curves and then fills them.

-</para>

-<para>

-<!-- .LP -->

-This function uses these GC components:

-function, plane-mask, line-width, line-style, cap-style, join-style,

-fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and

-clip-mask.

-It also uses these GC mode-dependent components: 

-foreground, background, tile, stipple,

-tile-stipple-x-origin, tile-stipple-y-origin, 

-dash-offset, dash-list, fill-style, and fill-rule.

-</para>

-</sect2>

-<sect2 id="Associating_User_Data_with_a_Value">

-<title>Associating User Data with a Value</title>

-<para>

-<!-- .LP -->

-These functions have been superseded by the context management functions

-(see section 16.10). 

-It is often necessary to associate arbitrary information with resource IDs.

-Xlib provides the 

-<function>XAssocTable</function>

-functions that you can use to make such an association.

-<indexterm><primary>Hash Lookup</primary></indexterm>

-<indexterm><primary>Window</primary><secondary>IDs</secondary></indexterm>

-<indexterm><primary>Resource IDs</primary></indexterm>

-Application programs often need to be able to easily refer to

-their own data structures when an event arrives.

-The 

-<function>XAssocTable</function>

-system provides users of the X library with a method

-for associating their own data structures with X resources

-(<type>Pixmap</type>s,

-<type>Font</type>s,

-<type>Window</type>s,

-and so on).

-</para>

-<para>

-<!-- .LP -->

-An 

-<function>XAssocTable</function>

-can be used to type X resources.  

-For example, the user

-may want to have three or four types of windows,

-each with different properties. 

-This can be accomplished by associating each X window ID

-with a pointer to a window property data structure  defined  by  the

-user.

-A generic type has been defined in the X library for resource IDs.

-It is called an XID.

-</para>

-<para>

-<!-- .LP -->

-There are a few  guidelines  that  should be observed when using an

-<function>XAssocTable</function> :

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-All  XIDs  are  relative  to  the  specified display.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Because  of  the  hashing  scheme  used  by  the  association mechanism,

-the following rules for determining the size of a

-<function>XAssocTable</function>

-should be followed.  

-Associations will be  made  and  looked  up  more

-efficiently  if  the  table  size  (number  of  buckets in the hashing

-system) is a power of two and if there are not more than 8 XIDs  per

-bucket.

-    </para>

-  </listitem>

-</itemizedlist>

-

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return a pointer to a new

-<function>XAssocTable</function>,

-use 

-<function>XCreateAssocTable</function>.

-<indexterm significance="preferred"><primary>XCreateAssocTable</primary></indexterm>

-<!-- .sM -->

-</para>

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XAssocTable *<function>XCreateAssocTable</function></funcdef>

-  <paramdef>int<parameter> size</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>size</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of buckets in the hash system of

-<function>XAssocTable</function>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The size argument specifies the number of buckets in the 

-hash system of

-<function>XAssocTable</function>.

-For  reasons  of  efficiency  the number of buckets

-should be a power of two.

-Some size  suggestions  might  be:  use  32 buckets  per  100  objects,

-and a reasonable maximum number of objects per buckets is 8.

-If  an  error  allocating  memory  for  the

-<function>XAssocTable</function>

-occurs, 

-a NULL pointer is returned. 

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create an entry in a given 

-<function>XAssocTable</function>,

-use 

-<function>XMakeAssoc</function>.

-<indexterm significance="preferred"><primary>XMakeAssoc</primary></indexterm>

-<!-- .sM -->

-</para>

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XMakeAssoc</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>

-  <paramdef>XID<parameter> x_id</parameter></paramdef>

-  <paramdef>char<parameter> *data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>table</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the assoc table. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_id</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the X resource ID.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the data to be associated with the X resource ID.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMakeAssoc</function>

-function inserts data into an 

-<function>XAssocTable</function>

-keyed on an XID.

-Data is inserted into the table only once.

-Redundant inserts are ignored.

-The queue in each association bucket is sorted from the lowest XID to 

-the highest XID.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain data from a given 

-<function>XAssocTable</function>,

-use 

-<function>XLookUpAssoc</function>.

-<indexterm significance="preferred"><primary>XLookUpAssoc</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XLookUpAssoc</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>

-  <paramdef>XID<parameter> x_id</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>table</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the assoc table. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_id</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the X resource ID.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLookUpAssoc</function>

-function retrieves the data stored in an 

-<function>XAssocTable</function>

-by its XID.  

-If  an appropriately  matching XID can be found in the table,

-<function>XLookUpAssoc</function>

-returns the data associated with it.

-If the x_id cannot be found in the table,

-it returns NULL.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To delete an entry from a given 

-<function>XAssocTable</function>,

-use 

-<function>XDeleteAssoc</function>.

-<indexterm significance="preferred"><primary>XDeleteAssoc</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDeleteAssoc</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>

-  <paramdef>XID<parameter> x_id</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>table</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the assoc table. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_id</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the X resource ID.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDeleteAssoc</function>

-function deletes an association in an 

-<function>XAssocTable</function>

-keyed on its XID.

-Redundant deletes (and deletes of nonexistent XIDs) are ignored.

-Deleting associations in no way impairs the performance of an

-<function>XAssocTable</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To free the memory associated with a given 

-<function>XAssocTable</function>,

-use 

-<function>XDestroyAssocTable</function>.

-</para>

-<indexterm significance="preferred"><primary>XDestroyAssocTable</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDestroyAssocTable</function></funcdef>

-  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>table</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the assoc table. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</sect2>

-</sect1>

-</appendix>

+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+	  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<appendix id="compatibility_functions">
+<title>Compatibility Functions</title>
+<para>
+The X Version 11 and X Version 10 functions discussed in this appendix 
+are obsolete, have been superseded by newer X Version 11 functions,
+and are maintained for compatibility reasons only.
+</para>
+<sect1 id="X_Version_11_Compatibility_Functions">
+<title>X Version 11 Compatibility Functions</title>
+<para>
+You can use the X Version 11 compatibility functions to:
+<itemizedlist>
+  <listitem>
+    <para>
+Set standard properties 
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and get window sizing hints 
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and get an
+<structname>XStandardColormap</structname>
+structure 
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Parse window geometry
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Get X environment defaults
+    </para>
+  </listitem>
+</itemizedlist>
+</para>
+<sect2 id="Setting_Standard_Properties">
+<title>Setting Standard Properties</title>
+<para>
+To specify a minimum set of properties describing the simplest application,
+use
+<function>XSetStandardProperties</function>.
+This function has been superseded by
+<function>XSetWMProperties</function>
+and sets all or portions of the 
+<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_COMMAND</property>, 
+and <property>WM_NORMAL_HINTS</property> properties.
+<indexterm significance="preferred"><primary>XSetStandardProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetstandardproperties'>
+<funcprototype>
+  <funcdef><function>XSetStandardProperties</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>char<parameter> *window_name</parameter></paramdef>
+  <paramdef>char<parameter> *icon_name</parameter></paramdef>
+  <paramdef>Pixmap<parameter> icon_pixmap</parameter></paramdef>
+  <paramdef>char<parameter> **argv</parameter></paramdef>
+  <paramdef>int<parameter> argc</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>window_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window name,
+which should be a null-terminated string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>icon_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the icon name,
+which should be a null-terminated string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>icon_pixmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the bitmap that is to be used for the icon or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argv</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the application's argument list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of arguments.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the size hints for the window in its normal state.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetStandardProperties</function>
+function provides a means by which simple applications set the
+most essential properties with a single call.
+<function>XSetStandardProperties</function>
+should be used to give a window manager some information about 
+your program's preferences. 
+It should not be used by applications that need
+to communicate more information than is possible with
+<function>XSetStandardProperties</function>.
+(Typically, argv is the argv array of your main program.)
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetStandardProperties</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_and_Getting_Window_Sizing_Hints">
+<title>Setting and Getting Window Sizing Hints</title>
+<para>
+Xlib provides functions that you can use to set or get window sizing hints.
+The functions discussed in this section use the flags and the
+<structname>XSizeHints</structname>
+structure, as defined in the
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+header file and use the <property>WM_NORMAL_HINTS</property> property.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the size hints for a given window in its normal state, use
+<function>XSetNormalHints</function>.
+This function has been superseded by
+<function>XSetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XSetNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetnormalhints'>
+<funcprototype>
+  <funcdef><function>XSetNormalHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the size hints for the window in its normal state.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetNormalHints</function>
+function sets the size hints structure for the specified window.
+Applications use
+<function>XSetNormalHints</function>
+to inform the window manager of the size
+or position desirable for that window.
+In addition, 
+an application that wants to move or resize itself should call
+<function>XSetNormalHints</function>
+and specify its new desired location and size
+as well as making direct Xlib calls to move or resize.  
+This is because window managers may ignore redirected
+configure requests, but they pay attention to property changes.
+</para>
+<para>
+<!-- .LP -->
+To set size hints, 
+an application not only must assign values to the appropriate members
+in the hints structure but also must set the flags member of the structure 
+to indicate which information is present and where it came from.  
+A call to
+<function>XSetNormalHints</function>
+is meaningless, unless the flags member is set to indicate which members of
+the structure have been assigned values.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetNormalHints</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the size hints for a window in its normal state, use
+<function>XGetNormalHints</function>.
+This function has been superseded by
+<function>XGetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XGetNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetnormalhints'>
+<funcprototype>
+  <funcdef>Status <function>XGetNormalHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the size hints for the window in its normal state.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetNormalHints</function>
+function returns the size hints for a window in its normal state.
+It returns a nonzero status if it succeeds or zero if
+the application specified no normal size hints for this window.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetNormalHints</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The next two functions set and read the <property>WM_ZOOM_HINTS</property> property.
+</para>
+<para>
+<!-- .LP -->
+To set the zoom hints for a window, use
+<function>XSetZoomHints</function>.
+This function is no longer supported by the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+<indexterm significance="preferred"><primary>XSetZoomHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetzoomhints'>
+<funcprototype>
+  <funcdef><function>XSetZoomHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *zhints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>zhints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the zoom hints.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Many window managers think of windows in one of three states:
+iconic, normal, or zoomed.
+The
+<function>XSetZoomHints</function>
+function provides the window manager with information for the window in the
+zoomed state.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetZoomHints</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read the zoom hints for a window, use
+<function>XGetZoomHints</function>.
+This function is no longer supported by the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+<indexterm significance="preferred"><primary>XGetZoomHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetzoomhints'>
+<funcprototype>
+  <funcdef>Status <function>XGetZoomHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *zhints_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>zhints_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the zoom hints.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetZoomHints</function>
+function returns the size hints for a window in its zoomed state.
+It returns a nonzero status if it succeeds or zero if
+the application specified no zoom size hints for this window.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetZoomHints</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the value of any property of type <property>WM_SIZE_HINTS</property>, use
+<function>XSetSizeHints</function>.
+This function has been superseded by
+<function>XSetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XSetSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetsizehints'>
+<funcprototype>
+  <funcdef><function>XSetSizeHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the size hints.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetSizeHints</function>
+function sets the
+<structname>XSizeHints</structname>
+structure for the named property and the specified window.
+This is used by
+<function>XSetNormalHints</function>
+and
+<function>XSetZoomHints</function>
+and can be used to set the value of any property of type <property>WM_SIZE_HINTS</property>.
+Thus, it may be useful if other properties of that type get defined.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetSizeHints</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadAtom</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read the value of any property of type <property>WM_SIZE_HINTS</property>, use
+<function>XGetSizeHints</function>.
+This function has been superseded by
+<function>XGetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XGetSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetsizehints'>
+<funcprototype>
+  <funcdef>Status <function>XGetSizeHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the size hints.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetSizeHints</function>
+function returns the
+<structname>XSizeHints</structname>
+structure for the named property and the specified window.
+This is used by
+<function>XGetNormalHints</function>
+and
+<function>XGetZoomHints</function>.
+It also can be used to retrieve the value of any property of type
+<property>WM_SIZE_HINTS</property>.
+Thus, it may be useful if other properties of that type get defined.
+<function>XGetSizeHints</function>
+returns a nonzero status if a size hint was defined
+or zero otherwise.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetSizeHints</function>
+can generate
+<errorname>BadAtom</errorname>
+and 
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Getting_and_Setting_an_XStandardColormap_Structure">
+<title>Getting and Setting an XStandardColormap Structure</title>
+<para>
+To get the 
+<structname>XStandardColormap</structname>
+structure associated with one of the described atoms, use
+<function>XGetStandardColormap</function>.
+This function has been superseded by
+<function>XGetRGBColormaps</function>.
+<indexterm significance="preferred"><primary>XGetStandardColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetstandardcolormap'>
+<funcprototype>
+  <funcdef>Status <function>XGetStandardColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XStandardColormap<parameter> *colormap_return</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the colormap associated with the specified atom.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetStandardColormap</function>
+function returns the colormap definition associated with the atom supplied
+as the property argument.
+<function>XGetStandardColormap</function>
+returns a nonzero status if successful and zero otherwise.
+For example,
+to fetch the standard
+<symbol>GrayScale</symbol>
+colormap for a display,
+you use
+<function>XGetStandardColormap</function>
+with the following syntax:
+<programlisting>
+XGetStandardColormap(dpy, DefaultRootWindow(dpy), &amp;cmap, XA_RGB_GRAY_MAP);
+</programlisting>
+See section 14.3 for the semantics of standard colormaps.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetStandardColormap</function>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a standard colormap, use
+<function>XSetStandardColormap</function>.
+This function has been superseded by
+<function>XSetRGBColormaps</function>.
+<indexterm significance="preferred"><primary>XSetStandardColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetstandardcolormap'>
+<funcprototype>
+  <funcdef><function>XSetStandardColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XStandardColormap<parameter> *colormap</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetStandardColormap</function>
+function usually is only used by window or session managers.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetStandardColormap</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadAtom</errorname>,
+<errorname>BadDrawable</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Parsing_Window_Geometry">
+<title>Parsing Window Geometry</title>
+<para>
+To parse window geometry given a user-specified position 
+and a default position, use
+<function>XGeometry</function>.
+This function has been superseded by
+<function>XWMGeometry</function>.
+<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGeometry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeometry'>
+<funcprototype>
+  <funcdef>int <function>XGeometry</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> screen</parameter></paramdef>
+  <paramdef>char*position,<parameter> *default_position</parameter></paramdef>
+  <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>
+  <paramdef>unsignedintfwidth,<parameter> fheight</parameter></paramdef>
+  <paramdef>intxadder,<parameter> yadder</parameter></paramdef>
+  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
+  <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>position</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>default_position</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the geometry specifications.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bwidth</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the border width.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>fheight</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>fwidth</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the font height and width in pixels (increment size).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>xadder</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>yadder</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify additional interior padding needed in the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the x and y offsets.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the width and height determined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+You pass in the border width (bwidth),
+size of the increments fwidth and fheight
+(typically font width and height),
+and any additional interior space (xadder and yadder)
+to make it easy to compute the resulting size.
+The
+<function>XGeometry</function>
+function returns the position the window should be placed given a position and
+a default position.
+<function>XGeometry</function>
+determines the placement of
+a window using a geometry specification as specified by
+<function>XParseGeometry</function>
+and the additional information about the window.
+Given a fully qualified default geometry specification and
+an incomplete geometry specification, 
+<function>XParseGeometry</function>
+returns a bitmask value as defined above in the 
+<function>XParseGeometry</function>
+call,
+by using the position argument.
+</para>
+<para>
+<!-- .LP -->
+The returned width and height will be the width and height specified
+by default_position as overridden by any user-specified position.
+They are not affected by fwidth, fheight, xadder, or yadder.
+The x and y coordinates are computed by using the border width,
+the screen width and height, padding as specified by xadder and yadder,
+and the fheight and fwidth times the width and height from the
+geometry specifications.
+</para>
+</sect2>
+<sect2 id="Getting_the_X_Environment_Defaults">
+<title>Getting the X Environment Defaults</title>
+<para>
+The
+<function>XGetDefault</function>
+function provides a primitive interface to the resource manager facilities 
+discussed in chapter 15. <!-- xref -->
+It is only useful in very simple applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XGetDefault</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetdefault'>
+<funcprototype>
+  <funcdef>char *<function>XGetDefault</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *program</parameter></paramdef>
+  <paramdef>char<parameter> *option</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>program</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the program name for the Xlib defaults (usually argv[0] 
+of the main program).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>option</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the option name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetDefault</function>
+function returns the value of the resource <emphasis remap='I'>prog</emphasis>.<emphasis remap='I'>option</emphasis>,
+where <emphasis remap='I'>prog</emphasis> is the program argument with the directory prefix removed
+and <emphasis remap='I'>option</emphasis> must be a single component.
+Note that multilevel resources cannot be used with
+<function>XGetDefault</function>.
+The class "Program.Name" is always used for the resource lookup.
+If the specified option name does not exist for this program,
+<function>XGetDefault</function>
+returns NULL.
+The strings returned by
+<function>XGetDefault</function>
+are owned by Xlib and should not be modified or freed by the client.
+</para>
+<para>
+<!-- .LP -->
+If a database has been set with 
+<function>XrmSetDatabase</function>,
+that database is used for the lookup.
+Otherwise, a database is created
+and is set in the display (as if by calling 
+<function>XrmSetDatabase</function>).
+The database is created in the current locale.
+To create a database,
+<function>XGetDefault</function>
+uses resources from the RESOURCE_MANAGER property on the root
+window of screen zero.
+If no such property exists,
+a resource file in the user's home directory is used.
+On a <acronym>POSIX</acronym>-conformant system,
+this file is
+<function>"$HOME/.Xdefaults"</function>.
+<indexterm><primary>Files</primary><secondary><filename>$HOME/.Xdefaults</filename></secondary></indexterm>
+After loading these defaults,
+<function>XGetDefault</function>
+merges additional defaults specified by the XENVIRONMENT
+environment variable.
+If XENVIRONMENT is defined,
+it contains a full path name for the additional resource file.
+If XENVIRONMENT is not defined,
+<function>XGetDefault</function>
+looks for
+"<filename>$HOME/.Xdefaults-<replaceable>name</replaceable></filename>" ,
+where <replaceable>name</replaceable> specifies the name of the machine on which the application
+is running.
+</para>
+</sect2>
+</sect1>
+<sect1 id="X_Version_10_Compatibility_Functions">
+<title>X Version 10 Compatibility Functions</title>
+<para>
+You can use the X Version 10 compatibility functions to:
+<itemizedlist>
+  <listitem>
+    <para>
+Draw and fill polygons and curves
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Associate user data with a value
+    </para>
+  </listitem>
+</itemizedlist>
+</para>
+<sect2 id="Drawing_and_Filling_Polygons_and_Curves">
+<title>Drawing and Filling Polygons and Curves</title>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to draw or fill
+arbitrary polygons or curves.  
+These functions are provided mainly for compatibility with X Version 10 
+and have no server support.  
+That is, they call other Xlib functions, not the server directly.  
+Thus, if you just have straight lines to draw, using 
+<function>XDrawLines</function>
+<indexterm><primary>XDrawLines</primary></indexterm>
+or
+<function>XDrawSegments</function>
+<indexterm><primary>XDrawSegments</primary></indexterm>
+is much faster.
+</para>
+<para>
+<!-- .LP -->
+The functions discussed here provide all the functionality of the 
+X Version 10 functions 
+<function>XDraw</function>,
+<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>
+<function>XDrawFilled</function>,
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>
+<function>XDrawPatterned</function>,
+<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>
+<function>XDrawDashed</function>,
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>
+and
+<function>XDrawTiled</function>.
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>
+They are as compatible as possible given X Version 11's new line-drawing 
+functions.  
+One thing to note, however, is that
+<function>VertexDrawLastPoint</function>
+is no longer supported. 
+Also, the error status returned is the opposite of what it was under 
+X Version 10 (this is the X Version 11 standard error status).  
+<function>XAppendVertex</function>
+and 
+<function>XClearVertexFlag</function>
+from X Version 10 also are not supported.
+</para>
+<para>
+<!-- .LP -->
+Just how the graphics context you use is set up actually
+determines whether you get dashes or not, and so on.  
+Lines are properly joined if they connect and include
+the closing of a closed figure  (see 
+<function>XDrawLines</function>).
+The functions discussed here fail (return zero) only if they run out of memory
+or are passed a 
+<structname>Vertex</structname>
+list that has a 
+<structname>Vertex</structname>
+with 
+<symbol>VertexStartClosed</symbol>
+set that is not followed by a 
+<structname>Vertex</structname>
+with 
+<symbol>VertexEndClosed</symbol>
+set.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To achieve the effects of the X Version 10
+<function>XDraw</function>,
+<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>
+<function>XDrawDashed</function>,
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>
+and 
+<function>XDrawPatterned</function>,
+<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>
+use
+<function>XDraw</function>.
+</para>
+
+<para>
+#include &lt;X11/X10.h&gt;
+</para>
+
+<funcsynopsis id='xdraw'>
+<funcprototype>
+  <funcdef>Status <function>XDraw</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>Vertex<parameter> *vlist</parameter></paramdef>
+  <paramdef>int<parameter> vcount</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>vlist</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the list of vertices that indicate what to draw.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>vcount</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies how many vertices are in vlist.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDraw</function>
+function draws an arbitrary polygon or curve.  
+The figure drawn is defined by the specified list of vertices (vlist).
+The points are connected by lines as specified in the flags in the
+vertex structure.
+</para>
+<para>
+<!-- .LP -->
+Each Vertex, as defined in
+<filename class="headerfile">&lt;X11/X10.h&gt;</filename>,
+<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X10.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X10.h&gt;</filename></secondary></indexterm>
+is a structure with the following members:
+<indexterm significance="preferred"><primary>Vertex</primary></indexterm>
+<synopsis>
+typedef struct _Vertex {
+	short x,y;
+	unsigned short flags;
+} Vertex;
+</synopsis>
+The x and y members are the coordinates of the vertex 
+that are relative to either the upper left inside corner of the drawable 
+(if 
+<symbol>VertexRelative</symbol>
+is zero) or the previous vertex (if 
+<symbol>VertexRelative</symbol>
+is one).
+</para>
+<para>
+<!-- .LP -->
+The flags, as defined in 
+<filename class="headerfile">&lt;X11/X10.h&gt;</filename>,
+<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X10.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X10.h&gt;</filename></secondary></indexterm>
+are as follows:
+<indexterm significance="preferred"><primary>VertexRelative</primary></indexterm>
+<indexterm significance="preferred"><primary>VertexDontDraw</primary></indexterm>
+<indexterm significance="preferred"><primary>VertexCurved</primary></indexterm>
+<indexterm significance="preferred"><primary>VertexStartClosed</primary></indexterm>
+<indexterm significance="preferred"><primary>VertexEndClosed</primary></indexterm>
+<!-- .sM -->
+
+<synopsis>
+VertexRelative     0x0001     /* else absolute */
+VertexDontDraw     0x0002     /* else draw */
+VertexCurved       0x0004     /* else straight */
+VertexStartClosed  0x0008     /* else not */
+VertexEndClosed    0x0010     /* else not */
+</synopsis>
+
+<itemizedlist>
+  <listitem>
+    <para>
+If 
+<symbol>VertexRelative</symbol>
+is not set,  
+the coordinates are absolute (that is, relative to the drawable's origin).  
+The first vertex must be an absolute vertex.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If
+<symbol>VertexDontDraw</symbol>
+is one, 
+no line or curve is drawn from the previous vertex to this one.  
+This is analogous to picking up the pen and moving to another place 
+before drawing another line.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If 
+<symbol>VertexCurved</symbol>
+is one, 
+a spline algorithm is used to draw a smooth curve from the previous vertex
+through this one to the next vertex.  
+Otherwise, a straight line is drawn from the previous vertex to this one.  
+It makes sense to set 
+<symbol>VertexCurved</symbol>
+to one only if a previous and next vertex are both defined
+(either explicitly in the array or through the definition of a closed 
+curve).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+It is permissible for 
+<symbol>VertexDontDraw</symbol>
+bits and 
+<symbol>VertexCurved</symbol>
+bits both to be one. 
+This is useful if you want to define the previous point for the smooth curve
+but do not want an actual curve drawing to start until this point.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If 
+<symbol>VertexStartClosed</symbol>
+is one, 
+then this point marks the beginning of a closed curve.  
+This vertex must be followed later in the array by another vertex 
+whose effective coordinates are identical
+and that has a
+<symbol>VertexEndClosed</symbol>
+bit of one.
+The points in between form a cycle to determine predecessor 
+and successor vertices for the spline algorithm.
+    </para>
+  </listitem>
+</itemizedlist>
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components:
+function, plane-mask, line-width, line-style, cap-style, join-style,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
+clip-mask.
+It also uses these GC mode-dependent components: 
+foreground, background, tile, stipple,
+tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To achieve the effects of the X Version 10
+<function>XDrawTiled</function>
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>
+and 
+<function>XDrawFilled</function>,
+<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>
+use
+<function>XDrawFilled</function>.
+</para>
+
+<para>#include &lt;X11/X10.h&gt;</para>
+
+<funcsynopsis id='xdrawfilled'>
+<funcprototype>
+  <funcdef>Status <function>XDrawFilled</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>Vertex<parameter> *vlist</parameter></paramdef>
+  <paramdef>int<parameter> vcount</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>vlist</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the list of vertices that indicate what to draw.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>vcount</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies how many vertices are in vlist.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawFilled</function>
+function draws arbitrary polygons or curves and then fills them.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components:
+function, plane-mask, line-width, line-style, cap-style, join-style,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
+clip-mask.
+It also uses these GC mode-dependent components: 
+foreground, background, tile, stipple,
+tile-stipple-x-origin, tile-stipple-y-origin, 
+dash-offset, dash-list, fill-style, and fill-rule.
+</para>
+</sect2>
+<sect2 id="Associating_User_Data_with_a_Value">
+<title>Associating User Data with a Value</title>
+<para>
+<!-- .LP -->
+These functions have been superseded by the context management functions
+(see section 16.10). 
+It is often necessary to associate arbitrary information with resource IDs.
+Xlib provides the 
+<function>XAssocTable</function>
+functions that you can use to make such an association.
+<indexterm><primary>Hash Lookup</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>IDs</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary></indexterm>
+Application programs often need to be able to easily refer to
+their own data structures when an event arrives.
+The 
+<function>XAssocTable</function>
+system provides users of the X library with a method
+for associating their own data structures with X resources
+(<type>Pixmap</type>s,
+<type>Font</type>s,
+<type>Window</type>s,
+and so on).
+</para>
+<para>
+<!-- .LP -->
+An 
+<function>XAssocTable</function>
+can be used to type X resources.  
+For example, the user
+may want to have three or four types of windows,
+each with different properties. 
+This can be accomplished by associating each X window ID
+with a pointer to a window property data structure  defined  by  the
+user.
+A generic type has been defined in the X library for resource IDs.
+It is called an XID.
+</para>
+<para>
+<!-- .LP -->
+There are a few  guidelines  that  should be observed when using an
+<function>XAssocTable</function> :
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+All  XIDs  are  relative  to  the  specified display.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Because  of  the  hashing  scheme  used  by  the  association mechanism,
+the following rules for determining the size of a
+<function>XAssocTable</function>
+should be followed.  
+Associations will be  made  and  looked  up  more
+efficiently  if  the  table  size  (number  of  buckets in the hashing
+system) is a power of two and if there are not more than 8 XIDs  per
+bucket.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a pointer to a new
+<function>XAssocTable</function>,
+use 
+<function>XCreateAssocTable</function>.
+<indexterm significance="preferred"><primary>XCreateAssocTable</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='xcreateassoctable'>
+<funcprototype>
+  <funcdef>XAssocTable *<function>XCreateAssocTable</function></funcdef>
+  <paramdef>int<parameter> size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>size</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of buckets in the hash system of
+<function>XAssocTable</function>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The size argument specifies the number of buckets in the 
+hash system of
+<function>XAssocTable</function>.
+For  reasons  of  efficiency  the number of buckets
+should be a power of two.
+Some size  suggestions  might  be:  use  32 buckets  per  100  objects,
+and a reasonable maximum number of objects per buckets is 8.
+If  an  error  allocating  memory  for  the
+<function>XAssocTable</function>
+occurs, 
+a NULL pointer is returned. 
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create an entry in a given 
+<function>XAssocTable</function>,
+use 
+<function>XMakeAssoc</function>.
+<indexterm significance="preferred"><primary>XMakeAssoc</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='xmakeassoc'>
+<funcprototype>
+  <funcdef><function>XMakeAssoc</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
+  <paramdef>XID<parameter> x_id</parameter></paramdef>
+  <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>table</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the assoc table. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_id</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the X resource ID.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the data to be associated with the X resource ID.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMakeAssoc</function>
+function inserts data into an 
+<function>XAssocTable</function>
+keyed on an XID.
+Data is inserted into the table only once.
+Redundant inserts are ignored.
+The queue in each association bucket is sorted from the lowest XID to 
+the highest XID.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain data from a given 
+<function>XAssocTable</function>,
+use 
+<function>XLookUpAssoc</function>.
+<indexterm significance="preferred"><primary>XLookUpAssoc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlookupassoc'>
+<funcprototype>
+  <funcdef>char *<function>XLookUpAssoc</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
+  <paramdef>XID<parameter> x_id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>table</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the assoc table. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_id</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the X resource ID.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLookUpAssoc</function>
+function retrieves the data stored in an 
+<function>XAssocTable</function>
+by its XID.  
+If  an appropriately  matching XID can be found in the table,
+<function>XLookUpAssoc</function>
+returns the data associated with it.
+If the x_id cannot be found in the table,
+it returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete an entry from a given 
+<function>XAssocTable</function>,
+use 
+<function>XDeleteAssoc</function>.
+<indexterm significance="preferred"><primary>XDeleteAssoc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdeleteassoc'>
+<funcprototype>
+  <funcdef><function>XDeleteAssoc</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
+  <paramdef>XID<parameter> x_id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>table</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the assoc table. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_id</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the X resource ID.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteAssoc</function>
+function deletes an association in an 
+<function>XAssocTable</function>
+keyed on its XID.
+Redundant deletes (and deletes of nonexistent XIDs) are ignored.
+Deleting associations in no way impairs the performance of an
+<function>XAssocTable</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free the memory associated with a given 
+<function>XAssocTable</function>,
+use 
+<function>XDestroyAssocTable</function>.
+</para>
+<indexterm significance="preferred"><primary>XDestroyAssocTable</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroyassoctable'>
+<funcprototype>
+  <funcdef><function>XDestroyAssocTable</function></funcdef>
+  <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>table</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the assoc table. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</sect2>
+</sect1>
+</appendix>
diff --git a/libX11/specs/libX11/CH02.xml b/libX11/specs/libX11/CH02.xml
index f4ef1bcd8..901a38503 100644
--- a/libX11/specs/libX11/CH02.xml
+++ b/libX11/specs/libX11/CH02.xml
@@ -66,7 +66,7 @@ To open a connection to the X server that controls a display, use
 <function>XOpenDisplay</function>.
 <indexterm significance="preferred"><primary>XOpenDisplay</primary></indexterm>
 </para>
-<funcsynopsis>
+<funcsynopsis id='xopendisplay'>
 <funcprototype>
   <funcdef>Display *<function>XOpenDisplay</function></funcdef>
   <paramdef>char *<parameter>display_name</parameter></paramdef>
@@ -356,7 +356,7 @@ The names are intended to convey the expected relative intensity of the colors.
 <para>
 BlackPixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xblackpixel'>
 <funcprototype>
   <funcdef>unsigned long <function>XBlackPixel</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -401,7 +401,7 @@ Both return the black pixel value for the specified screen.
 <para>
 WhitePixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xwhitepixel'>
 <funcprototype>
   <funcdef>unsigned long <function>XWhitePixel</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -446,7 +446,7 @@ Both return the white pixel value for the specified screen.
 <para>
 ConnectionNumber(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xconnectionnumber'>
 <funcprototype>
   <funcdef>int <function>XConnectionNumber</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -483,7 +483,7 @@ this is the file descriptor of the connection.
 <para>
 DefaultColormap(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultcolormap'>
 <funcprototype>
   <funcdef>Colormap <function>XDefaultColormap</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -529,7 +529,7 @@ Most routine allocations of color should be made out of this colormap.
 <para>
 DefaultDepth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultdepth'>
 <funcprototype>
   <funcdef>int <function>XDefaultDepth</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -580,7 +580,7 @@ To determine the number of depths that are available on a given screen, use
 <para>
 DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultgc'>
 <funcprototype>
   <funcdef>GC <function>XDefaultGC</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -698,7 +698,7 @@ This GC should never be freed.
 <para>
 DefaultRootWindow(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultrootwindow'>
 <funcprototype>
   <funcdef>Window <function>XDefaultRootWindow</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -732,7 +732,7 @@ Both return the root window for the default screen.
 <para>
 DefaultScreenOfDisplay(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultscreenofdisplay'>
 <funcprototype>
   <funcdef>Screen *<function>XDefaultScreenOfDisplay</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -766,7 +766,7 @@ Both return a pointer to the default screen.
 <para>
 ScreenOfDisplay(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xscreenofdisplay'>
 <funcprototype>
   <funcdef>Screen *<function>XScreenOfDisplay</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -811,7 +811,7 @@ Both return a pointer to the indicated screen.
 <para>
 DefaultScreen(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultscreen'>
 <funcprototype>
   <funcdef>int <function>XDefaultScreen</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -849,7 +849,7 @@ in applications that will use only a single screen.
 <para>
 DefaultVisual(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultvisual'>
 <funcprototype>
   <funcdef>Visual *<function>XDefaultVisual</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -896,7 +896,7 @@ see section 3.1.
 <para>
 DisplayCells(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdisplaycells'>
 <funcprototype>
   <funcdef>int <function>XDisplayCells</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -941,7 +941,7 @@ Both return the number of entries in the default colormap.
 <para>
 DisplayPlanes(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdisplayplanes'>
 <funcprototype>
   <funcdef>int <function>XDisplayPlanes</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -988,7 +988,7 @@ see the glossary.
 <para>
 DisplayString(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdisplaystring'>
 <funcprototype>
   <funcdef>char *<function>XDisplayString</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1032,7 +1032,7 @@ child process as well as for printing error messages.
 <para>
 LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xlastknownrequestprocessed'>
 <funcprototype>
   <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1175,7 +1175,7 @@ are received.
 <para>
 NextRequest(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xnextrequest'>
 <funcprototype>
   <funcdef>unsigned long <function>XNextRequest</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1211,7 +1211,7 @@ Serial numbers are maintained separately for each display connection.
 <para>
 ProtocolVersion(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xprotocolversion'>
 <funcprototype>
   <funcdef>int <function>XProtocolVersion</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1246,7 +1246,7 @@ the connected display.
 <para>
 ProtocolRevision(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xprotocolrevision'>
 <funcprototype>
   <funcdef>int <function>XProtocolRevision</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1280,7 +1280,7 @@ Both return the minor protocol revision number of the X server.
 <para>
 QLength(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xqlength'>
 <funcprototype>
   <funcdef>int <function>XQLength</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1317,7 +1317,7 @@ the queue yet (see
 <para>
 RootWindow(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xrootwindow'>
 <funcprototype>
   <funcdef>Window <function>XRootWindow</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1366,7 +1366,7 @@ and for creating top-level windows.
 <para>
 ScreenCount(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xscreencount'>
 <funcprototype>
   <funcdef>int <function>XScreenCount</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1400,7 +1400,7 @@ Both return the number of available screens.
 <para>
 ServerVendor(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xservervendor'>
 <funcprototype>
   <funcdef>char *<function>XServerVendor</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1438,7 +1438,7 @@ Otherwise, the contents of the string are implementation-dependent.
 <para>
 VendorRelease(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xvendorrelease'>
 <funcprototype>
   <funcdef>int <function>XVendorRelease</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1511,7 +1511,7 @@ To obtain the pixmap format information for a given display, use
 <para>
 ImageByteOrder(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='ximagebyteorder'>
 <funcprototype>
   <funcdef>int <function>XImageByteOrder</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1614,7 +1614,7 @@ or
 <para>
 BitmapUnit(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xbitmapunit'>
 <funcprototype>
   <funcdef>int <function>XBitmapUnit</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1649,7 +1649,7 @@ The scanline is calculated in multiples of this value.
 <para>
 BitmapBitOrder(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xbitmpabitorder'>
 <funcprototype>
   <funcdef>int <function>XBitmapBitOrder</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1689,7 +1689,7 @@ or
 <para>
 BitmapPad(<emphasis remap='I'>display</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xbitmappad'>
 <funcprototype>
   <funcdef>int <function>XBitmapPad</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1724,7 +1724,7 @@ by this macro or function.
 <para>
 DisplayHeight(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdisplayheight'>
 <funcprototype>
   <funcdef>int <function>XDisplayHeight</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1770,7 +1770,7 @@ in pixels.
 <para>
 DisplayHeightMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdisplayheightmm'>
 <funcprototype>
   <funcdef>int <function>XDisplayHeightMM</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1815,7 +1815,7 @@ Both return the height of the specified screen in millimeters.
 <para>
 DisplayWidth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdisplaywidth'>
 <funcprototype>
   <funcdef>int <function>XDisplayWidth</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1860,7 +1860,7 @@ Both return the width of the screen in pixels.
 <para>
 DisplayWidthMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdisplaywidthmm'>
 <funcprototype>
   <funcdef>int <function>XDisplayWidthMM</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1919,7 +1919,7 @@ structure.
 <para>
 BlackPixelOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xblackpixelofscreen'>
 <funcprototype>
   <funcdef>unsigned long <function>XBlackPixelOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -1955,7 +1955,7 @@ Both return the black pixel value of the specified screen.
 <para>
 WhitePixelOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xwhitepixelofscreen'>
 <funcprototype>
   <funcdef>unsigned long <function>XWhitePixelOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -1991,7 +1991,7 @@ Both return the white pixel value of the specified screen.
 <para>
 CellsOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xcellsofscreen'>
 <funcprototype>
   <funcdef>int <function>XCellsOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2028,7 +2028,7 @@ of the specified screen.
 <para>
 DefaultColormapOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultcolormapofscreen'>
 <funcprototype>
   <funcdef>Colormap <function>XDefaultColormapOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2064,7 +2064,7 @@ Both return the default colormap of the specified screen.
 <para>
 DefaultDepthOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultdepthofscreen'>
 <funcprototype>
   <funcdef>int <function>XDefaultDepthOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2100,7 +2100,7 @@ Both return the depth of the root window.
 <para>
 DefaultGCOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultgcofscreen'>
 <funcprototype>
   <funcdef>GC <function>XDefaultGCOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2138,7 +2138,7 @@ The GC must never be freed.
 <para>
 DefaultVisualOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdefaultvisualofscreen'>
 <funcprototype>
   <funcdef>Visual *<function>XDefaultVisualOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2176,7 +2176,7 @@ see section 3.1.
 <para>
 DoesBackingStore(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdoesbackingstore'>
 <funcprototype>
   <funcdef>int <function>XDoesBackingStore</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2219,7 +2219,7 @@ or
 <para>
 DoesSaveUnders(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdoessaveunders'>
 <funcprototype>
   <funcdef>Bool <function>XDoesSaveUnders</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2262,7 +2262,7 @@ the screen does not support save unders (see section 3.2.5).
 <para>
 DisplayOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xdisplayofscreen'>
 <funcprototype>
   <funcdef>Display *<function>XDisplayOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2299,7 +2299,7 @@ Both return the display of the specified screen.
 <para>
 EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xeventmaskofscreen'>
 <funcprototype>
   <funcdef>long <function>XEventMaskOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2372,7 +2372,7 @@ at connection setup time.
 <para>
 WidthOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xwidthofscreen'>
 <funcprototype>
   <funcdef>int <function>XWidthOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2408,7 +2408,7 @@ Both return the width of the specified screen in pixels.
 <para>
 HeightOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xheightofscreen'>
 <funcprototype>
   <funcdef>int <function>XHeightOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2444,7 +2444,7 @@ Both return the height of the specified screen in pixels.
 <para>
 WidthMMOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xwidthmmofscreen'>
 <funcprototype>
   <funcdef>int <function>XWidthMMOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2480,7 +2480,7 @@ Both return the width of the specified screen in millimeters.
 <para>
 HeightMMOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xheightmmofscreen'>
 <funcprototype>
   <funcdef>int <function>XHeightMMOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2516,7 +2516,7 @@ Both return the height of the specified screen in millimeters.
 <para>
 MaxCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xmaxcmapsofscreen'>
 <funcprototype>
   <funcdef>int <function>XMaxCmapsOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2553,7 +2553,7 @@ by the specified screen (see section 9.3).
 <para>
 MinCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xmincmapsofscreen'>
 <funcprototype>
   <funcdef>int <function>XMinCmapsOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2590,7 +2590,7 @@ by the specified screen (see section 9.3).
 <para>
 PlanesOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xplanesofscreen'>
 <funcprototype>
   <funcdef>int <function>XPlanesOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2626,7 +2626,7 @@ Both return the depth of the root window.
 <para>
 RootWindowOfScreen(<emphasis remap='I'>screen</emphasis>)
 </para>
-<funcsynopsis>
+<funcsynopsis id='xrootwindowofscreen'>
 <funcprototype>
   <funcdef>Window <function>XRootWindowOfScreen</function></funcdef>
   <paramdef>Screen<parameter> *screen</parameter></paramdef>
@@ -2670,7 +2670,7 @@ protocol request, use
 <indexterm significance="preferred"><primary>XNoOp</primary></indexterm>
 <!-- .sM -->
 </para>
-<funcsynopsis>
+<funcsynopsis id='xnoop'>
 <funcprototype>
   <funcdef><function>XNoOp</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -2708,7 +2708,7 @@ To free in-memory data that was created by an Xlib function, use
 <indexterm significance="preferred"><primary>XFree</primary></indexterm>
 <!-- .sM -->
 </para>
-<funcsynopsis>
+<funcsynopsis id='xfree'>
 <funcprototype>
   <funcdef>XFree</funcdef>
   <paramdef>void<parameter> *data</parameter></paramdef>
@@ -2754,7 +2754,7 @@ To close a display or disconnect from the X server, use
 <!-- .LP -->
 <!-- .sM -->
 </para>
-<funcsynopsis>
+<funcsynopsis id='xclosedisplay'>
 <funcprototype>
   <funcdef>XCloseDisplay</funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -2822,7 +2822,7 @@ To change a client's close-down mode, use
 <indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm>
 <!-- .sM -->
 </para>
-<funcsynopsis>
+<funcsynopsis id='xsetclosedownmode'>
 <funcprototype>
   <funcdef>XSetCloseDownMode</funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -3107,7 +3107,7 @@ To lock a display across several Xlib calls, use
 <indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm>
 <!-- .sM -->
 </para>
-<funcsynopsis>
+<funcsynopsis id='xlockdisplay'>
 <funcprototype>
   <funcdef>XLockDisplay</funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -3152,7 +3152,7 @@ To unlock a display, use
 <indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm>
 <!-- .sM -->
 </para>
-<funcsynopsis>
+<funcsynopsis id='xunlockdisplay'>
 <funcprototype>
   <funcdef>XUnlockDisplay</funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -3211,7 +3211,7 @@ facilities.
 To track internal connections for a display, use
 <function>XAddConnectionWatch</function>.
 </para>
-<funcsynopsis>
+<funcsynopsis id='xconnectionwatch'>
 <funcprototype>
   <funcdef>type void XConnectionWatchProc</funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -3222,7 +3222,7 @@ To track internal connections for a display, use
 </funcprototype>
 </funcsynopsis>
 
-<funcsynopsis>
+<funcsynopsis id='xaddconnectionwatch'>
 <funcprototype>
   <funcdef>Status XAddConnectionWatch</funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -3313,7 +3313,7 @@ To stop tracking internal connections for a display, use
 <para>
 ()
 </para>
-<funcsynopsis>
+<funcsynopsis id='xremoveconnectionwatch'>
 <funcprototype>
   <funcdef>Status <function>XRemoveConnectionWatch</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -3375,7 +3375,7 @@ To process input on an internal connection, use
 <para>
 ()
 </para>
-<funcsynopsis>
+<funcsynopsis id='xprocessinternalconnection'>
 <funcprototype>
   <funcdef>void <function>XProcessInternalConnection</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -3430,7 +3430,7 @@ To obtain all of the current internal connections for a display, use
 <para>
 ()
 </para>
-<funcsynopsis>
+<funcsynopsis id='xinternalconnectionnumbers'>
 <funcprototype>
   <funcdef>Status <function>XInternalConnectionNumbers</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
diff --git a/libX11/specs/libX11/CH03.xml b/libX11/specs/libX11/CH03.xml
index 645960797..9cbacd83b 100644
--- a/libX11/specs/libX11/CH03.xml
+++ b/libX11/specs/libX11/CH03.xml
@@ -1,4164 +1,4164 @@
-<?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="window_functions"><title>Window Functions</title>

-<sect1 id="Visual_Types">

-<title>Visual Types</title>

-<!-- .XS -->

-<!-- (SN Visual Types -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>Visual Type</primary></indexterm>

-On some display hardware, 

-it may be possible to deal with color resources in more than one way.

-For example, you may be able to deal with a screen of either 12-bit depth

-with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth

-with 8 bits of the pixel dedicated to each of red, green, and blue.

-These different ways of dealing with the visual aspects of the screen

-are called visuals.

-For each screen of the display, there may be a list of valid visual types

-supported at different depths of the screen.

-Because default windows and visual types are defined for each screen,

-most simple applications need not deal with this complexity.

-Xlib provides macros and functions that return the default root window, 

-the default depth of the default root window, and the default visual type

-(see sections 2.2.1 and 16.7).

-</para>

-<para>

-<!-- .LP -->

-Xlib uses an opaque 

-<structname>Visual</structname>

-<indexterm significance="preferred"><primary>Visual</primary></indexterm>

-structure that contains information about the possible color mapping.

-The visual utility functions (see section 16.7) use an

-<structname>XVisualInfo</structname>

-structure to return this information to an application.

-The members of this structure pertinent to this discussion are class, red_mask,

-green_mask, blue_mask, bits_per_rgb, and colormap_size.

-The class member specifies one of the possible visual classes of the screen

-and can be 

-<indexterm><primary>Visual Classes</primary><secondary>StaticGray</secondary></indexterm>

-<indexterm><primary>Visual Classes</primary><secondary>StaticColor</secondary></indexterm>

-<indexterm><primary>Visual Classes</primary><secondary>TrueColor</secondary></indexterm>

-<indexterm><primary>Visual Classes</primary><secondary>StaticColor</secondary></indexterm>

-<indexterm><primary>Visual Classes</primary><secondary>GrayScale</secondary></indexterm>

-<indexterm><primary>Visual Classes</primary><secondary>PseudoColor</secondary></indexterm>

-<symbol>StaticGray</symbol>,

-<symbol>StaticColor</symbol>,

-<symbol>TrueColor</symbol>,

-<symbol>GrayScale</symbol>,

-<symbol>PseudoColor</symbol>,

-or

-<symbol>DirectColor</symbol>.

-</para>

-<para>

-<!-- .LP -->

-The following concepts may serve to make the explanation of

-visual types clearer. 

-The screen can be color or grayscale,

-can have a colormap that is writable or read-only,

-and can also have a colormap whose indices are decomposed into separate 

-<acronym>RGB</acronym> pieces, provided one is not on a grayscale screen.

-This leads to the following diagram:

-</para>

-

-<literallayout class="monospaced">

-                      Color        Gray-Scale

-                   R/O    R/W      R/O   R/W

-----------------------------------------------

- Undecomposed    Static  Pseudo   Static  Gray

-   Colormap      Color   Color    Gray    Scale

-

- Decomposed       True   Direct

-   Colormap       Color  Color

-----------------------------------------------

-</literallayout>

-

-<para>

-<!-- .LP -->

-Conceptually, 

-as each pixel is read out of video memory for display on the screen,

-it goes through a look-up stage by indexing into a colormap.

-Colormaps can be manipulated arbitrarily on some hardware, 

-in limited ways on other hardware, and not at all on other hardware.  

-The visual types affect the colormap and 

-the <acronym>RGB</acronym> values in the following ways:

-</para>

-<para>

-<!-- .LP -->

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-For 

-<symbol>PseudoColor</symbol>,

-a pixel value indexes a colormap to produce

-independent <acronym>RGB</acronym> values, and the <acronym>RGB</acronym> values can be changed dynamically.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<symbol>GrayScale</symbol>

-is treated the same way as 

-<symbol>PseudoColor</symbol>

-except that the primary that drives the screen is undefined. 

-Thus, the client should always store the

-same value for red, green, and blue in the colormaps.  

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-For 

-<symbol>DirectColor</symbol>,

-a pixel value is decomposed into separate <acronym>RGB</acronym> subfields, and each

-subfield separately indexes the colormap for the corresponding value.

-The <acronym>RGB</acronym> values can be changed dynamically.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<symbol>TrueColor</symbol>

-is treated the same way as 

-<symbol>DirectColor</symbol>

-except that the colormap has predefined, read-only <acronym>RGB</acronym> values.

-These <acronym>RGB</acronym> values are server dependent but provide linear or near-linear

-ramps in each primary.  

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<symbol>StaticColor</symbol>

-is treated the same way as 

-<symbol>PseudoColor</symbol>

-except that the colormap has predefined, 

-read-only, server-dependent <acronym>RGB</acronym> values.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<symbol>StaticGray</symbol>

-is treated the same way as 

-<symbol>StaticColor</symbol>

-except that the <acronym>RGB</acronym> values are equal for any single pixel

-value, thus resulting in shades of gray.  

-<symbol>StaticGray</symbol>

-with a two-entry

-colormap can be thought of as monochrome.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The red_mask, green_mask, and blue_mask members are only defined for

-<symbol>DirectColor</symbol>

-and 

-<symbol>TrueColor</symbol>.

-Each has one contiguous set of bits with no

-intersections.

-The bits_per_rgb member specifies the log base 2 of the

-number of distinct color values (individually) of red, green, and blue.

-Actual <acronym>RGB</acronym> values are unsigned 16-bit numbers.

-The colormap_size member defines the number of available colormap entries

-in a newly created colormap.  

-For 

-<symbol>DirectColor</symbol>

-and 

-<symbol>TrueColor</symbol>,

-this is the size of an individual pixel subfield.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the visual ID from a 

-<structname>Visual</structname>,

-use

-<function>XVisualIDFromVisual</function>.

-<indexterm significance="preferred"><primary>XVisualIDFromVisual</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>VisualID <function>XVisualIDFromVisual</function></funcdef>

-  <paramdef>Visual *<parameter>visual</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>visual</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the visual type.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XVisualIDFromVisual</function>

-function returns the visual ID for the specified visual type.

-</para>

-</sect1>

-<sect1 id="Window_Attributes">

-<title>Window Attributes</title>

-<!-- .XS -->

-<!-- (SN Window Attributes -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Window</primary></indexterm>

-<indexterm><primary>Window</primary><secondary>attributes</secondary></indexterm>

-All 

-<symbol>InputOutput</symbol>

-windows have a border width of zero or more pixels, an optional background, 

-an event suppression mask (which suppresses propagation of events from 

-children), and a property list (see section 4.3).

-The window border and background can be a solid color or a pattern, called

-a tile.

-All windows except the root have a parent and are clipped by their parent.

-If a window is stacked on top of another window, it obscures that other

-window for the purpose of input.

-If a window has a background (almost all do), it obscures the other

-window for purposes of output.

-Attempts to output to the obscured area do nothing, 

-and no input events (for example, pointer motion) are generated for the 

-obscured area.

-</para>

-<para>

-<!-- .LP -->

-Windows also have associated property lists (see section 4.3).

-</para>

-<para>

-<!-- .LP -->

-Both

-<symbol>InputOutput</symbol>

-and

-<symbol>InputOnly</symbol>

-windows have the following common attributes,

-which are the only attributes of an

-<symbol>InputOnly</symbol>

-window:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-win-gravity

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-event-mask

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-do-not-propagate-mask

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-override-redirect

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-cursor

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-If you specify any other attributes for an

-<symbol>InputOnly</symbol>

-window,

-a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<symbol>InputOnly</symbol>

-windows are used for controlling input events in situations where

-<symbol>InputOutput</symbol>

-windows are unnecessary.

-<symbol>InputOnly</symbol>

-windows are invisible; can only be used to control such things as

-cursors, input event generation, and grabbing;

-and cannot be used in any graphics requests.

-Note that

-<symbol>InputOnly</symbol>

-windows cannot have

-<symbol>InputOutput</symbol>

-windows as inferiors.

-</para>

-<para>

-<!-- .LP -->

-Windows have borders of a programmable width and pattern

-as well as a background pattern or tile.

-<indexterm><primary>Tile</primary><secondary>pixmaps</secondary></indexterm>

-Pixel values can be used for solid colors.

-<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>

-<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>

-The background and border pixmaps can be destroyed immediately after

-creating the window if no further explicit references to them

-are to be made.

-<indexterm ><primary>Tile</primary><secondary>mode</secondary></indexterm>

-The pattern can either be relative to the parent 

-or absolute.

-If

-<symbol>ParentRelative</symbol>,

-the parent's background is used.

-</para>

-<para>

-<!-- .LP -->

-When windows are first created, 

-they are not visible (not mapped) on the screen.

-Any output to a window that is not visible on the screen 

-and that does not have backing store will be discarded.

-<indexterm><primary>Window</primary><secondary>mapping</secondary></indexterm>

-An application may wish to create a window long before it is

-mapped to the screen.

-When a window is eventually mapped to the screen 

-(using

-<function>XMapWindow</function>),

-<indexterm><primary>XMapWindow</primary></indexterm>

-the X server generates an 

-<symbol>Expose</symbol>

-event for the window if backing store has not been maintained.

-</para>

-<para>

-<!-- .LP -->

-A window manager can override your choice of size, 

-border width, and position for a top-level window.

-Your program must be prepared to use the actual size and position

-of the top window.

-It is not acceptable for a client application to resize itself

-unless in direct response to a human command to do so.

-Instead, either your program should use the space given to it,

-or if the space is too small for any useful work, your program

-might ask the user to resize the window.

-The border of your top-level window is considered fair game 

-for window managers.

-</para>

-<para>

-<!-- .LP -->

-To set an attribute of a window,

-set the appropriate member of the

-<structname>XSetWindowAttributes</structname>

-structure and OR in the corresponding value bitmask in your subsequent calls to

-<function>XCreateWindow</function>

-and

-<function>XChangeWindowAttributes</function>,

-or use one of the other convenience functions that set the appropriate 

-attribute.

-The symbols for the value mask bits and the

-<structname>XSetWindowAttributes</structname>

-structure are:

-<!-- .sM -->

-</para>

-<para>

-<!-- .LP -->

-/* Window attribute value mask bits */

-

-

-<literallayout class="monospaced">

-/* Window attribute value mask bits */

-#define    CWBackPixmap                    (1L&lt;&lt;0)

-#define    CWBackPixel                     (1L&lt;&lt;1)

-#define    CWBorderPixmap                  (1L&lt;&lt;2)

-#define    CWBorderPixel                   (1L&lt;&lt;3)

-#define    CWBitGravity                    (1L&lt;&lt;4)

-#define    CWWinGravity                    (1L&lt;&lt;5)

-#define    CWBackingStore                  (1L&lt;&lt;6)

-#define    CWBackingPlanes                 (1L&lt;&lt;7)

-#define    CWBackingPixel                  (1L&lt;&lt;8)

-#define    CWOverrideRedirect              (1L&lt;&lt;9)

-#define    CWSaveUnder                     (1L&lt;&lt;10)

-#define    CWEventMask                     (1L&lt;&lt;11)

-#define    CWDontPropagate                 (1L&lt;&lt;12)

-#define    CWColormap                      (1L&lt;&lt;13)

-#define    CWCursor                        (1L&lt;&lt;14)

-</literallayout>

-

-<indexterm significance="preferred"><primary>XSetWindowAttributes</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-/* Values */

-

-typedef struct {

-     Pixmap background_pixmap;     /* background, None, or ParentRelative */

-     unsigned long background_pixel;     /* background pixel */

-     Pixmap border_pixmap;          /* border of the window or CopyFromParent */

-     unsigned long border_pixel;     /* border pixel value */

-     int bit_gravity;     /* one of bit gravity values */

-     int win_gravity;     /* one of the window gravity values */

-     int backing_store;     /* NotUseful, WhenMapped, Always */

-     unsigned long backing_planes;     /* planes to be preserved if possible */

-     unsigned long backing_pixel;     /* value to use in restoring planes */

-     Bool save_under;     /* should bits under be saved? (popups) */

-     long event_mask;     /* set of events that should be saved */

-     long do_not_propagate_mask;     /* set of events that should not propagate */

-     Bool override_redirect;     /* boolean value for override_redirect */

-     Colormap colormap;     /* color map to be associated with window */

-     Cursor cursor;          /* cursor to be displayed (or None) */

-} XSetWindowAttributes;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The following lists the defaults for each window attribute and indicates

-whether the attribute is applicable to

-<symbol>InputOutput</symbol>

-and

-<symbol>InputOnly</symbol>

-windows:

-</para>

-<informaltable>

-  <tgroup cols='4' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <colspec colname='c4'/>

-  <thead>

-    <row>

-      <entry>Attribute</entry>

-      <entry>Default</entry>

-      <entry>InputOutput</entry>

-      <entry>nputOnly</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>background-pixmap</entry>

-      <entry><symbol>None</symbol></entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>background-pixel</entry>

-      <entry>Undefined</entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>border-pixmap</entry>

-      <entry><symbol>CopyFromParent</symbol></entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>border-pixel</entry>

-      <entry>Undefined</entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>bit-gravity</entry>

-      <entry><symbol>ForgetGravity</symbol></entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>win-gravity</entry>

-      <entry><symbol>NorthWestGravity</symbol></entry>

-      <entry>Yes</entry>

-      <entry>Yes</entry>

-    </row>

-    <row>

-      <entry>backing-store</entry>

-      <entry><symbol>NotUseful</symbol></entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>backing-planes</entry>

-      <entry>All ones</entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>backing-pixel</entry>

-      <entry>zero</entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>save-under</entry>

-      <entry><symbol>False</symbol></entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>event-mask</entry>

-      <entry>empty set</entry>

-      <entry>Yes</entry>

-      <entry>Yes</entry>

-    </row>

-    <row>

-      <entry>do-not-propagate-mask</entry>

-      <entry>empty set</entry>

-      <entry>Yes</entry>

-      <entry>Yes</entry>

-    </row>

-    <row>

-      <entry>override-redirect</entry>

-      <entry><symbol>False</symbol></entry>

-      <entry>Yes</entry>

-      <entry>Yes</entry>

-    </row>

-    <row>

-      <entry>colormap</entry>

-      <entry><symbol>CopyFromParent</symbol></entry>

-      <entry>Yes</entry>

-      <entry>No</entry>

-    </row>

-    <row>

-      <entry>cursor</entry>

-      <entry><symbol>None</symbol></entry>

-      <entry>Yes</entry>

-      <entry>Yes</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<sect2 id="Background_Attribute">

-<title>Background Attribute</title>

-<!-- .XS -->

-<!-- (SN Background Attribute -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Only

-<symbol>InputOutput</symbol>

-windows can have a background.

-You can set the background of an

-<symbol>InputOutput</symbol>

-window by using a pixel or a pixmap.

-</para>

-<para>

-<!-- .LP -->

-The background-pixmap attribute of a window specifies the pixmap to be used for 

-a window's background.

-This pixmap can be of any size, although some sizes may be faster than others.

-The background-pixel attribute of a window specifies a pixel value used to paint

-a window's background in a single color.

-</para>

-<para>

-<!-- .LP -->

-You can set the background-pixmap to a pixmap,  

-<symbol>None</symbol>

-(default), or 

-<symbol>ParentRelative</symbol>.

-You can set the background-pixel of a window to any pixel value (no default).

-If you specify a background-pixel, 

-it overrides either the default background-pixmap

-or any value you may have set in the background-pixmap.

-A pixmap of an undefined size that is filled with the background-pixel is used 

-for the background.

-Range checking is not performed on the background pixel;

-it simply is truncated to the appropriate number of bits.

-</para>

-<para>

-<!-- .LP -->

-If you set the background-pixmap,

-it overrides the default.

-The background-pixmap and the window must have the same depth,

-or a

-<errorname>BadMatch</errorname>

-error results.

-If you set background-pixmap to

-<symbol>None</symbol>,

-the window has no defined background.  

-If you set the background-pixmap to

-<symbol>ParentRelative</symbol>:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The parent window's background-pixmap is used. 

-The child window, however, must have the same depth as 

-its parent,

-or a

-<errorname>BadMatch</errorname>

-error results.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the parent window has a background-pixmap of

-<symbol>None</symbol>,

-the window also has a background-pixmap of

-<symbol>None</symbol>.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A copy of the parent window's background-pixmap is not made.

-The parent's background-pixmap is examined each time the child window's 

-background-pixmap is required.  

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The background tile origin always aligns with the parent window's

-background tile origin. 

-If the background-pixmap is not

-<symbol>ParentRelative</symbol>,

-the background tile origin is the child window's origin.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Setting a new background, whether by setting background-pixmap or

-background-pixel, overrides any previous background.

-The background-pixmap can be freed immediately if no further explicit reference

-is made to it (the X server will keep a copy to use when needed).

-If you later draw into the pixmap used for the background,

-what happens is undefined because the

-X implementation is free to make a copy of the pixmap or

-to use the same pixmap.

-</para>

-<para>

-<!-- .LP -->

-When no valid contents are available for regions of a window

-and either the regions are visible or the server is maintaining backing store,

-the server automatically tiles the regions with the window's background

-unless the window has a background of

-<symbol>None</symbol>.

-If the background is

-<symbol>None</symbol>,

-the previous screen contents from other windows of the same depth as the window

-are simply left in place as long as the contents come from the parent of the

-window or an inferior of the parent.

-Otherwise, the initial contents of the exposed regions are undefined.

-<symbol>Expose</symbol>

-events are then generated for the regions, even if the background-pixmap

-is

-<symbol>None</symbol>

-(see section 10.9).

-</para>

-</sect2>

-<sect2 id="Border_Attribute">

-<title>Border Attribute</title>

-<!-- .XS -->

-<!-- (SN Border Attribute -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Only

-<symbol>InputOutput</symbol>

-windows can have a border.

-You can set the border of an

-<symbol>InputOutput</symbol>

-window by using a pixel or a pixmap.

-</para>

-<para>

-<!-- .LP -->

-The border-pixmap attribute of a window specifies the pixmap to be used 

-for a window's border.

-The border-pixel attribute of a window specifies a pixmap of undefined size 

-filled with that pixel be used for a window's border. 

-Range checking is not performed on the background pixel;

-it simply is truncated to the appropriate number of bits.

-The border tile origin is always the same as the background tile origin.

-</para>

-<para>

-<!-- .LP -->

-You can also set the border-pixmap to a pixmap of any size (some may be faster

-than others) or to

-<symbol>CopyFromParent</symbol>

-(default).

-You can set the border-pixel to any pixel value (no default).

-</para>

-<para>

-<!-- .LP -->

-If you set a border-pixmap, 

-it overrides the default.

-The border-pixmap and the window must have the same depth,

-or a

-<errorname>BadMatch</errorname>

-error results.

-If you set the border-pixmap to 

-<symbol>CopyFromParent</symbol>,

-the parent window's border-pixmap is copied.

-Subsequent changes to the parent window's border attribute do not affect 

-the child window.

-However, the child window must have the same depth as the parent window,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-The border-pixmap can be freed immediately if no further explicit reference

-is made to it.

-If you later draw into the pixmap used for the border,

-what happens is undefined because the

-X implementation is free either to make a copy of the pixmap or

-to use the same pixmap.

-If you specify a border-pixel, 

-it overrides either the default border-pixmap

-or any value you may have set in the border-pixmap.

-All pixels in the window's border will be set to the border-pixel.

-Setting a new border, whether by setting border-pixel or by setting

-border-pixmap, overrides any previous border.

-</para>

-<para>

-<!-- .LP -->

-Output to a window is always clipped to the inside of the window. 

-Therefore, graphics operations never affect the window border.

-</para>

-</sect2>

-<sect2 id="Gravity_Attributes">

-<title>Gravity Attributes</title>

-<!-- .XS -->

-<!-- (SN Gravity Attributes -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The bit gravity of a window defines which region of the window should be 

-retained when an

-<symbol>InputOutput</symbol>

-window is resized. 

-The default value for the bit-gravity attribute is 

-<symbol>ForgetGravity</symbol>.

-The window gravity of a window allows you to define how the 

-<symbol>InputOutput</symbol>

-or

-<symbol>InputOnly</symbol>

-window should be repositioned if its parent is resized.  

-The default value for the win-gravity attribute is 

-<symbol>NorthWestGravity</symbol>.

-</para>

-<para>

-<!-- .LP -->

-If the inside width or height of a window is not changed 

-and if the window is moved or its border is changed, 

-then the contents of the window are not lost but move with the window.

-Changing the inside width or height of the window causes its contents to be

-moved or lost (depending on the bit-gravity of the window) and causes

-children to be reconfigured (depending on their win-gravity).

-For a

-change of width and height, the (x, y) pairs are defined:

-</para>

-<para>

-<!-- .LP -->

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry>Gravity Direction</entry>

-      <entry>Coordinates</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry><symbol>NorthWestGravity</symbol></entry>

-      <entry>(0, 0)</entry>

-    </row>

-    <row>

-      <entry><symbol>NorthGravity</symbol></entry>

-      <entry>(Width/2, 0)</entry>

-    </row>

-    <row>

-      <entry><symbol>NorthEastGravity</symbol></entry>

-      <entry>(Width, 0)</entry>

-    </row>

-    <row>

-      <entry><symbol>WestGravity</symbol></entry>

-      <entry>(0, Height/2)</entry>

-    </row>

-    <row>

-      <entry><symbol>CenterGravity</symbol></entry>

-      <entry>(Width/2, Height/2)</entry>

-    </row>

-    <row>

-      <entry><symbol>EastGravity</symbol></entry>

-      <entry>(Width, Height/2)</entry>

-    </row>

-    <row>

-      <entry><symbol>SouthWestGravity</symbol></entry>

-      <entry>(0, Height)</entry>

-    </row>

-    <row>

-      <entry><symbol>SouthGravity</symbol></entry>

-      <entry>(Width/2, Height)</entry>

-    </row>

-    <row>

-      <entry><symbol>SouthEastGravity</symbol></entry>

-      <entry>(Width, Height)</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-</para>

-<para>

-<!-- .LP -->

-When a window with one of these bit-gravity values is resized, 

-the corresponding pair

-defines the change in position of each pixel in the window.

-When a window with one of these win-gravities has its parent window resized,

-the corresponding pair defines the change in position of the window 

-within the parent.

-When a window is so repositioned, a

-<symbol>GravityNotify</symbol>

-event is generated (see section 10.10.5).

-</para>

-<para>

-<!-- .LP -->

-A bit-gravity of

-<symbol>StaticGravity</symbol>

-indicates that the contents or origin should not move relative to the 

-origin of the root window.

-If the change in size of the window is coupled with a change in position (x, y),

-then for bit-gravity the change in position of each pixel is (&minus;x, &minus;y), and for

-win-gravity the change in position of a child when its parent is so resized is

-(&minus;x, &minus;y).

-Note that

-<symbol>StaticGravity</symbol>

-still only takes effect when the width or height of the window is changed, 

-not when the window is moved.

-</para>

-<para>

-<!-- .LP -->

-A bit-gravity of 

-<symbol>ForgetGravity</symbol>

-indicates that the window's contents are always discarded after a size change, 

-even if a backing store or save under has been requested.

-The window is tiled with its background

-and zero or more 

-<symbol>Expose</symbol>

-events are generated. 

-If no background is defined, the existing screen contents are not

-altered.

-Some X servers may also ignore the specified bit-gravity and 

-always generate 

-<symbol>Expose</symbol>

-events.

-</para>

-<para>

-<!-- .LP -->

-The contents and borders of inferiors are not affected by their parent's

-bit-gravity.

-A server is permitted to ignore the specified bit-gravity and use

-<symbol>Forget</symbol>

-instead.

-</para>

-<para>

-<!-- .LP -->

-A win-gravity of 

-<symbol>UnmapGravity</symbol>

-is like 

-<symbol>NorthWestGravity</symbol>

-(the window is not moved),

-except the child is also

-unmapped when the parent is resized,

-and an 

-<symbol>UnmapNotify</symbol>

-event is

-generated.

-</para>

-</sect2>

-<sect2 id="Backing_Store_Attribute">

-<title>Backing Store Attribute</title>

-<!-- .XS -->

-<!-- (SN Backing Store Attribute -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Some implementations of the X server may choose to maintain the contents of 

-<symbol>InputOutput</symbol>

-windows.

-If the X server maintains the contents of a window, 

-the off-screen saved pixels

-are known as backing store.

-The backing store advises the X server on what to do 

-with the contents of a window.

-The backing-store attribute can be set to

-<symbol>NotUseful</symbol>

-(default),

-<symbol>WhenMapped</symbol>,

-or

-<symbol>Always</symbol>.

-</para>

-<para>

-<!-- .LP -->

-A backing-store attribute of 

-<symbol>NotUseful</symbol>

-advises the X server that 

-maintaining contents is unnecessary, 

-although some X implementations may

-still choose to maintain contents and, therefore, not generate 

-<symbol>Expose</symbol>

-events.

-A backing-store attribute of 

-<symbol>WhenMapped</symbol>

-advises the X server that maintaining contents of 

-obscured regions when the window is mapped would be beneficial.

-In this case,

-the server may generate an 

-<symbol>Expose</symbol>

-event when the window is created.

-A backing-store attribute of 

-<symbol>Always</symbol>

-advises the X server that maintaining contents even when 

-the window is unmapped would be beneficial.  

-Even if the window is larger than its parent, 

-this is a request to the X server to maintain complete contents, 

-not just the region within the parent window boundaries.  

-While the X server maintains the window's contents, 

-<symbol>Expose</symbol>

-events normally are not generated, 

-but the X server may stop maintaining 

-contents at any time.  

-</para>

-<para>

-<!-- .LP -->

-When the contents of obscured regions of a window are being maintained,

-regions obscured by noninferior windows are included in the destination

-of graphics requests (and source, when the window is the source).

-However, regions obscured by inferior windows are not included.

-</para>

-</sect2>

-<sect2 id="Save_Under_Flag">

-<title>Save Under Flag</title>

-<!-- .XS -->

-<!-- (SN Save Under Flag -->

-<!-- .XE -->

-<indexterm><primary>Save Unders</primary></indexterm>

-<para>

-<!-- .LP -->

-Some server implementations may preserve contents of 

-<symbol>InputOutput</symbol>

-windows under other 

-<symbol>InputOutput</symbol>

-windows.

-This is not the same as preserving the contents of a window for you.

-You may get better visual

-appeal if transient windows (for example, pop-up menus) request that the system

-preserve the screen contents under them, 

-so the temporarily obscured applications do not have to repaint.

-</para>

-<para>

-<!-- .LP -->

-You can set the save-under flag to

-<symbol>True</symbol>

-or

-<symbol>False</symbol>

-(default).

-If save-under is 

-<symbol>True</symbol>,

-the X server is advised that, when this window is mapped, 

-saving the contents of windows it obscures would be beneficial.

-</para>

-</sect2>

-<sect2 id="Backing_Planes_and_Backing_Pixel_Attributes">

-<title>Backing Planes and Backing Pixel Attributes</title>

-<!-- .XS -->

-<!-- (SN Backing Planes and Backing Pixel Attributes -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-You can set backing planes to indicate (with bits set to 1) 

-which bit planes of an

-<symbol>InputOutput</symbol>

-window hold dynamic data that must be preserved in backing store 

-and during save unders.

-The default value for the backing-planes attribute is all bits set to 1.

-You can set backing pixel to specify what bits to use in planes not 

-covered by backing planes.

-The default value for the backing-pixel attribute is all bits set to 0.

-The X server is free to save only the specified bit planes in the backing store

-or the save under and is free to regenerate the remaining planes with 

-the specified pixel value.

-Any extraneous bits in these values (that is, those bits beyond 

-the specified depth of the window) may be simply ignored.

-If you request backing store or save unders,

-you should use these members to minimize the amount of off-screen memory 

-required to store your window.

-</para>

-</sect2>

-<sect2 id="Event_Mask_and_Do_Not_Propagate_Mask_Attributes">

-<title>Event Mask and Do Not Propagate Mask Attributes</title>

-<!-- .XS -->

-<!-- (SN Event Mask and Do Not Propagate Mask Attributes -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The event mask defines which events the client is interested in for this 

-<symbol>InputOutput</symbol>

-or

-<symbol>InputOnly</symbol>

-window (or, for some event types, inferiors of this window).

-The event mask is the bitwise inclusive OR of zero or more of the 

-valid event mask bits.

-You can specify that no maskable events are reported by setting 

-<symbol>NoEventMask</symbol>

-(default).

-</para>

-<para>

-<!-- .LP -->

-The do-not-propagate-mask attribute

-defines which events should not be propagated to 

-ancestor windows when no client has the event type selected in this 

-<symbol>InputOutput</symbol>

-or

-<symbol>InputOnly</symbol>

-window.

-The do-not-propagate-mask is the bitwise inclusive OR of zero or more

-of the following masks:

-<symbol>KeyPress</symbol>,

-<symbol>KeyRelease</symbol>,

-<symbol>ButtonPress</symbol>,

-<symbol>ButtonRelease</symbol>,

-<symbol>PointerMotion</symbol>,

-<symbol>Button1Motion</symbol>,

-<symbol>Button2Motion</symbol>,

-<symbol>Button3Motion</symbol>,

-<symbol>Button4Motion</symbol>,

-<symbol>Button5Motion</symbol>,

-and

-<symbol>ButtonMotion</symbol>.

-You can specify that all events are propagated by setting 

-<symbol>NoEventMask</symbol>

-(default).

-</para>

-</sect2>

-<sect2 id="Override_Redirect_Flag">

-<title>Override Redirect Flag</title>

-<!-- .XS -->

-<!-- (SN Override Redirect Flag -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To control window placement or to add decoration,

-a window manager often needs to intercept (redirect) any map or configure

-request.

-Pop-up windows, however, often need to be mapped without a window manager

-getting in the way.

-To control whether an

-<symbol>InputOutput</symbol>

-or

-<symbol>InputOnly</symbol>

-window is to ignore these structure control facilities,

-use the override-redirect flag.

-</para>

-<para>

-<!-- .LP -->

-The override-redirect flag specifies whether map and configure requests 

-on this window should override a 

-<symbol>SubstructureRedirectMask</symbol>

-on the parent.

-You can set the override-redirect flag to

-<symbol>True</symbol>

-or

-<symbol>False</symbol>

-(default).

-Window managers use this information to avoid tampering with pop-up windows

-(see also chapter 14).

-</para>

-</sect2>

-<sect2 id="Colormap_Attribute">

-<title>Colormap Attribute</title>

-<!-- .XS -->

-<!-- (SN Colormap Attribute -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The colormap attribute specifies which colormap best reflects the true

-colors of the 

-<symbol>InputOutput</symbol>

-window.  

-The colormap must have the same visual type as the window,

-or a 

-<errorname>BadMatch</errorname>

-error results.  

-X servers capable of supporting multiple 

-hardware colormaps can use this information, 

-and window managers can use it for calls to

-<function>XInstallColormap</function>.

-You can set the colormap attribute to a colormap or to

-<symbol>CopyFromParent</symbol>

-(default).

-</para>

-<para>

-<!-- .LP -->

-If you set the colormap to

-<symbol>CopyFromParent</symbol>,

-the parent window's colormap is copied and used by its child.

-However, the child window must have the same visual type as the parent, 

-or a 

-<errorname>BadMatch</errorname>

-error results. 

-The parent window must not have a colormap of 

-<symbol>None</symbol>,

-or a 

-<errorname>BadMatch</errorname>

-error results.

-The colormap is copied by sharing the colormap object between the child 

-and parent, not by making a complete copy of the colormap contents.

-Subsequent changes to the parent window's colormap attribute do

-not affect the child window.

-</para>

-</sect2>

-<sect2 id="Cursor_Attribute">

-<title>Cursor Attribute</title>

-<!-- .XS -->

-<!-- (SN Cursor Attribute -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The cursor attribute specifies which cursor is to be used when the pointer is

-in the 

-<symbol>InputOutput</symbol>

-or

-<symbol>InputOnly</symbol>

-window.

-You can set the cursor to a cursor or

-<symbol>None</symbol>

-(default).

-</para>

-<para>

-<!-- .LP -->

-If you set the cursor to

-<symbol>None</symbol>,

-the parent's cursor is used when the 

-pointer is in the 

-<symbol>InputOutput</symbol>

-or

-<symbol>InputOnly</symbol>

-window, and any change in the parent's cursor will cause an

-immediate change in the displayed cursor.

-By calling

-<function>XFreeCursor</function>,

-the cursor can be freed immediately as long as no further explicit reference 

-to it is made.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Creating_Windows">

-<title>Creating Windows</title>

-<!-- .XS -->

-<!-- (SN Creating Windows -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides basic ways for creating windows,

-and toolkits often supply higher-level functions specifically for

-creating and placing top-level windows,

-which are discussed in the appropriate toolkit documentation.

-If you do not use a toolkit, however,

-you must provide some standard information or hints for the window

-manager by using the Xlib inter-client communication functions

-(see chapter 14).

-</para>

-<para>

-<!-- .LP -->

-If you use Xlib to create your own top-level windows

-(direct children of the root window),

-you must observe the following rules so that all applications interact

-reasonably across the different styles of window management:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-You must never fight with the window manager for the size or

-placement of your top-level window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-You must be able to deal with whatever size window you get, 

-even if this means that your application just prints a message 

-like ``Please make me bigger'' in its window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-You should only attempt to resize or move top-level windows in

-direct response to a user request.

-If a request to change the size of a top-level window fails,

-you must be prepared to live with what you get.

-You are free to resize or move the children of top-level

-windows as necessary.

-(Toolkits often have facilities for automatic relayout.)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If you do not use a toolkit that automatically sets standard window properties,

-you should set these properties for top-level windows before mapping them.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-For further information,

-see chapter 14 and the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateWindow</function>

-is the more general function that allows you to set specific window attributes 

-when you create a window.

-<function>XCreateSimpleWindow</function>

-creates a window that inherits its attributes from its parent window.

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>Window</primary><secondary>InputOnly</secondary></indexterm>

-The X server acts as if 

-<symbol>InputOnly</symbol>

-windows do not exist for

-the purposes of graphics requests, exposure processing, and

-<symbol>VisibilityNotify</symbol>

-events.

-An 

-<symbol>InputOnly</symbol>

-window cannot be used as a

-drawable (that is, as a source or destination for graphics requests).

-<symbol>InputOnly</symbol>

-and 

-<symbol>InputOutput</symbol>

-windows act identically in other respects (properties,

-grabs, input control, and so on).

-Extension packages can define other classes of windows.

-</para>

-<para>

-<!-- .LP -->

-To create an unmapped window and set its window attributes, use

-<function>XCreateWindow</function>.

-<indexterm significance="preferred"><primary>XCreateWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Window <function>XCreateWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> parent</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedint<parameter> border_width</parameter></paramdef>

-  <paramdef>int<parameter> depth</parameter></paramdef>

-  <paramdef>unsignedint<parameter> class</parameter></paramdef>

-  <paramdef>Visual<parameter> *visual</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

-  <paramdef>XSetWindowAttributes<parameter> *attributes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>parent</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the parent window.

-<!-- .ds Xy , which are the top-left outside corner of the created window's \ -->

-borders and are relative to the inside of the parent window's borders

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which are the created window's inside dimensions \ -->

-and do not include the created window's borders

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-The dimensions must be nonzero,

-or a

-<errorname>BadValue</errorname>

-error results.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>border_width</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the width of the created window's border in pixels.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>depth</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window's depth.

-A depth of 

-<symbol>CopyFromParent</symbol>

-means the depth is taken from the parent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the created window's class.

-You can pass

-<symbol>InputOutput</symbol>,

-<symbol>InputOnly</symbol>,

-or 

-<symbol>CopyFromParent</symbol>.

-A class of 

-<symbol>CopyFromParent</symbol>

-means the class

-is taken from the parent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>visual</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the visual type.

-A visual of 

-<symbol>CopyFromParent</symbol>

-means the visual type is taken from the 

-parent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>valuemask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which window attributes are defined in the attributes

-argument.

-This mask is the bitwise inclusive OR of the valid attribute mask bits.

-If valuemask is zero,

-the attributes are ignored and are not referenced.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>attributes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the structure from which the values (as specified by the value mask)

-are to be taken.

-The value mask should have the appropriate bits

-set to indicate which attributes have been set in the structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateWindow</function>

-function creates an unmapped subwindow for a specified parent window, 

-returns the window ID of the created window, 

-and causes the X server to generate a

-<symbol>CreateNotify</symbol>

-event.

-The created window is placed on top in the stacking order 

-with respect to siblings.

-</para>

-<para>

-<!-- .LP -->

-The coordinate system has the X axis horizontal and the Y axis vertical

-with the origin [0, 0] at the upper-left corner.

-Coordinates are integral,

-in terms of pixels,

-and coincide with pixel centers.

-Each window and pixmap has its own coordinate system.

-For a window, 

-the origin is inside the border at the inside, upper-left corner.

-</para>

-<para>

-<!-- .LP -->

-The border_width for an

-<symbol>InputOnly</symbol>

-window must be zero, or a

-<errorname>BadMatch</errorname>

-error results.

-For class

-<symbol>InputOutput</symbol>,

-the visual type and depth must be a combination supported for the screen,

-or a

-<errorname>BadMatch</errorname>

-error results.

-The depth need not be the same as the parent,

-but the parent must not be a window of class 

-<symbol>InputOnly</symbol>,

-or a

-<errorname>BadMatch</errorname>

-error results.

-For an

-<symbol>InputOnly</symbol>

-window,

-the depth must be zero, and the visual must be one supported by the screen.

-If either condition is not met,

-a

-<errorname>BadMatch</errorname>

-error results.

-The parent window, however, may have any depth and class.

-If you specify any invalid window attribute for a window, a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-The created window is not yet displayed (mapped) on the user's display.

-To display the window, call

-<function>XMapWindow</function>.

-The new window initially uses the same cursor as

-its parent. 

-A new cursor can be defined for the new window by calling

-<function>XDefineCursor</function>.

-<indexterm><primary>Cursor</primary><secondary>Initial State</secondary></indexterm>

-<indexterm><primary>XDefineCursor</primary></indexterm>

-The window will not be visible on the screen unless it and all of its

-ancestors are mapped and it is not obscured by any of its ancestors.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateWindow</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadColor</errorname>,

-<errorname>BadCursor</errorname>,

-<errorname>BadMatch</errorname>,

-<errorname>BadPixmap</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create an unmapped 

-<symbol>InputOutput</symbol>

-subwindow of a given parent window, use

-<function>XCreateSimpleWindow</function>.

-<indexterm significance="preferred"><primary>XCreateSimpleWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Window <function>XCreateSimpleWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> parent</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedint<parameter> border_width</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> border</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> background</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>parent</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the parent window.

-<!-- .ds Xy , which are the top-left outside corner of the new window's borders \ -->

-and are relative to the inside of the parent window's borders

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which are the created window's inside dimensions \ -->

-and do not include the created window's borders

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-The dimensions must be nonzero,

-or a

-<errorname>BadValue</errorname>

-error results.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>border_width</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the width of the created window's border in pixels.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>border</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the border pixel value of the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>background</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the background pixel value of the window.

-

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateSimpleWindow</function>

-function creates an unmapped

-<symbol>InputOutput</symbol>

-subwindow for a specified parent window, returns the

-window ID of the created window, and causes the X server to generate a

-<symbol>CreateNotify</symbol>

-event.

-The created window is placed on top in the stacking order with respect to 

-siblings.

-Any part of the window that extends outside its parent window is clipped.

-The border_width for an

-<symbol>InputOnly</symbol>

-window must be zero, or a

-<errorname>BadMatch</errorname>

-error results.

-<function>XCreateSimpleWindow</function>

-inherits its depth, class, and visual from its parent.

-All other window attributes, except background and border, 

-have their default values.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateSimpleWindow</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadMatch</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Destroying_Windows">

-<title>Destroying Windows</title>

-<!-- .XS -->

-<!-- (SN Destroying Windows  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to destroy a window or destroy all

-subwindows of a window.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To destroy a window and all of its subwindows, use

-<function>XDestroyWindow</function>.

-<indexterm significance="preferred"><primary>XDestroyWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDestroyWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDestroyWindow</function>

-function destroys the specified window as well as all of its subwindows and causes

-the X server to generate a

-<symbol>DestroyNotify</symbol>

-event for each window.

-The window should never be referenced again.

-If the window specified by the w argument is mapped,

-it is unmapped automatically.

-The ordering of the

-<symbol>DestroyNotify</symbol>

-events is such that for any given window being destroyed,

-<symbol>DestroyNotify</symbol>

-is generated on any inferiors of the window before being generated on

-the window itself.

-The ordering among siblings and across subhierarchies is not otherwise

-constrained.

-If the window you specified is a root window, no windows are destroyed.

-Destroying a mapped window will generate 

-<symbol>Expose</symbol>

-events on other windows that were obscured by the window being destroyed.

-</para>

-<para>

-<!-- .LP -->

-<function>XDestroyWindow</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To destroy all subwindows of a specified window, use 

-<function>XDestroySubwindows</function>.

-<indexterm significance="preferred"><primary>XDestroySubwindows</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDestroySubwindows</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDestroySubwindows</function>

-function destroys all inferior windows of the specified window, 

-in bottom-to-top stacking order.

-It causes the X server to generate a

-<symbol>DestroyNotify</symbol>

-event for each window.

-If any mapped

-subwindows were actually destroyed,

-<function>XDestroySubwindows</function>

-causes the X server to generate 

-<symbol>Expose</symbol>

-events on the specified window.

-This is much more efficient than deleting many windows

-one at a time because much of the work need be performed only once for all

-of the windows, rather than for each window.

-The subwindows should never be referenced again.  

-</para>

-<para>

-<!-- .LP -->

-<function>XDestroySubwindows</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Mapping_Windows_">

-<title>Mapping Windows </title>

-<!-- .XS -->

-<!-- (SN Mapping Windows  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A window is considered mapped if an 

-<function>XMapWindow</function>

-call has been made on it.

-It may not be visible on the screen for one of the following reasons:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-It is obscured by another opaque window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-One of its ancestors is not mapped.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-It is entirely clipped by an ancestor.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-<symbol>Expose</symbol>

-events are generated for the window when part or all of

-it becomes visible on the screen. 

-A client receives the

-<symbol>Expose</symbol>

-events only if it has asked for them.

-Windows retain their position in the stacking order when they are unmapped.

-</para>

-<para>

-<!-- .LP -->

-A window manager may want to control the placement of subwindows.

-If 

-<symbol>SubstructureRedirectMask</symbol>

-has been selected by a window manager

-on a parent window (usually a root window),

-a map request initiated by other clients on a child window is not performed,

-and the window manager is sent a 

-<symbol>MapRequest</symbol>

-event.

-However, if the override-redirect flag on the child had been set to

-<symbol>True</symbol>

-(usually only on pop-up menus),

-the map request is performed.

-</para>

-<para>

-<!-- .LP -->

-A tiling window manager might decide to reposition and resize other clients' 

-windows and then decide to map the window to its final location.

-A window manager that wants to provide decoration might

-reparent the child into a frame first.

-For further information,

-see sections 3.2.8 and 10.10.

-Only a single client at a time can select for 

-<symbol>SubstructureRedirectMask</symbol>.

-</para>

-<para>

-<!-- .LP -->

-Similarly, a single client can select for 

-<symbol>ResizeRedirectMask</symbol>

-on a parent window.

-Then, any attempt to resize the window by another client is suppressed, and

-the client receives a 

-<symbol>ResizeRequest</symbol>

-event.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To map a given window, use 

-<function>XMapWindow</function>.

-<indexterm significance="preferred"><primary>XMapWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XMapWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMapWindow</function>

-function

-maps the window and all of its

-subwindows that have had map requests.

-Mapping a window that has an unmapped ancestor does not display the

-window but marks it as eligible for display when the ancestor becomes

-mapped.

-Such a window is called unviewable.

-When all its ancestors are mapped,

-the window becomes viewable

-and will be visible on the screen if it is not obscured by another window.

-This function has no effect if the window is already mapped.

-</para>

-<para>

-<!-- .LP -->

-If the override-redirect of the window is

-<symbol>False</symbol>

-and if some other client has selected

-<symbol>SubstructureRedirectMask</symbol>

-on the parent window, then the X server generates a

-<symbol>MapRequest</symbol>

-event, and the

-<function>XMapWindow</function>

-function does not map the window.

-Otherwise, the window is mapped, and the X server generates a

-<symbol>MapNotify</symbol>

-event.

-</para>

-<para>

-<!-- .LP -->

-If the window becomes viewable and no earlier contents for it are remembered,

-the X server tiles the window with its background.

-If the window's background is undefined,

-the existing screen contents are not

-altered, and the X server generates zero or more 

-<symbol>Expose</symbol>

-events.

-If backing-store was maintained while the window was unmapped, no 

-<symbol>Expose</symbol>

-events

-are generated.

-If backing-store will now be maintained, 

-a full-window exposure is always generated.

-Otherwise, only visible regions may be reported.

-Similar tiling and exposure take place for any newly viewable inferiors.

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>XMapWindow</primary></indexterm>

-If the window is an

-<symbol>InputOutput</symbol>

-window,

-<function>XMapWindow</function>

-generates 

-<symbol>Expose</symbol>

-events on each 

-<symbol>InputOutput</symbol>

-window that it causes to be displayed.

-If the client maps and paints the window 

-and if the client begins processing events, 

-the window is painted twice.

-To avoid this,

-first ask for 

-<symbol>Expose</symbol>

-events and then map the window,

-so the client processes input events as usual.

-The event list will include 

-<symbol>Expose</symbol>

-for each

-window that has appeared on the screen. 

-The client's normal response to

-an 

-<symbol>Expose</symbol>

-event should be to repaint the window.

-This method usually leads to simpler programs and to proper interaction

-with window managers.

-</para>

-<para>

-<!-- .LP -->

-<function>XMapWindow</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To map and raise a window, use

-<function>XMapRaised</function>.

-<indexterm significance="preferred"><primary>XMapRaised</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XMapRaised</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMapRaised</function>

-function

-essentially is similar to

-<function>XMapWindow</function>

-in that it maps the window and all of its

-subwindows that have had map requests.

-However, it also raises the specified window to the top of the stack.

-For additional information,

-see 

-<function>XMapWindow</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XMapRaised</function>

-can generate multiple

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To map all subwindows for a specified window, use 

-<function>XMapSubwindows</function>.

-<indexterm significance="preferred"><primary>XMapSubwindows</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XMapSubwindows</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMapSubwindows</function>

-<indexterm><primary>XMapSubwindows</primary></indexterm>

-function maps all subwindows for a specified window in top-to-bottom stacking 

-order.

-The X server generates

-<symbol>Expose</symbol>

-events on each newly displayed window.

-This may be much more efficient than mapping many windows

-one at a time because the server needs to perform much of the work

-only once, for all of the windows, rather than for each window.

-</para>

-<para>

-<!-- .LP -->

-<function>XMapSubwindows</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Unmapping_Windows">

-<title>Unmapping Windows</title>

-<!-- .XS -->

-<!-- (SN Unmapping Windows  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to unmap a window or all subwindows.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To unmap a window, use 

-<function>XUnmapWindow</function>.

-<indexterm significance="preferred"><primary>XUnmapWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUnmapWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUnmapWindow</function>

-function unmaps the specified window and causes the X server to generate an

-<symbol>UnmapNotify</symbol>

-<indexterm><primary>UnmapNotify Event</primary></indexterm>

-<indexterm><primary>XUnmapWindow</primary></indexterm>

-event.

-If the specified window is already unmapped, 

-<function>XUnmapWindow</function>

-has no effect.

-Normal exposure processing on formerly obscured windows is performed.

-Any child window will no longer be visible until another map call is

-made on the parent.

-In other words, the subwindows are still mapped but are not visible

-until the parent is mapped.

-Unmapping a window will generate 

-<symbol>Expose</symbol>

-events on windows that were formerly obscured by it.

-</para>

-<para>

-<!-- .LP -->

-<function>XUnmapWindow</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To unmap all subwindows for a specified window, use 

-<function>XUnmapSubwindows</function>.

-<indexterm significance="preferred"><primary>XUnmapSubwindows</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUnmapSubwindows</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUnmapSubwindows</function>

-function unmaps all subwindows for the specified window in bottom-to-top

-stacking order.

-It causes the X server to generate an

-<symbol>UnmapNotify</symbol>

-event on each subwindow and 

-<symbol>Expose</symbol>

-events on formerly obscured windows.

-<indexterm><primary>UnmapNotify Event</primary></indexterm>

-Using this function is much more efficient than unmapping multiple windows

-one at a time because the server needs to perform much of the work

-only once, for all of the windows, rather than for each window.

-</para>

-<para>

-<!-- .LP -->

-<function>XUnmapSubwindows</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Configuring_Windows">

-<title>Configuring Windows</title>

-<!-- .XS -->

-<!-- (SN Configuring Windows  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-</para>

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to

-move a window, resize a window, move and resize a window, or

-change a window's border width.

-To change one of these parameters,

-set the appropriate member of the

-<structname>XWindowChanges</structname>

-structure and OR in the corresponding value mask in subsequent calls to

-<function>XConfigureWindow</function>.

-The symbols for the value mask bits and the

-<structname>XWindowChanges</structname>

-structure are:

-<!-- .sM -->

-</para>

-<para>

-<!-- .LP -->

-

-<literallayout class="monospaced">

-/* Configure window value mask bits */

-#define      CWX              (1&lt;&lt;0)

-#define      CWY              (1&lt;&lt;1)

-#define      CWWidth          (1&lt;&lt;2)

-#define      CWHeight         (1&lt;&lt;3)

-#define      CWBorderWidth    (1&lt;&lt;4)

-#define      CWSibling        (1&lt;&lt;5)

-#define      CWStackMode      (1&lt;&lt;6)

-</literallayout>

-

-<indexterm significance="preferred"><primary>XWindowChanges</primary></indexterm>

-<literallayout class="monospaced">

-/* Values */

-

-typedef struct {

-     int x, y;

-     int width, height;

-     int border_width;

-     Window sibling;

-     int stack_mode;

-} XWindowChanges;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The x and y members are used to set the window's x and y coordinates,

-which are relative to the parent's origin

-and indicate the position of the upper-left outer corner of the window.

-The width and height members are used to set the inside size of the window,

-not including the border, and must be nonzero, or a

-<errorname>BadValue</errorname>

-error results.

-Attempts to configure a root window have no effect.

-</para>

-<para>

-<!-- .LP -->

-The border_width member is used to set the width of the border in pixels.

-Note that setting just the border width leaves the outer-left corner of the window

-in a fixed position but moves the absolute position of the window's origin.

-If you attempt to set the border-width attribute of an

-<symbol>InputOnly</symbol>

-window nonzero, a

-<errorname>BadMatch</errorname>

-error results. 

-</para>

-<para>

-<!-- .LP -->

-The sibling member is used to set the sibling window for stacking operations.

-The stack_mode member is used to set how the window is to be restacked 

-and can be set to

-<symbol>Above</symbol>,

-<symbol>Below</symbol>,

-<symbol>TopIf</symbol>,

-<symbol>BottomIf</symbol>,

-or 

-<symbol>Opposite</symbol>.

-</para>

-<para>

-<!-- .LP -->

-If the override-redirect flag of the window is

-<symbol>False</symbol>

-and if some other client has selected

-<symbol>SubstructureRedirectMask</symbol>

-on the parent, the X server generates a

-<symbol>ConfigureRequest</symbol>

-event, and no further processing is performed.

-Otherwise, 

-if some other client has selected 

-<symbol>ResizeRedirectMask</symbol>

-on the window and the inside

-width or height of the window is being changed,

-a 

-<symbol>ResizeRequest</symbol>

-event is generated, and the current inside width and height are

-used instead.

-Note that the override-redirect flag of the window has no effect

-on

-<symbol>ResizeRedirectMask</symbol>

-and that

-<symbol>SubstructureRedirectMask</symbol>

-on the parent has precedence over

-<symbol>ResizeRedirectMask</symbol>

-on the window.

-</para>

-<para>

-<!-- .LP -->

-When the geometry of the window is changed as specified, 

-the window is restacked among siblings, and a

-<symbol>ConfigureNotify</symbol>

-event is generated if the state of the window actually changes.

-<symbol>GravityNotify</symbol>

-events are generated after 

-<symbol>ConfigureNotify</symbol>

-events.

-If the inside width or height of the window has actually changed, 

-children of the window are affected as specified.

-</para>

-<para>

-<!-- .LP -->

-If a window's size actually changes,

-the window's subwindows move according to their window gravity.

-Depending on the window's bit gravity,

-the contents of the window also may be moved (see section 3.2.3).

-</para>

-<para>

-<!-- .LP -->

-If regions of the window were obscured but now are not,

-exposure processing is performed on these formerly obscured windows, 

-including the window itself and its inferiors. 

-As a result of increasing the width or height,

-exposure processing is also performed on any new regions of the window 

-and any regions where window contents are lost.

-</para>

-<para>

-<!-- .LP -->

-The restack check (specifically, the computation for 

-<symbol>BottomIf</symbol>,

-<symbol>TopIf</symbol>,

-and 

-<symbol>Opposite</symbol>)

-is performed with respect to the window's final size and position (as

-controlled by the other arguments of the request), not its initial position.

-If a sibling is specified without a stack_mode,

-a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-If a sibling and a stack_mode are specified, 

-the window is restacked as follows:

-</para>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>Above</symbol></entry>

-      <entry>The window is placed just above the sibling.</entry>

-    </row>

-    <row>

-      <entry><symbol>Below</symbol></entry>

-      <entry>The window is placed just below the sibling.</entry>

-    </row>

-    <row>

-      <entry><symbol>TopIf</symbol></entry>

-      <entry>If the sibling occludes the window, the window is placed at the top of the stack.</entry>

-    </row>

-    <row>

-      <entry><symbol>BottomIf</symbol></entry>

-      <entry>If the window occludes the sibling, the window is placed at the bottom of the stack.</entry>

-    </row>

-    <row>

-      <entry><symbol>Opposite</symbol></entry>

-      <entry>

-If the sibling occludes the window, the window is placed at the top of the stack.

-If the window occludes the sibling,

-the window is placed at the bottom of the stack.

-      </entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-If a stack_mode is specified but no sibling is specified,

-the window is restacked as follows:

-</para>

-

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>Above</symbol></entry>

-      <entry>The window is placed at the top of the stack.</entry>

-    </row>

-    <row>

-      <entry><symbol>Below</symbol></entry>

-      <entry>The window is placed at the bottom of the stack.</entry>

-    </row>

-    <row>

-      <entry><symbol>TopIf</symbol></entry>

-      <entry>

-If any sibling occludes the window, the window is placed at

-the top of the stack.

-      </entry>

-    </row>

-    <row>

-      <entry>

-If the window occludes any sibling, the window is placed at

-the bottom of the stack.

-      </entry>

-    </row>

-    <row>

-      <entry><symbol>Opposite</symbol></entry>

-      <entry>

-If any sibling occludes the window, the window

-is placed at the top of the stack.

-If the window occludes any sibling,

-the window is placed at the bottom of the stack.

-      </entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-Attempts to configure a root window have no effect.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To configure a window's size, location, stacking, or border, use

-<function>XConfigureWindow</function>.

-<indexterm significance="preferred"><primary>XConfigureWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XConfigureWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>

-  <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi to be reconfigured -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which values are to be set using information in

-the values structure.

-This mask is the bitwise inclusive OR of the valid configure window values bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>values</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XWindowChanges</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XConfigureWindow</function>

-function uses the values specified in the

-<structname>XWindowChanges</structname>

-structure to reconfigure a window's size, position, border, and stacking order.

-Values not specified are taken from the existing geometry of the window.

-</para>

-<para>

-<!-- .LP -->

-If a sibling is specified without a stack_mode or if the window

-is not actually a sibling,

-a

-<errorname>BadMatch</errorname>

-error results. 

-Note that the computations for

-<symbol>BottomIf</symbol>,

-<symbol>TopIf</symbol>,

-and

-<symbol>Opposite</symbol>

-are performed with respect to the window's final geometry (as controlled by the

-other arguments passed to

-<function>XConfigureWindow</function>),

-not its initial geometry.

-Any backing store contents of the window, its

-inferiors, and other newly visible windows are either discarded or

-changed to reflect the current screen contents 

-(depending on the implementation).

-</para>

-<para>

-<!-- .LP -->

-<function>XConfigureWindow</function>

-can generate

-<errorname>BadMatch</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To move a window without changing its size, use 

-<function>XMoveWindow</function>.

-<indexterm significance="preferred"><primary>XMoveWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XMoveWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN      -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi to be moved -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-<!-- .ds Xy , which define the new location of the top-left pixel \ -->

-of the window's border or the window itself if it has no border

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMoveWindow</function>

-function moves the specified window to the specified x and y coordinates,

-but it does not change the window's size, raise the window, or

-change the mapping state of the window.

-Moving a mapped window may or may not lose the window's contents 

-depending on if the window is obscured by nonchildren 

-and if no backing store exists.

-If the contents of the window are lost, 

-the X server generates

-<symbol>Expose</symbol>

-events.

-Moving a mapped window generates

-<symbol>Expose</symbol>

-events on any formerly obscured windows. 

-</para>

-<para>

-<!-- .LP -->

-If the override-redirect flag of the window is 

-<symbol>False</symbol>

-and some

-other client has selected 

-<symbol>SubstructureRedirectMask</symbol>

-on the parent, the X server generates a

-<symbol>ConfigureRequest</symbol>

-event, and no further processing is

-performed.  

-Otherwise, the window is moved.

-</para>

-<para>

-<!-- .LP -->

-<function>XMoveWindow</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change a window's size without changing the upper-left coordinate, use 

-<function>XResizeWindow</function>.

-<indexterm significance="preferred"><primary>XResizeWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XResizeWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-<!-- .ds Wh , which are the interior dimensions of the window \ -->

-after the call completes

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XResizeWindow</function>

-function changes the inside dimensions of the specified window, not including

-its borders.

-This function does not change the window's upper-left coordinate or

-the origin and does not restack the window.

-Changing the size of a mapped window may lose its contents and generate

-<symbol>Expose</symbol>

-events.

-If a mapped window is made smaller, 

-changing its size generates

-<symbol>Expose</symbol>

-events on windows that the mapped window formerly obscured.

-</para>

-<para>

-<!-- .LP -->

-If the override-redirect flag of the window is 

-<symbol>False</symbol>

-and some

-other client has selected 

-<symbol>SubstructureRedirectMask</symbol>

-on the parent, the X server generates a

-<symbol>ConfigureRequest</symbol>

-event, and no further processing is performed.  

-If either width or height is zero,

-a

-<errorname>BadValue</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XResizeWindow</function>

-can generate

-<errorname>BadValue</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change the size and location of a window, use 

-<function>XMoveResizeWindow</function>.

-<indexterm significance="preferred"><primary>XMoveResizeWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XMoveResizeWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi to be reconfigured -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-<!-- .ds Xy , which define the new position of the window relative to its parent -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which define the interior size of the window -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMoveResizeWindow</function>

-function changes the size and location of the specified window 

-without raising it.

-Moving and resizing a mapped window may generate an

-<symbol>Expose</symbol>

-event on the window.

-Depending on the new size and location parameters,

-moving and resizing a window may generate 

-<symbol>Expose</symbol>

-events on windows that the window formerly obscured. 

-</para>

-<para>

-<!-- .LP -->

-If the override-redirect flag of the window is 

-<symbol>False</symbol>

-and some

-other client has selected 

-<symbol>SubstructureRedirectMask</symbol>

-on the parent, the X server generates a

-<symbol>ConfigureRequest</symbol>

-event, and no further processing is performed.  

-Otherwise, the window size and location are changed.

-</para>

-<para>

-<!-- .LP -->

-<function>XMoveResizeWindow</function>

-can generate

-<errorname>BadValue</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change the border width of a given window, use

-<function>XSetWindowBorderWidth</function>.

-<indexterm significance="preferred"><primary>XSetWindowBorderWidth</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetWindowBorderWidth</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>unsignedint<parameter> width</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the width of the window border.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWindowBorderWidth</function>

-function sets the specified window's border width to the specified width.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWindowBorderWidth</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Changing_Window_Stacking_Order">

-<title>Changing Window Stacking Order</title>

-<!-- .XS -->

-<!-- (SN Changing Window Stacking Order  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-</para>

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to raise, lower, circulate,

-or restack windows.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To raise a window so that no sibling window obscures it, use 

-<function>XRaiseWindow</function>.

-<indexterm significance="preferred"><primary>XRaiseWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRaiseWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRaiseWindow</function>

-function

-raises the specified window to the top of the stack so that no sibling window

-obscures it.

-If the windows are regarded as overlapping sheets of paper stacked 

-on a desk,

-then raising a window is analogous to moving the sheet to the top of

-the stack but leaving its x and y location on the desk constant.

-Raising a mapped window may generate 

-<symbol>Expose</symbol>

-events for the window and any mapped subwindows that were formerly obscured.  

-</para>

-<para>

-<!-- .LP -->

-If the override-redirect attribute of the window is 

-<symbol>False</symbol>

-and some

-other client has selected 

-<symbol>SubstructureRedirectMask</symbol>

-on the parent, the X server generates a

-<symbol>ConfigureRequest</symbol>

-event, and no processing is performed.

-Otherwise, the window is raised.

-</para>

-<para>

-<!-- .LP -->

-<function>XRaiseWindow</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To lower a window so that it does not obscure any sibling windows, use 

-<function>XLowerWindow</function>.

-<indexterm significance="preferred"><primary>XLowerWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XLowerWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLowerWindow</function>

-function lowers the specified window to the bottom of the stack

-so that it does not obscure any sibling

-windows.

-If the windows are regarded as overlapping sheets of paper

-stacked on a desk, then lowering a window is analogous to moving the

-sheet to the bottom of the stack but leaving its x and y location on

-the desk constant.

-Lowering a mapped window will generate 

-<symbol>Expose</symbol>

-events on any windows it formerly obscured.

-</para>

-<para>

-<!-- .LP -->

-If the override-redirect attribute of the window is 

-<symbol>False</symbol>

-and some

-other client has selected 

-<symbol>SubstructureRedirectMask</symbol>

-on the parent, the X server generates a

-<symbol>ConfigureRequest</symbol>

-event, and no processing is performed.  

-Otherwise, the window is lowered to the bottom of the

-stack.

-</para>

-<para>

-<!-- .LP -->

-<function>XLowerWindow</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To circulate a subwindow up or down, use

-<function>XCirculateSubwindows</function>.

-<indexterm significance="preferred"><primary>XCirculateSubwindows</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XCirculateSubwindows</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> direction</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>direction</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the direction (up or down) that you want to circulate

-the window. 

-You can pass 

-<symbol>RaiseLowest</symbol>

-or

-<symbol>LowerHighest</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCirculateSubwindows</function>

-function circulates children of the specified window in the specified 

-direction.

-If you specify

-<symbol>RaiseLowest</symbol>,

-<function>XCirculateSubwindows</function>

-raises the lowest mapped child (if any) that is occluded 

-by another child to the top of the stack.

-If you specify

-<symbol>LowerHighest</symbol>,

-<function>XCirculateSubwindows</function>

-lowers the highest mapped child (if any) that occludes another child

-to the bottom of the stack.

-Exposure processing is then performed on formerly obscured windows.

-If some other client has selected 

-<symbol>SubstructureRedirectMask</symbol>

-on the window, the X server generates a 

-<symbol>CirculateRequest</symbol>

-event, and no further processing is performed.

-If a child is actually restacked,

-the X server generates a

-<symbol>CirculateNotify</symbol>

-event. 

-</para>

-<para>

-<!-- .LP -->

-<function>XCirculateSubwindows</function>

-can generate

-<errorname>BadValue</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To raise the lowest mapped child of a window that is partially or completely

-occluded by another child, use

-<function>XCirculateSubwindowsUp</function>.

-<indexterm significance="preferred"><primary>XCirculateSubwindowsUp</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XCirculateSubwindowsUp</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCirculateSubwindowsUp</function>

-function raises the lowest mapped child of the specified window that

-is partially

-or completely

-occluded by another child.

-Completely unobscured children are not affected.

-This is a convenience function equivalent to

-<function>XCirculateSubwindows</function>

-with

-<symbol>RaiseLowest</symbol>

-specified.

-</para>

-<para>

-<!-- .LP -->

-<function>XCirculateSubwindowsUp</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To lower the highest mapped child of a window that partially or 

-completely occludes another child, use 

-<function>XCirculateSubwindowsDown</function>.

-<indexterm significance="preferred"><primary>XCirculateSubwindowsDown</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XCirculateSubwindowsDown</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCirculateSubwindowsDown</function>

-function lowers the highest mapped child of the specified window that partially

-or completely occludes another child.

-Completely unobscured children are not affected.

-This is a convenience function equivalent to

-<function>XCirculateSubwindows</function>

-with

-<symbol>LowerHighest</symbol>

-specified.

-</para>

-<para>

-<!-- .LP -->

-<function>XCirculateSubwindowsDown</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To restack a set of windows from top to bottom, use 

-<function>XRestackWindows</function>.

-<indexterm significance="preferred"><primary>XRestackWindows</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRestackWindows</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> windows[]</parameter></paramdef>

-  <paramdef>int<parameter> nwindows</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>windows</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array containing the windows to be restacked.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nwindows</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of windows to be restacked.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRestackWindows</function>

-function restacks the windows in the order specified,

-from top to bottom.

-The stacking order of the first window in the windows array is unaffected,

-but the other windows in the array are stacked underneath the first window,

-in the order of the array.

-The stacking order of the other windows is not affected.

-For each window in the window array that is not a child of the specified window,

-a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-If the override-redirect attribute of a window is 

-<symbol>False</symbol>

-and some

-other client has selected 

-<symbol>SubstructureRedirectMask</symbol>

-on the parent, the X server generates 

-<symbol>ConfigureRequest</symbol>

-events for each window whose override-redirect flag is not set, 

-and no further processing is performed.

-Otherwise, the windows will be restacked in top-to-bottom order.

-</para>

-<para>

-<!-- .LP -->

-<function>XRestackWindows</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Changing_Window_Attributes">

-<title>Changing Window Attributes</title>

-<!-- .XS -->

-<!-- (SN Changing Window Attributes  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-</para>

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set window attributes.

-<function>XChangeWindowAttributes</function>

-is the more general function that allows you to set one or more window

-attributes provided by the

-<structname>XSetWindowAttributes</structname>

-structure.

-The other functions described in this section allow you to set one specific

-window attribute, such as a window's background.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change one or more attributes for a given window, use

-<function>XChangeWindowAttributes</function>.

-<indexterm significance="preferred"><primary>XChangeWindowAttributes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XChangeWindowAttributes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

-  <paramdef>XSetWindowAttributes<parameter> *attributes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>valuemask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which window attributes are defined in the attributes

-argument.

-This mask is the bitwise inclusive OR of the valid attribute mask bits.

-If valuemask is zero,

-the attributes are ignored and are not referenced.

-The values and restrictions are

-the same as for

-<function>XCreateWindow</function>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      

-    </term>

-    <listitem>

-      <para>

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>attributes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the structure from which the values (as specified by the value mask)

-are to be taken.

-The value mask should have the appropriate bits

-set to indicate which attributes have been set in the structure 

-(see section 3.2).

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Depending on the valuemask,

-the

-<function>XChangeWindowAttributes</function>

-function uses the window attributes in the

-<structname>XSetWindowAttributes</structname>

-structure to change the specified window attributes.

-Changing the background does not cause the window contents to be

-changed.

-To repaint the window and its background, use 

-<function>XClearWindow</function>.

-Setting the border or changing the background such that the

-border tile origin changes causes the border to be repainted.

-Changing the background of a root window to 

-<symbol>None</symbol>

-or 

-<symbol>ParentRelative</symbol>

-restores the default background pixmap.

-Changing the border of a root window to

-<symbol>CopyFromParent</symbol>

-restores the default border pixmap.

-Changing the win-gravity does not affect the current position of the

-window.

-Changing the backing-store of an obscured window to 

-<symbol>WhenMapped</symbol>

-or

-<symbol>Always</symbol>,

-or changing the backing-planes, backing-pixel, or

-save-under of a mapped window may have no immediate effect.

-Changing the colormap of a window (that is, defining a new map, not

-changing the contents of the existing map) generates a 

-<symbol>ColormapNotify</symbol>

-event.

-Changing the colormap of a visible window may have no

-immediate effect on the screen because the map may not be installed

-(see

-<function>XInstallColormap</function>).

-Changing the cursor of a root window to 

-<symbol>None</symbol>

-restores the default

-cursor.

-Whenever possible, you are encouraged to share colormaps.

-</para>

-<para>

-<!-- .LP -->

-Multiple clients can select input on the same window. 

-Their event masks are maintained separately.

-When an event is generated, 

-it is reported to all interested clients. 

-However, only one client at a time can select for 

-<symbol>SubstructureRedirectMask</symbol>,

-<symbol>ResizeRedirectMask</symbol>,

-and

-<symbol>ButtonPressMask</symbol>.

-If a client attempts to select any of these event masks 

-and some other client has already selected one, 

-a

-<errorname>BadAccess</errorname>

-error results.

-There is only one do-not-propagate-mask for a window, 

-not one per client.

-</para>

-<para>

-<!-- .LP -->

-<function>XChangeWindowAttributes</function>

-can generate

-<errorname>BadAccess</errorname>,

-<errorname>BadColor</errorname>,

-<errorname>BadCursor</errorname>,

-<errorname>BadMatch</errorname>,

-<errorname>BadPixmap</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the background of a window to a given pixel, use 

-<function>XSetWindowBackground</function>.

-<indexterm significance="preferred"><primary>XSetWindowBackground</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetWindowBackground</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> background_pixel</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>background_pixel</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the pixel that is to be used for the background.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWindowBackground</function>

-function sets the background of the window to the specified pixel value.

-Changing the background does not cause the window contents to be changed.

-<function>XSetWindowBackground</function>

-uses a pixmap of undefined size filled with the pixel value you passed.

-If you try to change the background of an 

-<symbol>InputOnly</symbol>

-window, a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWindowBackground</function>

-can generate

-<errorname>BadMatch</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set the background of a window to a given pixmap, use 

-<function>XSetWindowBackgroundPixmap</function>.

-<indexterm><primary>Window</primary><secondary>background</secondary></indexterm>

-<indexterm significance="preferred"><primary>XSetWindowBackgroundPixmap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetWindowBackgroundPixmap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Pixmap<parameter> background_pixmap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>background_pixmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the background pixmap,

-<symbol>ParentRelative</symbol>,

-or

-<symbol>None</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>

-<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>

-The

-<function>XSetWindowBackgroundPixmap</function>

-function sets the background pixmap of the window to the specified pixmap.

-The background pixmap can immediately be freed if no further explicit

-references to it are to be made.

-If 

-<symbol>ParentRelative</symbol>

-is specified, 

-the background pixmap of the window's parent is used,

-or on the root window, the default background is restored.

-If you try to change the background of an 

-<symbol>InputOnly</symbol>

-window, a

-<errorname>BadMatch</errorname>

-error results.

-If the background is set to

-<symbol>None</symbol>,

-the window has no defined background.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWindowBackgroundPixmap</function>

-can generate

-<errorname>BadMatch</errorname>,

-<errorname>BadPixmap</errorname>,

-and 

-<errorname>BadWindow</errorname>

-errors.

-<!-- .NT Note -->

-<function>XSetWindowBackground</function>

-and

-<function>XSetWindowBackgroundPixmap</function>

-do not change the current contents of the window.

-<!-- .NE -->

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change and repaint a window's border to a given pixel, use 

-<function>XSetWindowBorder</function>.

-<indexterm significance="preferred"><primary>XSetWindowBorder</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetWindowBorder</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> border_pixel</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>border_pixel</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the entry in the colormap. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWindowBorder</function>

-function sets the border of the window to the pixel value you specify.

-If you attempt to perform this on an

-<symbol>InputOnly</symbol>

-window, a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWindowBorder</function>

-can generate

-<errorname>BadMatch</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change and repaint the border tile of a given window, use 

-<function>XSetWindowBorderPixmap</function>.

-<indexterm significance="preferred"><primary>XSetWindowBorderPixmap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetWindowBorderPixmap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Pixmap<parameter> border_pixmap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>border_pixmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the border pixmap or

-<symbol>CopyFromParent</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWindowBorderPixmap</function>

-function sets the border pixmap of the window to the pixmap you specify.

-The border pixmap can be freed immediately if no further explicit

-references to it are to be made.

-If you specify

-<symbol>CopyFromParent</symbol>,

-a copy of the parent window's border pixmap is used.

-If you attempt to perform this on an

-<symbol>InputOnly</symbol>

-window, a

-<errorname>BadMatch</errorname>

-error results.

-<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>

-<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWindowBorderPixmap</function>

-can generate

-<errorname>BadMatch</errorname>,

-<errorname>BadPixmap</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the colormap of a given window, use

-<function>XSetWindowColormap</function>.

-<indexterm significance="preferred"><primary>XSetWindowColormap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetWindowColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWindowColormap</function>

-function sets the specified colormap of the specified window.

-The colormap must have the same visual type as the window,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWindowColormap</function>

-can generate

-<errorname>BadColor</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To define which cursor will be used in a window, use

-<function>XDefineCursor</function>.

-<indexterm><primary>Window</primary><secondary>defining the cursor</secondary></indexterm>

-<indexterm significance="preferred"><primary>XDefineCursor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDefineCursor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>cursor</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the cursor that is to be displayed or

-<symbol>None</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If a cursor is set, it will be used when the pointer is in the window.

-If the cursor is

-<symbol>None</symbol>,

-it is equivalent to

-<function>XUndefineCursor</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XDefineCursor</function>

-can generate

-<errorname>BadCursor</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To undefine the cursor in a given window, use

-<function>XUndefineCursor</function>.

-<indexterm><primary>Window</primary><secondary>undefining the cursor</secondary></indexterm>

-<indexterm significance="preferred"><primary>XUndefineCursor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUndefineCursor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUndefineCursor</function>

-function undoes the effect of a previous

-<function>XDefineCursor</function>

-for this window.

-When the pointer is in the window,

-the parent's cursor will now be used.

-On the root window,

-the default cursor is restored.

-</para>

-<para>

-<!-- .LP -->

-<function>XUndefineCursor</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-<!-- .bp -->

-

-</para>

-</sect1>

-</chapter>

+<?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="window_functions"><title>Window Functions</title>
+<sect1 id="Visual_Types">
+<title>Visual Types</title>
+<!-- .XS -->
+<!-- (SN Visual Types -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Visual Type</primary></indexterm>
+On some display hardware, 
+it may be possible to deal with color resources in more than one way.
+For example, you may be able to deal with a screen of either 12-bit depth
+with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth
+with 8 bits of the pixel dedicated to each of red, green, and blue.
+These different ways of dealing with the visual aspects of the screen
+are called visuals.
+For each screen of the display, there may be a list of valid visual types
+supported at different depths of the screen.
+Because default windows and visual types are defined for each screen,
+most simple applications need not deal with this complexity.
+Xlib provides macros and functions that return the default root window, 
+the default depth of the default root window, and the default visual type
+(see sections 2.2.1 and 16.7).
+</para>
+<para>
+<!-- .LP -->
+Xlib uses an opaque 
+<structname>Visual</structname>
+<indexterm significance="preferred"><primary>Visual</primary></indexterm>
+structure that contains information about the possible color mapping.
+The visual utility functions (see section 16.7) use an
+<structname>XVisualInfo</structname>
+structure to return this information to an application.
+The members of this structure pertinent to this discussion are class, red_mask,
+green_mask, blue_mask, bits_per_rgb, and colormap_size.
+The class member specifies one of the possible visual classes of the screen
+and can be 
+<indexterm><primary>Visual Classes</primary><secondary>StaticGray</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>StaticColor</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>TrueColor</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>StaticColor</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>GrayScale</secondary></indexterm>
+<indexterm><primary>Visual Classes</primary><secondary>PseudoColor</secondary></indexterm>
+<symbol>StaticGray</symbol>,
+<symbol>StaticColor</symbol>,
+<symbol>TrueColor</symbol>,
+<symbol>GrayScale</symbol>,
+<symbol>PseudoColor</symbol>,
+or
+<symbol>DirectColor</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The following concepts may serve to make the explanation of
+visual types clearer. 
+The screen can be color or grayscale,
+can have a colormap that is writable or read-only,
+and can also have a colormap whose indices are decomposed into separate 
+<acronym>RGB</acronym> pieces, provided one is not on a grayscale screen.
+This leads to the following diagram:
+</para>
+
+<literallayout class="monospaced">
+                      Color        Gray-Scale
+                   R/O    R/W      R/O   R/W
+----------------------------------------------
+ Undecomposed    Static  Pseudo   Static  Gray
+   Colormap      Color   Color    Gray    Scale
+
+ Decomposed       True   Direct
+   Colormap       Color  Color
+----------------------------------------------
+</literallayout>
+
+<para>
+<!-- .LP -->
+Conceptually, 
+as each pixel is read out of video memory for display on the screen,
+it goes through a look-up stage by indexing into a colormap.
+Colormaps can be manipulated arbitrarily on some hardware, 
+in limited ways on other hardware, and not at all on other hardware.  
+The visual types affect the colormap and 
+the <acronym>RGB</acronym> values in the following ways:
+</para>
+<para>
+<!-- .LP -->
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+For 
+<symbol>PseudoColor</symbol>,
+a pixel value indexes a colormap to produce
+independent <acronym>RGB</acronym> values, and the <acronym>RGB</acronym> values can be changed dynamically.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<symbol>GrayScale</symbol>
+is treated the same way as 
+<symbol>PseudoColor</symbol>
+except that the primary that drives the screen is undefined. 
+Thus, the client should always store the
+same value for red, green, and blue in the colormaps.  
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+For 
+<symbol>DirectColor</symbol>,
+a pixel value is decomposed into separate <acronym>RGB</acronym> subfields, and each
+subfield separately indexes the colormap for the corresponding value.
+The <acronym>RGB</acronym> values can be changed dynamically.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<symbol>TrueColor</symbol>
+is treated the same way as 
+<symbol>DirectColor</symbol>
+except that the colormap has predefined, read-only <acronym>RGB</acronym> values.
+These <acronym>RGB</acronym> values are server dependent but provide linear or near-linear
+ramps in each primary.  
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<symbol>StaticColor</symbol>
+is treated the same way as 
+<symbol>PseudoColor</symbol>
+except that the colormap has predefined, 
+read-only, server-dependent <acronym>RGB</acronym> values.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<symbol>StaticGray</symbol>
+is treated the same way as 
+<symbol>StaticColor</symbol>
+except that the <acronym>RGB</acronym> values are equal for any single pixel
+value, thus resulting in shades of gray.  
+<symbol>StaticGray</symbol>
+with a two-entry
+colormap can be thought of as monochrome.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The red_mask, green_mask, and blue_mask members are only defined for
+<symbol>DirectColor</symbol>
+and 
+<symbol>TrueColor</symbol>.
+Each has one contiguous set of bits with no
+intersections.
+The bits_per_rgb member specifies the log base 2 of the
+number of distinct color values (individually) of red, green, and blue.
+Actual <acronym>RGB</acronym> values are unsigned 16-bit numbers.
+The colormap_size member defines the number of available colormap entries
+in a newly created colormap.  
+For 
+<symbol>DirectColor</symbol>
+and 
+<symbol>TrueColor</symbol>,
+this is the size of an individual pixel subfield.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the visual ID from a 
+<structname>Visual</structname>,
+use
+<function>XVisualIDFromVisual</function>.
+<indexterm significance="preferred"><primary>XVisualIDFromVisual</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xvisualidfromvisual'>
+<funcprototype>
+  <funcdef>VisualID <function>XVisualIDFromVisual</function></funcdef>
+  <paramdef>Visual *<parameter>visual</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>visual</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the visual type.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XVisualIDFromVisual</function>
+function returns the visual ID for the specified visual type.
+</para>
+</sect1>
+<sect1 id="Window_Attributes">
+<title>Window Attributes</title>
+<!-- .XS -->
+<!-- (SN Window Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Window</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>attributes</secondary></indexterm>
+All 
+<symbol>InputOutput</symbol>
+windows have a border width of zero or more pixels, an optional background, 
+an event suppression mask (which suppresses propagation of events from 
+children), and a property list (see section 4.3).
+The window border and background can be a solid color or a pattern, called
+a tile.
+All windows except the root have a parent and are clipped by their parent.
+If a window is stacked on top of another window, it obscures that other
+window for the purpose of input.
+If a window has a background (almost all do), it obscures the other
+window for purposes of output.
+Attempts to output to the obscured area do nothing, 
+and no input events (for example, pointer motion) are generated for the 
+obscured area.
+</para>
+<para>
+<!-- .LP -->
+Windows also have associated property lists (see section 4.3).
+</para>
+<para>
+<!-- .LP -->
+Both
+<symbol>InputOutput</symbol>
+and
+<symbol>InputOnly</symbol>
+windows have the following common attributes,
+which are the only attributes of an
+<symbol>InputOnly</symbol>
+window:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+win-gravity
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+event-mask
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+do-not-propagate-mask
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+override-redirect
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+cursor
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If you specify any other attributes for an
+<symbol>InputOnly</symbol>
+window,
+a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<symbol>InputOnly</symbol>
+windows are used for controlling input events in situations where
+<symbol>InputOutput</symbol>
+windows are unnecessary.
+<symbol>InputOnly</symbol>
+windows are invisible; can only be used to control such things as
+cursors, input event generation, and grabbing;
+and cannot be used in any graphics requests.
+Note that
+<symbol>InputOnly</symbol>
+windows cannot have
+<symbol>InputOutput</symbol>
+windows as inferiors.
+</para>
+<para>
+<!-- .LP -->
+Windows have borders of a programmable width and pattern
+as well as a background pattern or tile.
+<indexterm><primary>Tile</primary><secondary>pixmaps</secondary></indexterm>
+Pixel values can be used for solid colors.
+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>
+The background and border pixmaps can be destroyed immediately after
+creating the window if no further explicit references to them
+are to be made.
+<indexterm ><primary>Tile</primary><secondary>mode</secondary></indexterm>
+The pattern can either be relative to the parent 
+or absolute.
+If
+<symbol>ParentRelative</symbol>,
+the parent's background is used.
+</para>
+<para>
+<!-- .LP -->
+When windows are first created, 
+they are not visible (not mapped) on the screen.
+Any output to a window that is not visible on the screen 
+and that does not have backing store will be discarded.
+<indexterm><primary>Window</primary><secondary>mapping</secondary></indexterm>
+An application may wish to create a window long before it is
+mapped to the screen.
+When a window is eventually mapped to the screen 
+(using
+<function>XMapWindow</function>),
+<indexterm><primary>XMapWindow</primary></indexterm>
+the X server generates an 
+<symbol>Expose</symbol>
+event for the window if backing store has not been maintained.
+</para>
+<para>
+<!-- .LP -->
+A window manager can override your choice of size, 
+border width, and position for a top-level window.
+Your program must be prepared to use the actual size and position
+of the top window.
+It is not acceptable for a client application to resize itself
+unless in direct response to a human command to do so.
+Instead, either your program should use the space given to it,
+or if the space is too small for any useful work, your program
+might ask the user to resize the window.
+The border of your top-level window is considered fair game 
+for window managers.
+</para>
+<para>
+<!-- .LP -->
+To set an attribute of a window,
+set the appropriate member of the
+<structname>XSetWindowAttributes</structname>
+structure and OR in the corresponding value bitmask in your subsequent calls to
+<function>XCreateWindow</function>
+and
+<function>XChangeWindowAttributes</function>,
+or use one of the other convenience functions that set the appropriate 
+attribute.
+The symbols for the value mask bits and the
+<structname>XSetWindowAttributes</structname>
+structure are:
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+/* Window attribute value mask bits */
+
+
+<literallayout class="monospaced">
+/* Window attribute value mask bits */
+#define    CWBackPixmap                    (1L&lt;&lt;0)
+#define    CWBackPixel                     (1L&lt;&lt;1)
+#define    CWBorderPixmap                  (1L&lt;&lt;2)
+#define    CWBorderPixel                   (1L&lt;&lt;3)
+#define    CWBitGravity                    (1L&lt;&lt;4)
+#define    CWWinGravity                    (1L&lt;&lt;5)
+#define    CWBackingStore                  (1L&lt;&lt;6)
+#define    CWBackingPlanes                 (1L&lt;&lt;7)
+#define    CWBackingPixel                  (1L&lt;&lt;8)
+#define    CWOverrideRedirect              (1L&lt;&lt;9)
+#define    CWSaveUnder                     (1L&lt;&lt;10)
+#define    CWEventMask                     (1L&lt;&lt;11)
+#define    CWDontPropagate                 (1L&lt;&lt;12)
+#define    CWColormap                      (1L&lt;&lt;13)
+#define    CWCursor                        (1L&lt;&lt;14)
+</literallayout>
+
+<indexterm significance="preferred"><primary>XSetWindowAttributes</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+/* Values */
+
+typedef struct {
+     Pixmap background_pixmap;     /* background, None, or ParentRelative */
+     unsigned long background_pixel;     /* background pixel */
+     Pixmap border_pixmap;          /* border of the window or CopyFromParent */
+     unsigned long border_pixel;     /* border pixel value */
+     int bit_gravity;     /* one of bit gravity values */
+     int win_gravity;     /* one of the window gravity values */
+     int backing_store;     /* NotUseful, WhenMapped, Always */
+     unsigned long backing_planes;     /* planes to be preserved if possible */
+     unsigned long backing_pixel;     /* value to use in restoring planes */
+     Bool save_under;     /* should bits under be saved? (popups) */
+     long event_mask;     /* set of events that should be saved */
+     long do_not_propagate_mask;     /* set of events that should not propagate */
+     Bool override_redirect;     /* boolean value for override_redirect */
+     Colormap colormap;     /* color map to be associated with window */
+     Cursor cursor;          /* cursor to be displayed (or None) */
+} XSetWindowAttributes;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The following lists the defaults for each window attribute and indicates
+whether the attribute is applicable to
+<symbol>InputOutput</symbol>
+and
+<symbol>InputOnly</symbol>
+windows:
+</para>
+<informaltable>
+  <tgroup cols='4' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <colspec colname='c4'/>
+  <thead>
+    <row>
+      <entry>Attribute</entry>
+      <entry>Default</entry>
+      <entry>InputOutput</entry>
+      <entry>nputOnly</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>background-pixmap</entry>
+      <entry><symbol>None</symbol></entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>background-pixel</entry>
+      <entry>Undefined</entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>border-pixmap</entry>
+      <entry><symbol>CopyFromParent</symbol></entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>border-pixel</entry>
+      <entry>Undefined</entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>bit-gravity</entry>
+      <entry><symbol>ForgetGravity</symbol></entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>win-gravity</entry>
+      <entry><symbol>NorthWestGravity</symbol></entry>
+      <entry>Yes</entry>
+      <entry>Yes</entry>
+    </row>
+    <row>
+      <entry>backing-store</entry>
+      <entry><symbol>NotUseful</symbol></entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>backing-planes</entry>
+      <entry>All ones</entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>backing-pixel</entry>
+      <entry>zero</entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>save-under</entry>
+      <entry><symbol>False</symbol></entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>event-mask</entry>
+      <entry>empty set</entry>
+      <entry>Yes</entry>
+      <entry>Yes</entry>
+    </row>
+    <row>
+      <entry>do-not-propagate-mask</entry>
+      <entry>empty set</entry>
+      <entry>Yes</entry>
+      <entry>Yes</entry>
+    </row>
+    <row>
+      <entry>override-redirect</entry>
+      <entry><symbol>False</symbol></entry>
+      <entry>Yes</entry>
+      <entry>Yes</entry>
+    </row>
+    <row>
+      <entry>colormap</entry>
+      <entry><symbol>CopyFromParent</symbol></entry>
+      <entry>Yes</entry>
+      <entry>No</entry>
+    </row>
+    <row>
+      <entry>cursor</entry>
+      <entry><symbol>None</symbol></entry>
+      <entry>Yes</entry>
+      <entry>Yes</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<sect2 id="Background_Attribute">
+<title>Background Attribute</title>
+<!-- .XS -->
+<!-- (SN Background Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Only
+<symbol>InputOutput</symbol>
+windows can have a background.
+You can set the background of an
+<symbol>InputOutput</symbol>
+window by using a pixel or a pixmap.
+</para>
+<para>
+<!-- .LP -->
+The background-pixmap attribute of a window specifies the pixmap to be used for 
+a window's background.
+This pixmap can be of any size, although some sizes may be faster than others.
+The background-pixel attribute of a window specifies a pixel value used to paint
+a window's background in a single color.
+</para>
+<para>
+<!-- .LP -->
+You can set the background-pixmap to a pixmap,  
+<symbol>None</symbol>
+(default), or 
+<symbol>ParentRelative</symbol>.
+You can set the background-pixel of a window to any pixel value (no default).
+If you specify a background-pixel, 
+it overrides either the default background-pixmap
+or any value you may have set in the background-pixmap.
+A pixmap of an undefined size that is filled with the background-pixel is used 
+for the background.
+Range checking is not performed on the background pixel;
+it simply is truncated to the appropriate number of bits.
+</para>
+<para>
+<!-- .LP -->
+If you set the background-pixmap,
+it overrides the default.
+The background-pixmap and the window must have the same depth,
+or a
+<errorname>BadMatch</errorname>
+error results.
+If you set background-pixmap to
+<symbol>None</symbol>,
+the window has no defined background.  
+If you set the background-pixmap to
+<symbol>ParentRelative</symbol>:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The parent window's background-pixmap is used. 
+The child window, however, must have the same depth as 
+its parent,
+or a
+<errorname>BadMatch</errorname>
+error results.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the parent window has a background-pixmap of
+<symbol>None</symbol>,
+the window also has a background-pixmap of
+<symbol>None</symbol>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A copy of the parent window's background-pixmap is not made.
+The parent's background-pixmap is examined each time the child window's 
+background-pixmap is required.  
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The background tile origin always aligns with the parent window's
+background tile origin. 
+If the background-pixmap is not
+<symbol>ParentRelative</symbol>,
+the background tile origin is the child window's origin.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Setting a new background, whether by setting background-pixmap or
+background-pixel, overrides any previous background.
+The background-pixmap can be freed immediately if no further explicit reference
+is made to it (the X server will keep a copy to use when needed).
+If you later draw into the pixmap used for the background,
+what happens is undefined because the
+X implementation is free to make a copy of the pixmap or
+to use the same pixmap.
+</para>
+<para>
+<!-- .LP -->
+When no valid contents are available for regions of a window
+and either the regions are visible or the server is maintaining backing store,
+the server automatically tiles the regions with the window's background
+unless the window has a background of
+<symbol>None</symbol>.
+If the background is
+<symbol>None</symbol>,
+the previous screen contents from other windows of the same depth as the window
+are simply left in place as long as the contents come from the parent of the
+window or an inferior of the parent.
+Otherwise, the initial contents of the exposed regions are undefined.
+<symbol>Expose</symbol>
+events are then generated for the regions, even if the background-pixmap
+is
+<symbol>None</symbol>
+(see section 10.9).
+</para>
+</sect2>
+<sect2 id="Border_Attribute">
+<title>Border Attribute</title>
+<!-- .XS -->
+<!-- (SN Border Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Only
+<symbol>InputOutput</symbol>
+windows can have a border.
+You can set the border of an
+<symbol>InputOutput</symbol>
+window by using a pixel or a pixmap.
+</para>
+<para>
+<!-- .LP -->
+The border-pixmap attribute of a window specifies the pixmap to be used 
+for a window's border.
+The border-pixel attribute of a window specifies a pixmap of undefined size 
+filled with that pixel be used for a window's border. 
+Range checking is not performed on the background pixel;
+it simply is truncated to the appropriate number of bits.
+The border tile origin is always the same as the background tile origin.
+</para>
+<para>
+<!-- .LP -->
+You can also set the border-pixmap to a pixmap of any size (some may be faster
+than others) or to
+<symbol>CopyFromParent</symbol>
+(default).
+You can set the border-pixel to any pixel value (no default).
+</para>
+<para>
+<!-- .LP -->
+If you set a border-pixmap, 
+it overrides the default.
+The border-pixmap and the window must have the same depth,
+or a
+<errorname>BadMatch</errorname>
+error results.
+If you set the border-pixmap to 
+<symbol>CopyFromParent</symbol>,
+the parent window's border-pixmap is copied.
+Subsequent changes to the parent window's border attribute do not affect 
+the child window.
+However, the child window must have the same depth as the parent window,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The border-pixmap can be freed immediately if no further explicit reference
+is made to it.
+If you later draw into the pixmap used for the border,
+what happens is undefined because the
+X implementation is free either to make a copy of the pixmap or
+to use the same pixmap.
+If you specify a border-pixel, 
+it overrides either the default border-pixmap
+or any value you may have set in the border-pixmap.
+All pixels in the window's border will be set to the border-pixel.
+Setting a new border, whether by setting border-pixel or by setting
+border-pixmap, overrides any previous border.
+</para>
+<para>
+<!-- .LP -->
+Output to a window is always clipped to the inside of the window. 
+Therefore, graphics operations never affect the window border.
+</para>
+</sect2>
+<sect2 id="Gravity_Attributes">
+<title>Gravity Attributes</title>
+<!-- .XS -->
+<!-- (SN Gravity Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The bit gravity of a window defines which region of the window should be 
+retained when an
+<symbol>InputOutput</symbol>
+window is resized. 
+The default value for the bit-gravity attribute is 
+<symbol>ForgetGravity</symbol>.
+The window gravity of a window allows you to define how the 
+<symbol>InputOutput</symbol>
+or
+<symbol>InputOnly</symbol>
+window should be repositioned if its parent is resized.  
+The default value for the win-gravity attribute is 
+<symbol>NorthWestGravity</symbol>.
+</para>
+<para>
+<!-- .LP -->
+If the inside width or height of a window is not changed 
+and if the window is moved or its border is changed, 
+then the contents of the window are not lost but move with the window.
+Changing the inside width or height of the window causes its contents to be
+moved or lost (depending on the bit-gravity of the window) and causes
+children to be reconfigured (depending on their win-gravity).
+For a
+change of width and height, the (x, y) pairs are defined:
+</para>
+<para>
+<!-- .LP -->
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry>Gravity Direction</entry>
+      <entry>Coordinates</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry><symbol>NorthWestGravity</symbol></entry>
+      <entry>(0, 0)</entry>
+    </row>
+    <row>
+      <entry><symbol>NorthGravity</symbol></entry>
+      <entry>(Width/2, 0)</entry>
+    </row>
+    <row>
+      <entry><symbol>NorthEastGravity</symbol></entry>
+      <entry>(Width, 0)</entry>
+    </row>
+    <row>
+      <entry><symbol>WestGravity</symbol></entry>
+      <entry>(0, Height/2)</entry>
+    </row>
+    <row>
+      <entry><symbol>CenterGravity</symbol></entry>
+      <entry>(Width/2, Height/2)</entry>
+    </row>
+    <row>
+      <entry><symbol>EastGravity</symbol></entry>
+      <entry>(Width, Height/2)</entry>
+    </row>
+    <row>
+      <entry><symbol>SouthWestGravity</symbol></entry>
+      <entry>(0, Height)</entry>
+    </row>
+    <row>
+      <entry><symbol>SouthGravity</symbol></entry>
+      <entry>(Width/2, Height)</entry>
+    </row>
+    <row>
+      <entry><symbol>SouthEastGravity</symbol></entry>
+      <entry>(Width, Height)</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+</para>
+<para>
+<!-- .LP -->
+When a window with one of these bit-gravity values is resized, 
+the corresponding pair
+defines the change in position of each pixel in the window.
+When a window with one of these win-gravities has its parent window resized,
+the corresponding pair defines the change in position of the window 
+within the parent.
+When a window is so repositioned, a
+<symbol>GravityNotify</symbol>
+event is generated (see section 10.10.5).
+</para>
+<para>
+<!-- .LP -->
+A bit-gravity of
+<symbol>StaticGravity</symbol>
+indicates that the contents or origin should not move relative to the 
+origin of the root window.
+If the change in size of the window is coupled with a change in position (x, y),
+then for bit-gravity the change in position of each pixel is (&minus;x, &minus;y), and for
+win-gravity the change in position of a child when its parent is so resized is
+(&minus;x, &minus;y).
+Note that
+<symbol>StaticGravity</symbol>
+still only takes effect when the width or height of the window is changed, 
+not when the window is moved.
+</para>
+<para>
+<!-- .LP -->
+A bit-gravity of 
+<symbol>ForgetGravity</symbol>
+indicates that the window's contents are always discarded after a size change, 
+even if a backing store or save under has been requested.
+The window is tiled with its background
+and zero or more 
+<symbol>Expose</symbol>
+events are generated. 
+If no background is defined, the existing screen contents are not
+altered.
+Some X servers may also ignore the specified bit-gravity and 
+always generate 
+<symbol>Expose</symbol>
+events.
+</para>
+<para>
+<!-- .LP -->
+The contents and borders of inferiors are not affected by their parent's
+bit-gravity.
+A server is permitted to ignore the specified bit-gravity and use
+<symbol>Forget</symbol>
+instead.
+</para>
+<para>
+<!-- .LP -->
+A win-gravity of 
+<symbol>UnmapGravity</symbol>
+is like 
+<symbol>NorthWestGravity</symbol>
+(the window is not moved),
+except the child is also
+unmapped when the parent is resized,
+and an 
+<symbol>UnmapNotify</symbol>
+event is
+generated.
+</para>
+</sect2>
+<sect2 id="Backing_Store_Attribute">
+<title>Backing Store Attribute</title>
+<!-- .XS -->
+<!-- (SN Backing Store Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some implementations of the X server may choose to maintain the contents of 
+<symbol>InputOutput</symbol>
+windows.
+If the X server maintains the contents of a window, 
+the off-screen saved pixels
+are known as backing store.
+The backing store advises the X server on what to do 
+with the contents of a window.
+The backing-store attribute can be set to
+<symbol>NotUseful</symbol>
+(default),
+<symbol>WhenMapped</symbol>,
+or
+<symbol>Always</symbol>.
+</para>
+<para>
+<!-- .LP -->
+A backing-store attribute of 
+<symbol>NotUseful</symbol>
+advises the X server that 
+maintaining contents is unnecessary, 
+although some X implementations may
+still choose to maintain contents and, therefore, not generate 
+<symbol>Expose</symbol>
+events.
+A backing-store attribute of 
+<symbol>WhenMapped</symbol>
+advises the X server that maintaining contents of 
+obscured regions when the window is mapped would be beneficial.
+In this case,
+the server may generate an 
+<symbol>Expose</symbol>
+event when the window is created.
+A backing-store attribute of 
+<symbol>Always</symbol>
+advises the X server that maintaining contents even when 
+the window is unmapped would be beneficial.  
+Even if the window is larger than its parent, 
+this is a request to the X server to maintain complete contents, 
+not just the region within the parent window boundaries.  
+While the X server maintains the window's contents, 
+<symbol>Expose</symbol>
+events normally are not generated, 
+but the X server may stop maintaining 
+contents at any time.  
+</para>
+<para>
+<!-- .LP -->
+When the contents of obscured regions of a window are being maintained,
+regions obscured by noninferior windows are included in the destination
+of graphics requests (and source, when the window is the source).
+However, regions obscured by inferior windows are not included.
+</para>
+</sect2>
+<sect2 id="Save_Under_Flag">
+<title>Save Under Flag</title>
+<!-- .XS -->
+<!-- (SN Save Under Flag -->
+<!-- .XE -->
+<indexterm><primary>Save Unders</primary></indexterm>
+<para>
+<!-- .LP -->
+Some server implementations may preserve contents of 
+<symbol>InputOutput</symbol>
+windows under other 
+<symbol>InputOutput</symbol>
+windows.
+This is not the same as preserving the contents of a window for you.
+You may get better visual
+appeal if transient windows (for example, pop-up menus) request that the system
+preserve the screen contents under them, 
+so the temporarily obscured applications do not have to repaint.
+</para>
+<para>
+<!-- .LP -->
+You can set the save-under flag to
+<symbol>True</symbol>
+or
+<symbol>False</symbol>
+(default).
+If save-under is 
+<symbol>True</symbol>,
+the X server is advised that, when this window is mapped, 
+saving the contents of windows it obscures would be beneficial.
+</para>
+</sect2>
+<sect2 id="Backing_Planes_and_Backing_Pixel_Attributes">
+<title>Backing Planes and Backing Pixel Attributes</title>
+<!-- .XS -->
+<!-- (SN Backing Planes and Backing Pixel Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You can set backing planes to indicate (with bits set to 1) 
+which bit planes of an
+<symbol>InputOutput</symbol>
+window hold dynamic data that must be preserved in backing store 
+and during save unders.
+The default value for the backing-planes attribute is all bits set to 1.
+You can set backing pixel to specify what bits to use in planes not 
+covered by backing planes.
+The default value for the backing-pixel attribute is all bits set to 0.
+The X server is free to save only the specified bit planes in the backing store
+or the save under and is free to regenerate the remaining planes with 
+the specified pixel value.
+Any extraneous bits in these values (that is, those bits beyond 
+the specified depth of the window) may be simply ignored.
+If you request backing store or save unders,
+you should use these members to minimize the amount of off-screen memory 
+required to store your window.
+</para>
+</sect2>
+<sect2 id="Event_Mask_and_Do_Not_Propagate_Mask_Attributes">
+<title>Event Mask and Do Not Propagate Mask Attributes</title>
+<!-- .XS -->
+<!-- (SN Event Mask and Do Not Propagate Mask Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The event mask defines which events the client is interested in for this 
+<symbol>InputOutput</symbol>
+or
+<symbol>InputOnly</symbol>
+window (or, for some event types, inferiors of this window).
+The event mask is the bitwise inclusive OR of zero or more of the 
+valid event mask bits.
+You can specify that no maskable events are reported by setting 
+<symbol>NoEventMask</symbol>
+(default).
+</para>
+<para>
+<!-- .LP -->
+The do-not-propagate-mask attribute
+defines which events should not be propagated to 
+ancestor windows when no client has the event type selected in this 
+<symbol>InputOutput</symbol>
+or
+<symbol>InputOnly</symbol>
+window.
+The do-not-propagate-mask is the bitwise inclusive OR of zero or more
+of the following masks:
+<symbol>KeyPress</symbol>,
+<symbol>KeyRelease</symbol>,
+<symbol>ButtonPress</symbol>,
+<symbol>ButtonRelease</symbol>,
+<symbol>PointerMotion</symbol>,
+<symbol>Button1Motion</symbol>,
+<symbol>Button2Motion</symbol>,
+<symbol>Button3Motion</symbol>,
+<symbol>Button4Motion</symbol>,
+<symbol>Button5Motion</symbol>,
+and
+<symbol>ButtonMotion</symbol>.
+You can specify that all events are propagated by setting 
+<symbol>NoEventMask</symbol>
+(default).
+</para>
+</sect2>
+<sect2 id="Override_Redirect_Flag">
+<title>Override Redirect Flag</title>
+<!-- .XS -->
+<!-- (SN Override Redirect Flag -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To control window placement or to add decoration,
+a window manager often needs to intercept (redirect) any map or configure
+request.
+Pop-up windows, however, often need to be mapped without a window manager
+getting in the way.
+To control whether an
+<symbol>InputOutput</symbol>
+or
+<symbol>InputOnly</symbol>
+window is to ignore these structure control facilities,
+use the override-redirect flag.
+</para>
+<para>
+<!-- .LP -->
+The override-redirect flag specifies whether map and configure requests 
+on this window should override a 
+<symbol>SubstructureRedirectMask</symbol>
+on the parent.
+You can set the override-redirect flag to
+<symbol>True</symbol>
+or
+<symbol>False</symbol>
+(default).
+Window managers use this information to avoid tampering with pop-up windows
+(see also chapter 14).
+</para>
+</sect2>
+<sect2 id="Colormap_Attribute">
+<title>Colormap Attribute</title>
+<!-- .XS -->
+<!-- (SN Colormap Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The colormap attribute specifies which colormap best reflects the true
+colors of the 
+<symbol>InputOutput</symbol>
+window.  
+The colormap must have the same visual type as the window,
+or a 
+<errorname>BadMatch</errorname>
+error results.  
+X servers capable of supporting multiple 
+hardware colormaps can use this information, 
+and window managers can use it for calls to
+<function>XInstallColormap</function>.
+You can set the colormap attribute to a colormap or to
+<symbol>CopyFromParent</symbol>
+(default).
+</para>
+<para>
+<!-- .LP -->
+If you set the colormap to
+<symbol>CopyFromParent</symbol>,
+the parent window's colormap is copied and used by its child.
+However, the child window must have the same visual type as the parent, 
+or a 
+<errorname>BadMatch</errorname>
+error results. 
+The parent window must not have a colormap of 
+<symbol>None</symbol>,
+or a 
+<errorname>BadMatch</errorname>
+error results.
+The colormap is copied by sharing the colormap object between the child 
+and parent, not by making a complete copy of the colormap contents.
+Subsequent changes to the parent window's colormap attribute do
+not affect the child window.
+</para>
+</sect2>
+<sect2 id="Cursor_Attribute">
+<title>Cursor Attribute</title>
+<!-- .XS -->
+<!-- (SN Cursor Attribute -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The cursor attribute specifies which cursor is to be used when the pointer is
+in the 
+<symbol>InputOutput</symbol>
+or
+<symbol>InputOnly</symbol>
+window.
+You can set the cursor to a cursor or
+<symbol>None</symbol>
+(default).
+</para>
+<para>
+<!-- .LP -->
+If you set the cursor to
+<symbol>None</symbol>,
+the parent's cursor is used when the 
+pointer is in the 
+<symbol>InputOutput</symbol>
+or
+<symbol>InputOnly</symbol>
+window, and any change in the parent's cursor will cause an
+immediate change in the displayed cursor.
+By calling
+<function>XFreeCursor</function>,
+the cursor can be freed immediately as long as no further explicit reference 
+to it is made.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Creating_Windows">
+<title>Creating Windows</title>
+<!-- .XS -->
+<!-- (SN Creating Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides basic ways for creating windows,
+and toolkits often supply higher-level functions specifically for
+creating and placing top-level windows,
+which are discussed in the appropriate toolkit documentation.
+If you do not use a toolkit, however,
+you must provide some standard information or hints for the window
+manager by using the Xlib inter-client communication functions
+(see chapter 14).
+</para>
+<para>
+<!-- .LP -->
+If you use Xlib to create your own top-level windows
+(direct children of the root window),
+you must observe the following rules so that all applications interact
+reasonably across the different styles of window management:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+You must never fight with the window manager for the size or
+placement of your top-level window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+You must be able to deal with whatever size window you get, 
+even if this means that your application just prints a message 
+like ``Please make me bigger'' in its window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+You should only attempt to resize or move top-level windows in
+direct response to a user request.
+If a request to change the size of a top-level window fails,
+you must be prepared to live with what you get.
+You are free to resize or move the children of top-level
+windows as necessary.
+(Toolkits often have facilities for automatic relayout.)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If you do not use a toolkit that automatically sets standard window properties,
+you should set these properties for top-level windows before mapping them.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For further information,
+see chapter 14 and the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateWindow</function>
+is the more general function that allows you to set specific window attributes 
+when you create a window.
+<function>XCreateSimpleWindow</function>
+creates a window that inherits its attributes from its parent window.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Window</primary><secondary>InputOnly</secondary></indexterm>
+The X server acts as if 
+<symbol>InputOnly</symbol>
+windows do not exist for
+the purposes of graphics requests, exposure processing, and
+<symbol>VisibilityNotify</symbol>
+events.
+An 
+<symbol>InputOnly</symbol>
+window cannot be used as a
+drawable (that is, as a source or destination for graphics requests).
+<symbol>InputOnly</symbol>
+and 
+<symbol>InputOutput</symbol>
+windows act identically in other respects (properties,
+grabs, input control, and so on).
+Extension packages can define other classes of windows.
+</para>
+<para>
+<!-- .LP -->
+To create an unmapped window and set its window attributes, use
+<function>XCreateWindow</function>.
+<indexterm significance="preferred"><primary>XCreateWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatewindow'>
+<funcprototype>
+  <funcdef>Window <function>XCreateWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> parent</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedint<parameter> border_width</parameter></paramdef>
+  <paramdef>int<parameter> depth</parameter></paramdef>
+  <paramdef>unsignedint<parameter> class</parameter></paramdef>
+  <paramdef>Visual<parameter> *visual</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+  <paramdef>XSetWindowAttributes<parameter> *attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>parent</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the parent window.
+<!-- .ds Xy , which are the top-left outside corner of the created window's \ -->
+borders and are relative to the inside of the parent window's borders
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the created window's inside dimensions \ -->
+and do not include the created window's borders
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+The dimensions must be nonzero,
+or a
+<errorname>BadValue</errorname>
+error results.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>border_width</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the width of the created window's border in pixels.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>depth</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window's depth.
+A depth of 
+<symbol>CopyFromParent</symbol>
+means the depth is taken from the parent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the created window's class.
+You can pass
+<symbol>InputOutput</symbol>,
+<symbol>InputOnly</symbol>,
+or 
+<symbol>CopyFromParent</symbol>.
+A class of 
+<symbol>CopyFromParent</symbol>
+means the class
+is taken from the parent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>visual</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the visual type.
+A visual of 
+<symbol>CopyFromParent</symbol>
+means the visual type is taken from the 
+parent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>valuemask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which window attributes are defined in the attributes
+argument.
+This mask is the bitwise inclusive OR of the valid attribute mask bits.
+If valuemask is zero,
+the attributes are ignored and are not referenced.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>attributes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the structure from which the values (as specified by the value mask)
+are to be taken.
+The value mask should have the appropriate bits
+set to indicate which attributes have been set in the structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateWindow</function>
+function creates an unmapped subwindow for a specified parent window, 
+returns the window ID of the created window, 
+and causes the X server to generate a
+<symbol>CreateNotify</symbol>
+event.
+The created window is placed on top in the stacking order 
+with respect to siblings.
+</para>
+<para>
+<!-- .LP -->
+The coordinate system has the X axis horizontal and the Y axis vertical
+with the origin [0, 0] at the upper-left corner.
+Coordinates are integral,
+in terms of pixels,
+and coincide with pixel centers.
+Each window and pixmap has its own coordinate system.
+For a window, 
+the origin is inside the border at the inside, upper-left corner.
+</para>
+<para>
+<!-- .LP -->
+The border_width for an
+<symbol>InputOnly</symbol>
+window must be zero, or a
+<errorname>BadMatch</errorname>
+error results.
+For class
+<symbol>InputOutput</symbol>,
+the visual type and depth must be a combination supported for the screen,
+or a
+<errorname>BadMatch</errorname>
+error results.
+The depth need not be the same as the parent,
+but the parent must not be a window of class 
+<symbol>InputOnly</symbol>,
+or a
+<errorname>BadMatch</errorname>
+error results.
+For an
+<symbol>InputOnly</symbol>
+window,
+the depth must be zero, and the visual must be one supported by the screen.
+If either condition is not met,
+a
+<errorname>BadMatch</errorname>
+error results.
+The parent window, however, may have any depth and class.
+If you specify any invalid window attribute for a window, a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The created window is not yet displayed (mapped) on the user's display.
+To display the window, call
+<function>XMapWindow</function>.
+The new window initially uses the same cursor as
+its parent. 
+A new cursor can be defined for the new window by calling
+<function>XDefineCursor</function>.
+<indexterm><primary>Cursor</primary><secondary>Initial State</secondary></indexterm>
+<indexterm><primary>XDefineCursor</primary></indexterm>
+The window will not be visible on the screen unless it and all of its
+ancestors are mapped and it is not obscured by any of its ancestors.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateWindow</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadColor</errorname>,
+<errorname>BadCursor</errorname>,
+<errorname>BadMatch</errorname>,
+<errorname>BadPixmap</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create an unmapped 
+<symbol>InputOutput</symbol>
+subwindow of a given parent window, use
+<function>XCreateSimpleWindow</function>.
+<indexterm significance="preferred"><primary>XCreateSimpleWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatesimplewindow'>
+<funcprototype>
+  <funcdef>Window <function>XCreateSimpleWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> parent</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedint<parameter> border_width</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> border</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> background</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>parent</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the parent window.
+<!-- .ds Xy , which are the top-left outside corner of the new window's borders \ -->
+and are relative to the inside of the parent window's borders
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the created window's inside dimensions \ -->
+and do not include the created window's borders
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+The dimensions must be nonzero,
+or a
+<errorname>BadValue</errorname>
+error results.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>border_width</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the width of the created window's border in pixels.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>border</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the border pixel value of the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>background</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the background pixel value of the window.
+
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateSimpleWindow</function>
+function creates an unmapped
+<symbol>InputOutput</symbol>
+subwindow for a specified parent window, returns the
+window ID of the created window, and causes the X server to generate a
+<symbol>CreateNotify</symbol>
+event.
+The created window is placed on top in the stacking order with respect to 
+siblings.
+Any part of the window that extends outside its parent window is clipped.
+The border_width for an
+<symbol>InputOnly</symbol>
+window must be zero, or a
+<errorname>BadMatch</errorname>
+error results.
+<function>XCreateSimpleWindow</function>
+inherits its depth, class, and visual from its parent.
+All other window attributes, except background and border, 
+have their default values.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateSimpleWindow</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Destroying_Windows">
+<title>Destroying Windows</title>
+<!-- .XS -->
+<!-- (SN Destroying Windows  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to destroy a window or destroy all
+subwindows of a window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy a window and all of its subwindows, use
+<function>XDestroyWindow</function>.
+<indexterm significance="preferred"><primary>XDestroyWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroywindow'>
+<funcprototype>
+  <funcdef><function>XDestroyWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDestroyWindow</function>
+function destroys the specified window as well as all of its subwindows and causes
+the X server to generate a
+<symbol>DestroyNotify</symbol>
+event for each window.
+The window should never be referenced again.
+If the window specified by the w argument is mapped,
+it is unmapped automatically.
+The ordering of the
+<symbol>DestroyNotify</symbol>
+events is such that for any given window being destroyed,
+<symbol>DestroyNotify</symbol>
+is generated on any inferiors of the window before being generated on
+the window itself.
+The ordering among siblings and across subhierarchies is not otherwise
+constrained.
+If the window you specified is a root window, no windows are destroyed.
+Destroying a mapped window will generate 
+<symbol>Expose</symbol>
+events on other windows that were obscured by the window being destroyed.
+</para>
+<para>
+<!-- .LP -->
+<function>XDestroyWindow</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy all subwindows of a specified window, use 
+<function>XDestroySubwindows</function>.
+<indexterm significance="preferred"><primary>XDestroySubwindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroysubwindows'>
+<funcprototype>
+  <funcdef><function>XDestroySubwindows</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDestroySubwindows</function>
+function destroys all inferior windows of the specified window, 
+in bottom-to-top stacking order.
+It causes the X server to generate a
+<symbol>DestroyNotify</symbol>
+event for each window.
+If any mapped
+subwindows were actually destroyed,
+<function>XDestroySubwindows</function>
+causes the X server to generate 
+<symbol>Expose</symbol>
+events on the specified window.
+This is much more efficient than deleting many windows
+one at a time because much of the work need be performed only once for all
+of the windows, rather than for each window.
+The subwindows should never be referenced again.  
+</para>
+<para>
+<!-- .LP -->
+<function>XDestroySubwindows</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Mapping_Windows_">
+<title>Mapping Windows </title>
+<!-- .XS -->
+<!-- (SN Mapping Windows  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A window is considered mapped if an 
+<function>XMapWindow</function>
+call has been made on it.
+It may not be visible on the screen for one of the following reasons:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+It is obscured by another opaque window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+One of its ancestors is not mapped.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+It is entirely clipped by an ancestor.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<symbol>Expose</symbol>
+events are generated for the window when part or all of
+it becomes visible on the screen. 
+A client receives the
+<symbol>Expose</symbol>
+events only if it has asked for them.
+Windows retain their position in the stacking order when they are unmapped.
+</para>
+<para>
+<!-- .LP -->
+A window manager may want to control the placement of subwindows.
+If 
+<symbol>SubstructureRedirectMask</symbol>
+has been selected by a window manager
+on a parent window (usually a root window),
+a map request initiated by other clients on a child window is not performed,
+and the window manager is sent a 
+<symbol>MapRequest</symbol>
+event.
+However, if the override-redirect flag on the child had been set to
+<symbol>True</symbol>
+(usually only on pop-up menus),
+the map request is performed.
+</para>
+<para>
+<!-- .LP -->
+A tiling window manager might decide to reposition and resize other clients' 
+windows and then decide to map the window to its final location.
+A window manager that wants to provide decoration might
+reparent the child into a frame first.
+For further information,
+see sections 3.2.8 and 10.10.
+Only a single client at a time can select for 
+<symbol>SubstructureRedirectMask</symbol>.
+</para>
+<para>
+<!-- .LP -->
+Similarly, a single client can select for 
+<symbol>ResizeRedirectMask</symbol>
+on a parent window.
+Then, any attempt to resize the window by another client is suppressed, and
+the client receives a 
+<symbol>ResizeRequest</symbol>
+event.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a given window, use 
+<function>XMapWindow</function>.
+<indexterm significance="preferred"><primary>XMapWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmapwindow'>
+<funcprototype>
+  <funcdef><function>XMapWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMapWindow</function>
+function
+maps the window and all of its
+subwindows that have had map requests.
+Mapping a window that has an unmapped ancestor does not display the
+window but marks it as eligible for display when the ancestor becomes
+mapped.
+Such a window is called unviewable.
+When all its ancestors are mapped,
+the window becomes viewable
+and will be visible on the screen if it is not obscured by another window.
+This function has no effect if the window is already mapped.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect of the window is
+<symbol>False</symbol>
+and if some other client has selected
+<symbol>SubstructureRedirectMask</symbol>
+on the parent window, then the X server generates a
+<symbol>MapRequest</symbol>
+event, and the
+<function>XMapWindow</function>
+function does not map the window.
+Otherwise, the window is mapped, and the X server generates a
+<symbol>MapNotify</symbol>
+event.
+</para>
+<para>
+<!-- .LP -->
+If the window becomes viewable and no earlier contents for it are remembered,
+the X server tiles the window with its background.
+If the window's background is undefined,
+the existing screen contents are not
+altered, and the X server generates zero or more 
+<symbol>Expose</symbol>
+events.
+If backing-store was maintained while the window was unmapped, no 
+<symbol>Expose</symbol>
+events
+are generated.
+If backing-store will now be maintained, 
+a full-window exposure is always generated.
+Otherwise, only visible regions may be reported.
+Similar tiling and exposure take place for any newly viewable inferiors.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>XMapWindow</primary></indexterm>
+If the window is an
+<symbol>InputOutput</symbol>
+window,
+<function>XMapWindow</function>
+generates 
+<symbol>Expose</symbol>
+events on each 
+<symbol>InputOutput</symbol>
+window that it causes to be displayed.
+If the client maps and paints the window 
+and if the client begins processing events, 
+the window is painted twice.
+To avoid this,
+first ask for 
+<symbol>Expose</symbol>
+events and then map the window,
+so the client processes input events as usual.
+The event list will include 
+<symbol>Expose</symbol>
+for each
+window that has appeared on the screen. 
+The client's normal response to
+an 
+<symbol>Expose</symbol>
+event should be to repaint the window.
+This method usually leads to simpler programs and to proper interaction
+with window managers.
+</para>
+<para>
+<!-- .LP -->
+<function>XMapWindow</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map and raise a window, use
+<function>XMapRaised</function>.
+<indexterm significance="preferred"><primary>XMapRaised</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmapraised'>
+<funcprototype>
+  <funcdef><function>XMapRaised</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMapRaised</function>
+function
+essentially is similar to
+<function>XMapWindow</function>
+in that it maps the window and all of its
+subwindows that have had map requests.
+However, it also raises the specified window to the top of the stack.
+For additional information,
+see 
+<function>XMapWindow</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XMapRaised</function>
+can generate multiple
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map all subwindows for a specified window, use 
+<function>XMapSubwindows</function>.
+<indexterm significance="preferred"><primary>XMapSubwindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmapsubwindows'>
+<funcprototype>
+  <funcdef><function>XMapSubwindows</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMapSubwindows</function>
+<indexterm><primary>XMapSubwindows</primary></indexterm>
+function maps all subwindows for a specified window in top-to-bottom stacking 
+order.
+The X server generates
+<symbol>Expose</symbol>
+events on each newly displayed window.
+This may be much more efficient than mapping many windows
+one at a time because the server needs to perform much of the work
+only once, for all of the windows, rather than for each window.
+</para>
+<para>
+<!-- .LP -->
+<function>XMapSubwindows</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Unmapping_Windows">
+<title>Unmapping Windows</title>
+<!-- .XS -->
+<!-- (SN Unmapping Windows  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to unmap a window or all subwindows.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unmap a window, use 
+<function>XUnmapWindow</function>.
+<indexterm significance="preferred"><primary>XUnmapWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunmapwindow'>
+<funcprototype>
+  <funcdef><function>XUnmapWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnmapWindow</function>
+function unmaps the specified window and causes the X server to generate an
+<symbol>UnmapNotify</symbol>
+<indexterm><primary>UnmapNotify Event</primary></indexterm>
+<indexterm><primary>XUnmapWindow</primary></indexterm>
+event.
+If the specified window is already unmapped, 
+<function>XUnmapWindow</function>
+has no effect.
+Normal exposure processing on formerly obscured windows is performed.
+Any child window will no longer be visible until another map call is
+made on the parent.
+In other words, the subwindows are still mapped but are not visible
+until the parent is mapped.
+Unmapping a window will generate 
+<symbol>Expose</symbol>
+events on windows that were formerly obscured by it.
+</para>
+<para>
+<!-- .LP -->
+<function>XUnmapWindow</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unmap all subwindows for a specified window, use 
+<function>XUnmapSubwindows</function>.
+<indexterm significance="preferred"><primary>XUnmapSubwindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunmapsubwindows'>
+<funcprototype>
+  <funcdef><function>XUnmapSubwindows</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnmapSubwindows</function>
+function unmaps all subwindows for the specified window in bottom-to-top
+stacking order.
+It causes the X server to generate an
+<symbol>UnmapNotify</symbol>
+event on each subwindow and 
+<symbol>Expose</symbol>
+events on formerly obscured windows.
+<indexterm><primary>UnmapNotify Event</primary></indexterm>
+Using this function is much more efficient than unmapping multiple windows
+one at a time because the server needs to perform much of the work
+only once, for all of the windows, rather than for each window.
+</para>
+<para>
+<!-- .LP -->
+<function>XUnmapSubwindows</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Configuring_Windows">
+<title>Configuring Windows</title>
+<!-- .XS -->
+<!-- (SN Configuring Windows  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to
+move a window, resize a window, move and resize a window, or
+change a window's border width.
+To change one of these parameters,
+set the appropriate member of the
+<structname>XWindowChanges</structname>
+structure and OR in the corresponding value mask in subsequent calls to
+<function>XConfigureWindow</function>.
+The symbols for the value mask bits and the
+<structname>XWindowChanges</structname>
+structure are:
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+
+<literallayout class="monospaced">
+/* Configure window value mask bits */
+#define      CWX              (1&lt;&lt;0)
+#define      CWY              (1&lt;&lt;1)
+#define      CWWidth          (1&lt;&lt;2)
+#define      CWHeight         (1&lt;&lt;3)
+#define      CWBorderWidth    (1&lt;&lt;4)
+#define      CWSibling        (1&lt;&lt;5)
+#define      CWStackMode      (1&lt;&lt;6)
+</literallayout>
+
+<indexterm significance="preferred"><primary>XWindowChanges</primary></indexterm>
+<literallayout class="monospaced">
+/* Values */
+
+typedef struct {
+     int x, y;
+     int width, height;
+     int border_width;
+     Window sibling;
+     int stack_mode;
+} XWindowChanges;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x and y members are used to set the window's x and y coordinates,
+which are relative to the parent's origin
+and indicate the position of the upper-left outer corner of the window.
+The width and height members are used to set the inside size of the window,
+not including the border, and must be nonzero, or a
+<errorname>BadValue</errorname>
+error results.
+Attempts to configure a root window have no effect.
+</para>
+<para>
+<!-- .LP -->
+The border_width member is used to set the width of the border in pixels.
+Note that setting just the border width leaves the outer-left corner of the window
+in a fixed position but moves the absolute position of the window's origin.
+If you attempt to set the border-width attribute of an
+<symbol>InputOnly</symbol>
+window nonzero, a
+<errorname>BadMatch</errorname>
+error results. 
+</para>
+<para>
+<!-- .LP -->
+The sibling member is used to set the sibling window for stacking operations.
+The stack_mode member is used to set how the window is to be restacked 
+and can be set to
+<symbol>Above</symbol>,
+<symbol>Below</symbol>,
+<symbol>TopIf</symbol>,
+<symbol>BottomIf</symbol>,
+or 
+<symbol>Opposite</symbol>.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect flag of the window is
+<symbol>False</symbol>
+and if some other client has selected
+<symbol>SubstructureRedirectMask</symbol>
+on the parent, the X server generates a
+<symbol>ConfigureRequest</symbol>
+event, and no further processing is performed.
+Otherwise, 
+if some other client has selected 
+<symbol>ResizeRedirectMask</symbol>
+on the window and the inside
+width or height of the window is being changed,
+a 
+<symbol>ResizeRequest</symbol>
+event is generated, and the current inside width and height are
+used instead.
+Note that the override-redirect flag of the window has no effect
+on
+<symbol>ResizeRedirectMask</symbol>
+and that
+<symbol>SubstructureRedirectMask</symbol>
+on the parent has precedence over
+<symbol>ResizeRedirectMask</symbol>
+on the window.
+</para>
+<para>
+<!-- .LP -->
+When the geometry of the window is changed as specified, 
+the window is restacked among siblings, and a
+<symbol>ConfigureNotify</symbol>
+event is generated if the state of the window actually changes.
+<symbol>GravityNotify</symbol>
+events are generated after 
+<symbol>ConfigureNotify</symbol>
+events.
+If the inside width or height of the window has actually changed, 
+children of the window are affected as specified.
+</para>
+<para>
+<!-- .LP -->
+If a window's size actually changes,
+the window's subwindows move according to their window gravity.
+Depending on the window's bit gravity,
+the contents of the window also may be moved (see section 3.2.3).
+</para>
+<para>
+<!-- .LP -->
+If regions of the window were obscured but now are not,
+exposure processing is performed on these formerly obscured windows, 
+including the window itself and its inferiors. 
+As a result of increasing the width or height,
+exposure processing is also performed on any new regions of the window 
+and any regions where window contents are lost.
+</para>
+<para>
+<!-- .LP -->
+The restack check (specifically, the computation for 
+<symbol>BottomIf</symbol>,
+<symbol>TopIf</symbol>,
+and 
+<symbol>Opposite</symbol>)
+is performed with respect to the window's final size and position (as
+controlled by the other arguments of the request), not its initial position.
+If a sibling is specified without a stack_mode,
+a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If a sibling and a stack_mode are specified, 
+the window is restacked as follows:
+</para>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>Above</symbol></entry>
+      <entry>The window is placed just above the sibling.</entry>
+    </row>
+    <row>
+      <entry><symbol>Below</symbol></entry>
+      <entry>The window is placed just below the sibling.</entry>
+    </row>
+    <row>
+      <entry><symbol>TopIf</symbol></entry>
+      <entry>If the sibling occludes the window, the window is placed at the top of the stack.</entry>
+    </row>
+    <row>
+      <entry><symbol>BottomIf</symbol></entry>
+      <entry>If the window occludes the sibling, the window is placed at the bottom of the stack.</entry>
+    </row>
+    <row>
+      <entry><symbol>Opposite</symbol></entry>
+      <entry>
+If the sibling occludes the window, the window is placed at the top of the stack.
+If the window occludes the sibling,
+the window is placed at the bottom of the stack.
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+If a stack_mode is specified but no sibling is specified,
+the window is restacked as follows:
+</para>
+
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>Above</symbol></entry>
+      <entry>The window is placed at the top of the stack.</entry>
+    </row>
+    <row>
+      <entry><symbol>Below</symbol></entry>
+      <entry>The window is placed at the bottom of the stack.</entry>
+    </row>
+    <row>
+      <entry><symbol>TopIf</symbol></entry>
+      <entry>
+If any sibling occludes the window, the window is placed at
+the top of the stack.
+      </entry>
+    </row>
+    <row>
+      <entry>
+If the window occludes any sibling, the window is placed at
+the bottom of the stack.
+      </entry>
+    </row>
+    <row>
+      <entry><symbol>Opposite</symbol></entry>
+      <entry>
+If any sibling occludes the window, the window
+is placed at the top of the stack.
+If the window occludes any sibling,
+the window is placed at the bottom of the stack.
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Attempts to configure a root window have no effect.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To configure a window's size, location, stacking, or border, use
+<function>XConfigureWindow</function>.
+<indexterm significance="preferred"><primary>XConfigureWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xconfigurewindow'>
+<funcprototype>
+  <funcdef><function>XConfigureWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>
+  <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi to be reconfigured -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which values are to be set using information in
+the values structure.
+This mask is the bitwise inclusive OR of the valid configure window values bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>values</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XWindowChanges</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XConfigureWindow</function>
+function uses the values specified in the
+<structname>XWindowChanges</structname>
+structure to reconfigure a window's size, position, border, and stacking order.
+Values not specified are taken from the existing geometry of the window.
+</para>
+<para>
+<!-- .LP -->
+If a sibling is specified without a stack_mode or if the window
+is not actually a sibling,
+a
+<errorname>BadMatch</errorname>
+error results. 
+Note that the computations for
+<symbol>BottomIf</symbol>,
+<symbol>TopIf</symbol>,
+and
+<symbol>Opposite</symbol>
+are performed with respect to the window's final geometry (as controlled by the
+other arguments passed to
+<function>XConfigureWindow</function>),
+not its initial geometry.
+Any backing store contents of the window, its
+inferiors, and other newly visible windows are either discarded or
+changed to reflect the current screen contents 
+(depending on the implementation).
+</para>
+<para>
+<!-- .LP -->
+<function>XConfigureWindow</function>
+can generate
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To move a window without changing its size, use 
+<function>XMoveWindow</function>.
+<indexterm significance="preferred"><primary>XMoveWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmovewindow'>
+<funcprototype>
+  <funcdef><function>XMoveWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN      -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi to be moved -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+<!-- .ds Xy , which define the new location of the top-left pixel \ -->
+of the window's border or the window itself if it has no border
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMoveWindow</function>
+function moves the specified window to the specified x and y coordinates,
+but it does not change the window's size, raise the window, or
+change the mapping state of the window.
+Moving a mapped window may or may not lose the window's contents 
+depending on if the window is obscured by nonchildren 
+and if no backing store exists.
+If the contents of the window are lost, 
+the X server generates
+<symbol>Expose</symbol>
+events.
+Moving a mapped window generates
+<symbol>Expose</symbol>
+events on any formerly obscured windows. 
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect flag of the window is 
+<symbol>False</symbol>
+and some
+other client has selected 
+<symbol>SubstructureRedirectMask</symbol>
+on the parent, the X server generates a
+<symbol>ConfigureRequest</symbol>
+event, and no further processing is
+performed.  
+Otherwise, the window is moved.
+</para>
+<para>
+<!-- .LP -->
+<function>XMoveWindow</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change a window's size without changing the upper-left coordinate, use 
+<function>XResizeWindow</function>.
+<indexterm significance="preferred"><primary>XResizeWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xresizewindow'>
+<funcprototype>
+  <funcdef><function>XResizeWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+<!-- .ds Wh , which are the interior dimensions of the window \ -->
+after the call completes
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XResizeWindow</function>
+function changes the inside dimensions of the specified window, not including
+its borders.
+This function does not change the window's upper-left coordinate or
+the origin and does not restack the window.
+Changing the size of a mapped window may lose its contents and generate
+<symbol>Expose</symbol>
+events.
+If a mapped window is made smaller, 
+changing its size generates
+<symbol>Expose</symbol>
+events on windows that the mapped window formerly obscured.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect flag of the window is 
+<symbol>False</symbol>
+and some
+other client has selected 
+<symbol>SubstructureRedirectMask</symbol>
+on the parent, the X server generates a
+<symbol>ConfigureRequest</symbol>
+event, and no further processing is performed.  
+If either width or height is zero,
+a
+<errorname>BadValue</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XResizeWindow</function>
+can generate
+<errorname>BadValue</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the size and location of a window, use 
+<function>XMoveResizeWindow</function>.
+<indexterm significance="preferred"><primary>XMoveResizeWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmoveresizewindow'>
+<funcprototype>
+  <funcdef><function>XMoveResizeWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi to be reconfigured -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+<!-- .ds Xy , which define the new position of the window relative to its parent -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which define the interior size of the window -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMoveResizeWindow</function>
+function changes the size and location of the specified window 
+without raising it.
+Moving and resizing a mapped window may generate an
+<symbol>Expose</symbol>
+event on the window.
+Depending on the new size and location parameters,
+moving and resizing a window may generate 
+<symbol>Expose</symbol>
+events on windows that the window formerly obscured. 
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect flag of the window is 
+<symbol>False</symbol>
+and some
+other client has selected 
+<symbol>SubstructureRedirectMask</symbol>
+on the parent, the X server generates a
+<symbol>ConfigureRequest</symbol>
+event, and no further processing is performed.  
+Otherwise, the window size and location are changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XMoveResizeWindow</function>
+can generate
+<errorname>BadValue</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the border width of a given window, use
+<function>XSetWindowBorderWidth</function>.
+<indexterm significance="preferred"><primary>XSetWindowBorderWidth</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwindowborderwidth'>
+<funcprototype>
+  <funcdef><function>XSetWindowBorderWidth</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>unsignedint<parameter> width</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the width of the window border.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowBorderWidth</function>
+function sets the specified window's border width to the specified width.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBorderWidth</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Changing_Window_Stacking_Order">
+<title>Changing Window Stacking Order</title>
+<!-- .XS -->
+<!-- (SN Changing Window Stacking Order  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to raise, lower, circulate,
+or restack windows.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To raise a window so that no sibling window obscures it, use 
+<function>XRaiseWindow</function>.
+<indexterm significance="preferred"><primary>XRaiseWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xraisewindow'>
+<funcprototype>
+  <funcdef><function>XRaiseWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRaiseWindow</function>
+function
+raises the specified window to the top of the stack so that no sibling window
+obscures it.
+If the windows are regarded as overlapping sheets of paper stacked 
+on a desk,
+then raising a window is analogous to moving the sheet to the top of
+the stack but leaving its x and y location on the desk constant.
+Raising a mapped window may generate 
+<symbol>Expose</symbol>
+events for the window and any mapped subwindows that were formerly obscured.  
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect attribute of the window is 
+<symbol>False</symbol>
+and some
+other client has selected 
+<symbol>SubstructureRedirectMask</symbol>
+on the parent, the X server generates a
+<symbol>ConfigureRequest</symbol>
+event, and no processing is performed.
+Otherwise, the window is raised.
+</para>
+<para>
+<!-- .LP -->
+<function>XRaiseWindow</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To lower a window so that it does not obscure any sibling windows, use 
+<function>XLowerWindow</function>.
+<indexterm significance="preferred"><primary>XLowerWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlowerwindow'>
+<funcprototype>
+  <funcdef><function>XLowerWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLowerWindow</function>
+function lowers the specified window to the bottom of the stack
+so that it does not obscure any sibling
+windows.
+If the windows are regarded as overlapping sheets of paper
+stacked on a desk, then lowering a window is analogous to moving the
+sheet to the bottom of the stack but leaving its x and y location on
+the desk constant.
+Lowering a mapped window will generate 
+<symbol>Expose</symbol>
+events on any windows it formerly obscured.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect attribute of the window is 
+<symbol>False</symbol>
+and some
+other client has selected 
+<symbol>SubstructureRedirectMask</symbol>
+on the parent, the X server generates a
+<symbol>ConfigureRequest</symbol>
+event, and no processing is performed.  
+Otherwise, the window is lowered to the bottom of the
+stack.
+</para>
+<para>
+<!-- .LP -->
+<function>XLowerWindow</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To circulate a subwindow up or down, use
+<function>XCirculateSubwindows</function>.
+<indexterm significance="preferred"><primary>XCirculateSubwindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcirculatesubwindows'>
+<funcprototype>
+  <funcdef><function>XCirculateSubwindows</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> direction</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>direction</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the direction (up or down) that you want to circulate
+the window. 
+You can pass 
+<symbol>RaiseLowest</symbol>
+or
+<symbol>LowerHighest</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCirculateSubwindows</function>
+function circulates children of the specified window in the specified 
+direction.
+If you specify
+<symbol>RaiseLowest</symbol>,
+<function>XCirculateSubwindows</function>
+raises the lowest mapped child (if any) that is occluded 
+by another child to the top of the stack.
+If you specify
+<symbol>LowerHighest</symbol>,
+<function>XCirculateSubwindows</function>
+lowers the highest mapped child (if any) that occludes another child
+to the bottom of the stack.
+Exposure processing is then performed on formerly obscured windows.
+If some other client has selected 
+<symbol>SubstructureRedirectMask</symbol>
+on the window, the X server generates a 
+<symbol>CirculateRequest</symbol>
+event, and no further processing is performed.
+If a child is actually restacked,
+the X server generates a
+<symbol>CirculateNotify</symbol>
+event. 
+</para>
+<para>
+<!-- .LP -->
+<function>XCirculateSubwindows</function>
+can generate
+<errorname>BadValue</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To raise the lowest mapped child of a window that is partially or completely
+occluded by another child, use
+<function>XCirculateSubwindowsUp</function>.
+<indexterm significance="preferred"><primary>XCirculateSubwindowsUp</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcirculatesubwindowsup'>
+<funcprototype>
+  <funcdef><function>XCirculateSubwindowsUp</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCirculateSubwindowsUp</function>
+function raises the lowest mapped child of the specified window that
+is partially
+or completely
+occluded by another child.
+Completely unobscured children are not affected.
+This is a convenience function equivalent to
+<function>XCirculateSubwindows</function>
+with
+<symbol>RaiseLowest</symbol>
+specified.
+</para>
+<para>
+<!-- .LP -->
+<function>XCirculateSubwindowsUp</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To lower the highest mapped child of a window that partially or 
+completely occludes another child, use 
+<function>XCirculateSubwindowsDown</function>.
+<indexterm significance="preferred"><primary>XCirculateSubwindowsDown</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcirculatesubwindowsdown'>
+<funcprototype>
+  <funcdef><function>XCirculateSubwindowsDown</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCirculateSubwindowsDown</function>
+function lowers the highest mapped child of the specified window that partially
+or completely occludes another child.
+Completely unobscured children are not affected.
+This is a convenience function equivalent to
+<function>XCirculateSubwindows</function>
+with
+<symbol>LowerHighest</symbol>
+specified.
+</para>
+<para>
+<!-- .LP -->
+<function>XCirculateSubwindowsDown</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To restack a set of windows from top to bottom, use 
+<function>XRestackWindows</function>.
+<indexterm significance="preferred"><primary>XRestackWindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrestackwindows'>
+<funcprototype>
+  <funcdef><function>XRestackWindows</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> windows[]</parameter></paramdef>
+  <paramdef>int<parameter> nwindows</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>windows</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array containing the windows to be restacked.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nwindows</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of windows to be restacked.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRestackWindows</function>
+function restacks the windows in the order specified,
+from top to bottom.
+The stacking order of the first window in the windows array is unaffected,
+but the other windows in the array are stacked underneath the first window,
+in the order of the array.
+The stacking order of the other windows is not affected.
+For each window in the window array that is not a child of the specified window,
+a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If the override-redirect attribute of a window is 
+<symbol>False</symbol>
+and some
+other client has selected 
+<symbol>SubstructureRedirectMask</symbol>
+on the parent, the X server generates 
+<symbol>ConfigureRequest</symbol>
+events for each window whose override-redirect flag is not set, 
+and no further processing is performed.
+Otherwise, the windows will be restacked in top-to-bottom order.
+</para>
+<para>
+<!-- .LP -->
+<function>XRestackWindows</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Changing_Window_Attributes">
+<title>Changing Window Attributes</title>
+<!-- .XS -->
+<!-- (SN Changing Window Attributes  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set window attributes.
+<function>XChangeWindowAttributes</function>
+is the more general function that allows you to set one or more window
+attributes provided by the
+<structname>XSetWindowAttributes</structname>
+structure.
+The other functions described in this section allow you to set one specific
+window attribute, such as a window's background.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change one or more attributes for a given window, use
+<function>XChangeWindowAttributes</function>.
+<indexterm significance="preferred"><primary>XChangeWindowAttributes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchangewindowattributes'>
+<funcprototype>
+  <funcdef><function>XChangeWindowAttributes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+  <paramdef>XSetWindowAttributes<parameter> *attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>valuemask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which window attributes are defined in the attributes
+argument.
+This mask is the bitwise inclusive OR of the valid attribute mask bits.
+If valuemask is zero,
+the attributes are ignored and are not referenced.
+The values and restrictions are
+the same as for
+<function>XCreateWindow</function>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      
+    </term>
+    <listitem>
+      <para>
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>attributes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the structure from which the values (as specified by the value mask)
+are to be taken.
+The value mask should have the appropriate bits
+set to indicate which attributes have been set in the structure 
+(see section 3.2).
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Depending on the valuemask,
+the
+<function>XChangeWindowAttributes</function>
+function uses the window attributes in the
+<structname>XSetWindowAttributes</structname>
+structure to change the specified window attributes.
+Changing the background does not cause the window contents to be
+changed.
+To repaint the window and its background, use 
+<function>XClearWindow</function>.
+Setting the border or changing the background such that the
+border tile origin changes causes the border to be repainted.
+Changing the background of a root window to 
+<symbol>None</symbol>
+or 
+<symbol>ParentRelative</symbol>
+restores the default background pixmap.
+Changing the border of a root window to
+<symbol>CopyFromParent</symbol>
+restores the default border pixmap.
+Changing the win-gravity does not affect the current position of the
+window.
+Changing the backing-store of an obscured window to 
+<symbol>WhenMapped</symbol>
+or
+<symbol>Always</symbol>,
+or changing the backing-planes, backing-pixel, or
+save-under of a mapped window may have no immediate effect.
+Changing the colormap of a window (that is, defining a new map, not
+changing the contents of the existing map) generates a 
+<symbol>ColormapNotify</symbol>
+event.
+Changing the colormap of a visible window may have no
+immediate effect on the screen because the map may not be installed
+(see
+<function>XInstallColormap</function>).
+Changing the cursor of a root window to 
+<symbol>None</symbol>
+restores the default
+cursor.
+Whenever possible, you are encouraged to share colormaps.
+</para>
+<para>
+<!-- .LP -->
+Multiple clients can select input on the same window. 
+Their event masks are maintained separately.
+When an event is generated, 
+it is reported to all interested clients. 
+However, only one client at a time can select for 
+<symbol>SubstructureRedirectMask</symbol>,
+<symbol>ResizeRedirectMask</symbol>,
+and
+<symbol>ButtonPressMask</symbol>.
+If a client attempts to select any of these event masks 
+and some other client has already selected one, 
+a
+<errorname>BadAccess</errorname>
+error results.
+There is only one do-not-propagate-mask for a window, 
+not one per client.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeWindowAttributes</function>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadColor</errorname>,
+<errorname>BadCursor</errorname>,
+<errorname>BadMatch</errorname>,
+<errorname>BadPixmap</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the background of a window to a given pixel, use 
+<function>XSetWindowBackground</function>.
+<indexterm significance="preferred"><primary>XSetWindowBackground</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwindowbackground'>
+<funcprototype>
+  <funcdef><function>XSetWindowBackground</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> background_pixel</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>background_pixel</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the pixel that is to be used for the background.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowBackground</function>
+function sets the background of the window to the specified pixel value.
+Changing the background does not cause the window contents to be changed.
+<function>XSetWindowBackground</function>
+uses a pixmap of undefined size filled with the pixel value you passed.
+If you try to change the background of an 
+<symbol>InputOnly</symbol>
+window, a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBackground</function>
+can generate
+<errorname>BadMatch</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the background of a window to a given pixmap, use 
+<function>XSetWindowBackgroundPixmap</function>.
+<indexterm><primary>Window</primary><secondary>background</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSetWindowBackgroundPixmap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwindowbackgroundpixmap'>
+<funcprototype>
+  <funcdef><function>XSetWindowBackgroundPixmap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Pixmap<parameter> background_pixmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>background_pixmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the background pixmap,
+<symbol>ParentRelative</symbol>,
+or
+<symbol>None</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>
+The
+<function>XSetWindowBackgroundPixmap</function>
+function sets the background pixmap of the window to the specified pixmap.
+The background pixmap can immediately be freed if no further explicit
+references to it are to be made.
+If 
+<symbol>ParentRelative</symbol>
+is specified, 
+the background pixmap of the window's parent is used,
+or on the root window, the default background is restored.
+If you try to change the background of an 
+<symbol>InputOnly</symbol>
+window, a
+<errorname>BadMatch</errorname>
+error results.
+If the background is set to
+<symbol>None</symbol>,
+the window has no defined background.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBackgroundPixmap</function>
+can generate
+<errorname>BadMatch</errorname>,
+<errorname>BadPixmap</errorname>,
+and 
+<errorname>BadWindow</errorname>
+errors.
+<!-- .NT Note -->
+<function>XSetWindowBackground</function>
+and
+<function>XSetWindowBackgroundPixmap</function>
+do not change the current contents of the window.
+<!-- .NE -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change and repaint a window's border to a given pixel, use 
+<function>XSetWindowBorder</function>.
+<indexterm significance="preferred"><primary>XSetWindowBorder</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwindowborder'>
+<funcprototype>
+  <funcdef><function>XSetWindowBorder</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> border_pixel</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>border_pixel</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the entry in the colormap. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowBorder</function>
+function sets the border of the window to the pixel value you specify.
+If you attempt to perform this on an
+<symbol>InputOnly</symbol>
+window, a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBorder</function>
+can generate
+<errorname>BadMatch</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change and repaint the border tile of a given window, use 
+<function>XSetWindowBorderPixmap</function>.
+<indexterm significance="preferred"><primary>XSetWindowBorderPixmap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwindowborderpixmap'>
+<funcprototype>
+  <funcdef><function>XSetWindowBorderPixmap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Pixmap<parameter> border_pixmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>border_pixmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the border pixmap or
+<symbol>CopyFromParent</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowBorderPixmap</function>
+function sets the border pixmap of the window to the pixmap you specify.
+The border pixmap can be freed immediately if no further explicit
+references to it are to be made.
+If you specify
+<symbol>CopyFromParent</symbol>,
+a copy of the parent window's border pixmap is used.
+If you attempt to perform this on an
+<symbol>InputOnly</symbol>
+window, a
+<errorname>BadMatch</errorname>
+error results.
+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowBorderPixmap</function>
+can generate
+<errorname>BadMatch</errorname>,
+<errorname>BadPixmap</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the colormap of a given window, use
+<function>XSetWindowColormap</function>.
+<indexterm significance="preferred"><primary>XSetWindowColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwindowcolormap'>
+<funcprototype>
+  <funcdef><function>XSetWindowColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWindowColormap</function>
+function sets the specified colormap of the specified window.
+The colormap must have the same visual type as the window,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWindowColormap</function>
+can generate
+<errorname>BadColor</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To define which cursor will be used in a window, use
+<function>XDefineCursor</function>.
+<indexterm><primary>Window</primary><secondary>defining the cursor</secondary></indexterm>
+<indexterm significance="preferred"><primary>XDefineCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdefinecursor'>
+<funcprototype>
+  <funcdef><function>XDefineCursor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>cursor</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the cursor that is to be displayed or
+<symbol>None</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If a cursor is set, it will be used when the pointer is in the window.
+If the cursor is
+<symbol>None</symbol>,
+it is equivalent to
+<function>XUndefineCursor</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XDefineCursor</function>
+can generate
+<errorname>BadCursor</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To undefine the cursor in a given window, use
+<function>XUndefineCursor</function>.
+<indexterm><primary>Window</primary><secondary>undefining the cursor</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUndefineCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xundefinecursor'>
+<funcprototype>
+  <funcdef><function>XUndefineCursor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUndefineCursor</function>
+function undoes the effect of a previous
+<function>XDefineCursor</function>
+for this window.
+When the pointer is in the window,
+the parent's cursor will now be used.
+On the root window,
+the default cursor is restored.
+</para>
+<para>
+<!-- .LP -->
+<function>XUndefineCursor</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+<!-- .bp -->
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH04.xml b/libX11/specs/libX11/CH04.xml
index 8a3e8c535..d224216d3 100644
--- a/libX11/specs/libX11/CH04.xml
+++ b/libX11/specs/libX11/CH04.xml
@@ -40,7 +40,7 @@ a given window, use
 <indexterm><primary>Parent Window</primary></indexterm>
 <indexterm significance="preferred"><primary>XQueryTree</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xquerytree'>
 <funcprototype>
   <funcdef>Status <function>XQueryTree</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -147,7 +147,7 @@ To obtain the current attributes of a given window, use
 <function>XGetWindowAttributes</function>.
 <indexterm significance="preferred"><primary>XGetWindowAttributes</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xgetwindowattributes'>
 <funcprototype>
   <funcdef>Status <function>XGetWindowAttributes</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -372,7 +372,7 @@ To obtain the current geometry of a given drawable, use
 <function>XGetGeometry</function>.
 <indexterm significance="preferred"><primary>XGetGeometry</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xgetgeometry'>
 <funcprototype>
   <funcdef>Status <function>XGetGeometry</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -533,7 +533,7 @@ space of another window, use
 <function>XTranslateCoordinates</function>.
 <indexterm significance="preferred"><primary>XTranslateCoordinates</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xtranslatecoordinates'>
 <funcprototype>
   <funcdef>Bool <function>XTranslateCoordinates</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -667,7 +667,7 @@ or to determine the pointer coordinates relative to a specified window, use
 <function>XQueryPointer</function>.
 <indexterm significance="preferred"><primary>XQueryPointer</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xquerypointer'>
 <funcprototype>
   <funcdef>Bool <function>XQueryPointer</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1050,7 +1050,7 @@ To return an atom for a given name, use
 <indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>
 <indexterm significance="preferred"><primary>XInternAtom</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xinternatom'>
 <funcprototype>
   <funcdef>Atom <function>XInternAtom</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1132,7 +1132,7 @@ To return atoms for an array of names, use
 <indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>
 <indexterm significance="preferred"><primary>XInternAtoms</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xinternatoms'>
 <funcprototype>
   <funcdef>Status <function>XInternAtoms</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1233,7 +1233,7 @@ To return a name for a given atom identifier, use
 <indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>
 <indexterm significance="preferred"><primary>XGetAtomName</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xgetatomname'>
 <funcprototype>
   <funcdef>char *<function>XGetAtomName</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1292,7 +1292,7 @@ To return the names for an array of atom identifiers, use
 <indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>
 <indexterm significance="preferred"><primary>XGetAtomNames</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xgetatomnames'>
 <funcprototype>
   <funcdef>Status <function>XGetAtomNames</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1409,7 +1409,7 @@ To obtain the type, format, and value of a property of a given window, use
 <!-- .LP -->
 <indexterm significance="preferred"><primary>XGetWindowProperty</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xgetwindowproperty'>
 <funcprototype>
   <funcdef>int <function>XGetWindowProperty</function></funcdef>
   <paramdef><parameter> display</parameter></paramdef>
@@ -1689,7 +1689,7 @@ To obtain a given window's property list, use
 <indexterm><primary>Property</primary><secondary>listing</secondary></indexterm>
 <indexterm significance="preferred"><primary>XListProperties</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xlistproperties'>
 <funcprototype>
   <funcdef>Atom *<function>XListProperties</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1762,7 +1762,7 @@ To change a property of a given window, use
 <indexterm><primary>Property</primary><secondary>type</secondary></indexterm>
 <indexterm significance="preferred"><primary>XChangeProperty</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xchangeproperty'>
 <funcprototype>
   <funcdef><function>XChangeProperty</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -1963,7 +1963,7 @@ To rotate a window's property list, use
 <!-- .LP -->
 <indexterm significance="preferred"><primary>XRotateWindowProperties</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xrotatewindowproperties'>
 <funcprototype>
   <funcdef><function>XRotateWindowProperties</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -2077,7 +2077,7 @@ To delete a property on a given window, use
 <indexterm><primary>Property</primary><secondary>deleting</secondary></indexterm>
 <indexterm significance="preferred"><primary>XDeleteProperty</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xdeleteproperty'>
 <funcprototype>
   <funcdef><function>XDeleteProperty</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -2200,7 +2200,7 @@ To set the selection owner, use
 <indexterm><primary>Selection</primary><secondary>setting the owner</secondary></indexterm>
 <indexterm significance="preferred"><primary>XSetSelectionOwner</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xsetselectionowner'>
 <funcprototype>
   <funcdef><function>XSetSelectionOwner</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -2323,7 +2323,7 @@ To return the selection owner, use
 <indexterm><primary>Selection</primary><secondary>getting the owner</secondary></indexterm>
 <indexterm significance="preferred"><primary>XGetSelectionOwner</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xgetselectionowner'>
 <funcprototype>
   <funcdef>Window <function>XGetSelectionOwner</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
@@ -2385,7 +2385,7 @@ To request conversion of a selection, use
 <indexterm><primary>Selection</primary><secondary>converting</secondary></indexterm>
 <indexterm significance="preferred"><primary>XConvertSelection</primary></indexterm>
 <!-- .sM -->
-<funcsynopsis>
+<funcsynopsis id='xconvertselection'>
 <funcprototype>
   <funcdef><function>XConvertSelection</function></funcdef>
   <paramdef>Display<parameter> *display</parameter></paramdef>
diff --git a/libX11/specs/libX11/CH05.xml b/libX11/specs/libX11/CH05.xml
index 08d78d666..3ad7076ea 100644
--- a/libX11/specs/libX11/CH05.xml
+++ b/libX11/specs/libX11/CH05.xml
@@ -1,818 +1,818 @@
-<?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="pixmap_and_cursor_functions">

-<title>Pixmap and Cursor Functions</title>

-<sect1 id="Creating_and_Freeing_Pixmaps">

-<title>Creating and Freeing Pixmaps</title>

-<!-- .XS -->

-<!-- (SN Creating and Freeing Pixmaps -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Pixmaps can only be used on the screen on which they were created.

-Pixmaps are off-screen resources that are used for various operations,

-such as defining cursors as tiling patterns 

-or as the source for certain raster operations.

-Most graphics requests can operate either on a window or on a pixmap.

-A bitmap is a single bit-plane pixmap.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a pixmap of a given size, use

-<function>XCreatePixmap</function>.

-<indexterm significance="preferred"><primary>XCreatePixmap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Pixmap <function>XCreatePixmap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedint<parameter> depth</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which screen the pixmap is created on. 

-<!-- .ds Wh , which define the dimensions of the pixmap -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>depth</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the depth of the pixmap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XCreatePixmap</function>

-function creates a pixmap of the width, height, and depth you specified

-and returns a pixmap ID that identifies it.

-It is valid to pass an 

-<symbol>InputOnly</symbol>

-window to the drawable argument.

-The width and height arguments must be nonzero,

-or a 

-<errorname>BadValue</errorname>

-error results.

-The depth argument must be one of the depths supported by the screen

-of the specified drawable,

-or a

-<errorname>BadValue</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-The server uses the specified drawable to determine on which screen

-to create the pixmap.

-The pixmap can be used only on this screen

-and only with other drawables of the same depth (see

-<function>XCopyPlane</function>

-for an exception to this rule).

-The initial contents of the pixmap are undefined.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreatePixmap</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadDrawable</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To free all storage associated with a specified pixmap, use

-<function>XFreePixmap</function>.

-<indexterm significance="preferred"><primary>XFreePixmap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreePixmap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN	 -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pixmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the pixmap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XFreePixmap</function>

-function first deletes the association between the pixmap ID and the pixmap.

-Then, the X server frees the pixmap storage when there are no references to it.

-The pixmap should never be referenced again.

-</para>

-<para>

-<!-- .LP -->

-<function>XFreePixmap</function>

-can generate a

-<errorname>BadPixmap</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Creating_Recoloring_and_Freeing_Cursors">

-<title>Creating, Recoloring, and Freeing Cursors</title>

-<!-- .XS -->

-<!-- (SN Creating, Recoloring, and Freeing Cursors  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Each window can have a different cursor defined for it.

-Whenever the pointer is in a visible window, 

-it is set to the cursor defined for that window.

-If no cursor was defined for that window, 

-the cursor is the one defined for the parent window.

-</para>

-<para>

-<!-- .LP -->

-From X's perspective, 

-a cursor consists of a cursor source, mask, colors, and a hotspot. 

-The mask pixmap determines the shape of the cursor and must be a depth

-of one.

-The source pixmap must have a depth of one,

-and the colors determine the colors of the source.

-The hotspot defines the point on the cursor that is reported

-when a pointer event occurs.

-There may be limitations imposed by the hardware on

-cursors as to size and whether a mask is implemented. 

-<indexterm><primary>XQueryBestCursor</primary></indexterm>

-<function>XQueryBestCursor</function>

-can be used to find out what sizes are possible.

-There is a standard font for creating cursors, but

-Xlib provides functions that you can use to create cursors

-from an arbitrary font or from bitmaps.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a cursor from the standard cursor font, use

-<function>XCreateFontCursor</function>.

-</para>

-<para>

-#include &lt;X11/cursorfont.h&gt;

-</para>

-

-<indexterm significance="preferred"><primary>XCreateFontCursor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Cursor <function>XCreateFontCursor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedint<parameter> shape</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>shape</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the shape of the cursor.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-X provides a set of standard cursor shapes in a special font named

-cursor.

-Applications are encouraged to use this interface for their cursors

-because the font can be customized for the individual display type.

-The shape argument specifies which glyph of the standard fonts

-to use.

-</para>

-<para>

-<!-- .LP -->

-The hotspot comes from the information stored in the cursor font.

-The initial colors of a cursor are a black foreground and a white

-background (see

-<function>XRecolorCursor</function>).

-For further information about cursor shapes,

-see appendix B.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateFontCursor</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a cursor from font glyphs, use

-<function>XCreateGlyphCursor</function>.

-<indexterm significance="preferred"><primary>XCreateGlyphCursor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Cursor <function>XCreateGlyphCursor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Fontsource_font,<parameter> mask_font</parameter></paramdef>

-  <paramdef>unsignedintsource_char,<parameter> mask_char</parameter></paramdef>

-  <paramdef>XColor<parameter> *foreground_color</parameter></paramdef>

-  <paramdef>XColor<parameter> *background_color</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>source_font</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font for the source glyph.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mask_font</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font for the mask glyph or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>source_char</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character glyph for the source.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mask_char</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the glyph character for the mask. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>foreground_color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the <acronym>RGB</acronym> values for the foreground of the source. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>background_color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the <acronym>RGB</acronym> values for the background of the source.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateGlyphCursor</function>

-function is similar to

-<function>XCreatePixmapCursor</function>

-except that the source and mask bitmaps are obtained from the specified 

-font glyphs.

-The source_char must be a defined glyph in source_font, 

-or a

-<errorname>BadValue</errorname>

-error results.

-If mask_font is given, 

-mask_char must be a defined glyph in mask_font,

-or a

-<errorname>BadValue</errorname>

-error results.

-The mask_font and character are optional.

-The origins of the source_char and mask_char (if defined) glyphs are

-positioned coincidently and define the hotspot. 

-The source_char and mask_char need not have the same bounding box metrics, 

-and there is no restriction on the placement of the hotspot relative to the bounding

-boxes. 

-If no mask_char is given, all pixels of the source are displayed.

-You can free the fonts immediately by calling

-<function>XFreeFont</function>

-if no further explicit references to them are to be made. 

-</para>

-<para>

-<!-- .LP -->

-For 2-byte matrix fonts, 

-the 16-bit value should be formed with the byte1

-member in the most significant byte and the byte2 member in the 

-least significant byte.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateGlyphCursor</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadFont</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a cursor from two bitmaps,

-use

-<function>XCreatePixmapCursor</function>.

-<indexterm significance="preferred"><primary>XCreatePixmapCursor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Cursor <function>XCreatePixmapCursor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Pixmap<parameter> source</parameter></paramdef>

-  <paramdef>Pixmap<parameter> mask</parameter></paramdef>

-  <paramdef>XColor<parameter> *foreground_color</parameter></paramdef>

-  <paramdef>XColor<parameter> *background_color</parameter></paramdef>

-  <paramdef>unsignedintx,<parameter> y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>source</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the shape of the source cursor.

-<!-- .\" *** JIM: NEED TO CHECK THIS. *** -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the cursor's source bits to be displayed or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>foreground_color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the <acronym>RGB</acronym> values for the foreground of the source. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>background_color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the <acronym>RGB</acronym> values for the background of the source.

-<!-- .ds Xy , which indicate the hotspot relative to the source's origin -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreatePixmapCursor</function>

-function creates a cursor and returns the cursor ID associated with it.

-The foreground and background <acronym>RGB</acronym> values must be specified using

-foreground_color and background_color,

-even if the X server only has a

-<symbol>StaticGray</symbol>

-or

-<symbol>GrayScale</symbol>

-screen.

-The foreground color is used for the pixels set to 1 in the

-source, and the background color is used for the pixels set to 0.

-Both source and mask, if specified, must have depth one (or a 

-<errorname>BadMatch</errorname>

-error results) but can have any root.

-The mask argument defines the shape of the cursor.

-The pixels set to 1 in the mask define which source pixels are displayed,

-and the pixels set to 0 define which pixels are ignored.

-If no mask is given, 

-all pixels of the source are displayed.

-The mask, if present, must be the same size as the pixmap defined by the 

-source argument, or a

-<errorname>BadMatch</errorname>

-error results.

-The hotspot must be a point within the source,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-The components of the cursor can be transformed arbitrarily to meet

-display limitations.

-The pixmaps can be freed immediately if no further explicit references

-to them are to be made.

-Subsequent drawing in the source or mask pixmap has an undefined effect on the

-cursor.

-The X server might or might not make a copy of the pixmap.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreatePixmapCursor</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadPixmap</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To determine useful cursor sizes, use

-<function>XQueryBestCursor</function>.

-<indexterm significance="preferred"><primary>XQueryBestCursor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XQueryBestCursor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Dr , which indicates the screen -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable(Dr. 

-<!-- .ds Wh \ of the cursor that you want the size information for -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the best width and height that is closest to the specified width 

-and height.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Some displays allow larger cursors than other displays.

-The

-<function>XQueryBestCursor</function>

-function provides a way to find out what size cursors are actually

-possible on the display.

-<indexterm ><primary>Cursor</primary><secondary>limitations</secondary></indexterm>

-It returns the largest size that can be displayed.

-Applications should be prepared to use smaller cursors on displays that

-cannot support large ones.

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryBestCursor</function>

-can generate a

-<errorname>BadDrawable</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change the color of a given cursor, use

-<function>XRecolorCursor</function>.

-<indexterm significance="preferred"><primary>XRecolorCursor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRecolorCursor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

-  <paramdef>XColor*foreground_color,<parameter> *background_color</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>cursor</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the cursor. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>foreground_color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the <acronym>RGB</acronym> values for the foreground of the source. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>background_color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the <acronym>RGB</acronym> values for the background of the source.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRecolorCursor</function>

-function changes the color of the specified cursor, and

-if the cursor is being displayed on a screen,

-the change is visible immediately.

-The pixel members of the

-<structname>XColor</structname>

-structures are ignored; only the <acronym>RGB</acronym> values are used.

-</para>

-<para>

-<!-- .LP -->

-<function>XRecolorCursor</function>

-can generate a

-<errorname>BadCursor</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To free (destroy) a given cursor, use

-<function>XFreeCursor</function>.

-<indexterm significance="preferred"><primary>XFreeCursor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeCursor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>cursor</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the cursor. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XFreeCursor</function>

-function deletes the association between the cursor resource ID 

-and the specified cursor.

-The cursor storage is freed when no other resource references it.

-The specified cursor ID should not be referred to again.

-</para>

-<para>

-<!-- .LP -->

-<function>XFreeCursor</function>

-can generate a

-<errorname>BadCursor</errorname>

-error.

-<!-- .bp -->

-

-</para>

-</sect1>

-</chapter>

+<?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="pixmap_and_cursor_functions">
+<title>Pixmap and Cursor Functions</title>
+<sect1 id="Creating_and_Freeing_Pixmaps">
+<title>Creating and Freeing Pixmaps</title>
+<!-- .XS -->
+<!-- (SN Creating and Freeing Pixmaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Pixmaps can only be used on the screen on which they were created.
+Pixmaps are off-screen resources that are used for various operations,
+such as defining cursors as tiling patterns 
+or as the source for certain raster operations.
+Most graphics requests can operate either on a window or on a pixmap.
+A bitmap is a single bit-plane pixmap.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a pixmap of a given size, use
+<function>XCreatePixmap</function>.
+<indexterm significance="preferred"><primary>XCreatePixmap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatepixmap'>
+<funcprototype>
+  <funcdef>Pixmap <function>XCreatePixmap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedint<parameter> depth</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which screen the pixmap is created on. 
+<!-- .ds Wh , which define the dimensions of the pixmap -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>depth</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the depth of the pixmap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XCreatePixmap</function>
+function creates a pixmap of the width, height, and depth you specified
+and returns a pixmap ID that identifies it.
+It is valid to pass an 
+<symbol>InputOnly</symbol>
+window to the drawable argument.
+The width and height arguments must be nonzero,
+or a 
+<errorname>BadValue</errorname>
+error results.
+The depth argument must be one of the depths supported by the screen
+of the specified drawable,
+or a
+<errorname>BadValue</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The server uses the specified drawable to determine on which screen
+to create the pixmap.
+The pixmap can be used only on this screen
+and only with other drawables of the same depth (see
+<function>XCopyPlane</function>
+for an exception to this rule).
+The initial contents of the pixmap are undefined.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreatePixmap</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadDrawable</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free all storage associated with a specified pixmap, use
+<function>XFreePixmap</function>.
+<indexterm significance="preferred"><primary>XFreePixmap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreepixmap'>
+<funcprototype>
+  <funcdef><function>XFreePixmap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN	 -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pixmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the pixmap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XFreePixmap</function>
+function first deletes the association between the pixmap ID and the pixmap.
+Then, the X server frees the pixmap storage when there are no references to it.
+The pixmap should never be referenced again.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreePixmap</function>
+can generate a
+<errorname>BadPixmap</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Creating_Recoloring_and_Freeing_Cursors">
+<title>Creating, Recoloring, and Freeing Cursors</title>
+<!-- .XS -->
+<!-- (SN Creating, Recoloring, and Freeing Cursors  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Each window can have a different cursor defined for it.
+Whenever the pointer is in a visible window, 
+it is set to the cursor defined for that window.
+If no cursor was defined for that window, 
+the cursor is the one defined for the parent window.
+</para>
+<para>
+<!-- .LP -->
+From X's perspective, 
+a cursor consists of a cursor source, mask, colors, and a hotspot. 
+The mask pixmap determines the shape of the cursor and must be a depth
+of one.
+The source pixmap must have a depth of one,
+and the colors determine the colors of the source.
+The hotspot defines the point on the cursor that is reported
+when a pointer event occurs.
+There may be limitations imposed by the hardware on
+cursors as to size and whether a mask is implemented. 
+<indexterm><primary>XQueryBestCursor</primary></indexterm>
+<function>XQueryBestCursor</function>
+can be used to find out what sizes are possible.
+There is a standard font for creating cursors, but
+Xlib provides functions that you can use to create cursors
+from an arbitrary font or from bitmaps.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a cursor from the standard cursor font, use
+<function>XCreateFontCursor</function>.
+</para>
+<para>
+#include &lt;X11/cursorfont.h&gt;
+</para>
+
+<indexterm significance="preferred"><primary>XCreateFontCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatefontcursor'>
+<funcprototype>
+  <funcdef>Cursor <function>XCreateFontCursor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedint<parameter> shape</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>shape</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the shape of the cursor.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+X provides a set of standard cursor shapes in a special font named
+cursor.
+Applications are encouraged to use this interface for their cursors
+because the font can be customized for the individual display type.
+The shape argument specifies which glyph of the standard fonts
+to use.
+</para>
+<para>
+<!-- .LP -->
+The hotspot comes from the information stored in the cursor font.
+The initial colors of a cursor are a black foreground and a white
+background (see
+<function>XRecolorCursor</function>).
+For further information about cursor shapes,
+see appendix B.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateFontCursor</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a cursor from font glyphs, use
+<function>XCreateGlyphCursor</function>.
+<indexterm significance="preferred"><primary>XCreateGlyphCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreateglyphcursor'>
+<funcprototype>
+  <funcdef>Cursor <function>XCreateGlyphCursor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Fontsource_font,<parameter> mask_font</parameter></paramdef>
+  <paramdef>unsignedintsource_char,<parameter> mask_char</parameter></paramdef>
+  <paramdef>XColor<parameter> *foreground_color</parameter></paramdef>
+  <paramdef>XColor<parameter> *background_color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>source_font</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font for the source glyph.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mask_font</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font for the mask glyph or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>source_char</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character glyph for the source.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mask_char</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the glyph character for the mask. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>foreground_color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the <acronym>RGB</acronym> values for the foreground of the source. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>background_color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the <acronym>RGB</acronym> values for the background of the source.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateGlyphCursor</function>
+function is similar to
+<function>XCreatePixmapCursor</function>
+except that the source and mask bitmaps are obtained from the specified 
+font glyphs.
+The source_char must be a defined glyph in source_font, 
+or a
+<errorname>BadValue</errorname>
+error results.
+If mask_font is given, 
+mask_char must be a defined glyph in mask_font,
+or a
+<errorname>BadValue</errorname>
+error results.
+The mask_font and character are optional.
+The origins of the source_char and mask_char (if defined) glyphs are
+positioned coincidently and define the hotspot. 
+The source_char and mask_char need not have the same bounding box metrics, 
+and there is no restriction on the placement of the hotspot relative to the bounding
+boxes. 
+If no mask_char is given, all pixels of the source are displayed.
+You can free the fonts immediately by calling
+<function>XFreeFont</function>
+if no further explicit references to them are to be made. 
+</para>
+<para>
+<!-- .LP -->
+For 2-byte matrix fonts, 
+the 16-bit value should be formed with the byte1
+member in the most significant byte and the byte2 member in the 
+least significant byte.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateGlyphCursor</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadFont</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a cursor from two bitmaps,
+use
+<function>XCreatePixmapCursor</function>.
+<indexterm significance="preferred"><primary>XCreatePixmapCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatepixmapcursor'>
+<funcprototype>
+  <funcdef>Cursor <function>XCreatePixmapCursor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Pixmap<parameter> source</parameter></paramdef>
+  <paramdef>Pixmap<parameter> mask</parameter></paramdef>
+  <paramdef>XColor<parameter> *foreground_color</parameter></paramdef>
+  <paramdef>XColor<parameter> *background_color</parameter></paramdef>
+  <paramdef>unsignedintx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>source</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the shape of the source cursor.
+<!-- .\" *** JIM: NEED TO CHECK THIS. *** -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the cursor's source bits to be displayed or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>foreground_color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the <acronym>RGB</acronym> values for the foreground of the source. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>background_color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the <acronym>RGB</acronym> values for the background of the source.
+<!-- .ds Xy , which indicate the hotspot relative to the source's origin -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreatePixmapCursor</function>
+function creates a cursor and returns the cursor ID associated with it.
+The foreground and background <acronym>RGB</acronym> values must be specified using
+foreground_color and background_color,
+even if the X server only has a
+<symbol>StaticGray</symbol>
+or
+<symbol>GrayScale</symbol>
+screen.
+The foreground color is used for the pixels set to 1 in the
+source, and the background color is used for the pixels set to 0.
+Both source and mask, if specified, must have depth one (or a 
+<errorname>BadMatch</errorname>
+error results) but can have any root.
+The mask argument defines the shape of the cursor.
+The pixels set to 1 in the mask define which source pixels are displayed,
+and the pixels set to 0 define which pixels are ignored.
+If no mask is given, 
+all pixels of the source are displayed.
+The mask, if present, must be the same size as the pixmap defined by the 
+source argument, or a
+<errorname>BadMatch</errorname>
+error results.
+The hotspot must be a point within the source,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The components of the cursor can be transformed arbitrarily to meet
+display limitations.
+The pixmaps can be freed immediately if no further explicit references
+to them are to be made.
+Subsequent drawing in the source or mask pixmap has an undefined effect on the
+cursor.
+The X server might or might not make a copy of the pixmap.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreatePixmapCursor</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadPixmap</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine useful cursor sizes, use
+<function>XQueryBestCursor</function>.
+<indexterm significance="preferred"><primary>XQueryBestCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerybestcursor'>
+<funcprototype>
+  <funcdef>Status <function>XQueryBestCursor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Dr , which indicates the screen -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable(Dr. 
+<!-- .ds Wh \ of the cursor that you want the size information for -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the best width and height that is closest to the specified width 
+and height.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Some displays allow larger cursors than other displays.
+The
+<function>XQueryBestCursor</function>
+function provides a way to find out what size cursors are actually
+possible on the display.
+<indexterm ><primary>Cursor</primary><secondary>limitations</secondary></indexterm>
+It returns the largest size that can be displayed.
+Applications should be prepared to use smaller cursors on displays that
+cannot support large ones.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryBestCursor</function>
+can generate a
+<errorname>BadDrawable</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the color of a given cursor, use
+<function>XRecolorCursor</function>.
+<indexterm significance="preferred"><primary>XRecolorCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrecolorcursor'>
+<funcprototype>
+  <funcdef><function>XRecolorCursor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+  <paramdef>XColor*foreground_color,<parameter> *background_color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>cursor</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the cursor. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>foreground_color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the <acronym>RGB</acronym> values for the foreground of the source. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>background_color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the <acronym>RGB</acronym> values for the background of the source.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRecolorCursor</function>
+function changes the color of the specified cursor, and
+if the cursor is being displayed on a screen,
+the change is visible immediately.
+The pixel members of the
+<structname>XColor</structname>
+structures are ignored; only the <acronym>RGB</acronym> values are used.
+</para>
+<para>
+<!-- .LP -->
+<function>XRecolorCursor</function>
+can generate a
+<errorname>BadCursor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free (destroy) a given cursor, use
+<function>XFreeCursor</function>.
+<indexterm significance="preferred"><primary>XFreeCursor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreecursor'>
+<funcprototype>
+  <funcdef><function>XFreeCursor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>cursor</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the cursor. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XFreeCursor</function>
+function deletes the association between the cursor resource ID 
+and the specified cursor.
+The cursor storage is freed when no other resource references it.
+The specified cursor ID should not be referred to again.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeCursor</function>
+can generate a
+<errorname>BadCursor</errorname>
+error.
+<!-- .bp -->
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH06.xml b/libX11/specs/libX11/CH06.xml
index a8224d8fc..ab5cec031 100644
--- a/libX11/specs/libX11/CH06.xml
+++ b/libX11/specs/libX11/CH06.xml
@@ -1,7448 +1,7448 @@
-<?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="color_management_functions">

-<title>Color Management Functions</title>

-<!-- .sp 2 -->

-<!-- .nr H1 6 -->

-<!-- .nr H2 0 -->

-<!-- .nr H3 0 -->

-<!-- .nr H4 0 -->

-<!-- .nr H5 0 -->

-<!-- .na -->

-<para>

-<!-- .LP -->

-<!-- .XS -->

-<!-- Chapter 6: Color Management Functions  -->

-<!-- .XE -->

-Each X window always has an associated colormap that

-provides a level of indirection between pixel values and colors displayed

-on the screen.

-Xlib provides functions that you can use to manipulate a colormap.

-The X protocol defines colors using values in the <acronym>RGB</acronym> color space.

-The <acronym>RGB</acronym> color space is device dependent;

-rendering an <acronym>RGB</acronym> value on differing output devices typically results

-in different colors.

-Xlib also provides a means for clients to specify color using

-device-independent color spaces for consistent results across devices.

-Xlib supports device-independent color spaces derivable from the <acronym>CIE</acronym> XYZ

-color space.

-This includes the <acronym>CIE</acronym> XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as

-the TekHVC color space.

-</para>

-<para>

-<!-- .LP -->

-This chapter discusses how to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Create, copy, and destroy a colormap

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Specify colors by name or value

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Allocate, modify, and free color cells

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Read entries in a colormap

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Convert between color spaces

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Control aspects of color conversion

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Query the color gamut of a screen

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Add new color spaces

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-All functions, types, and symbols in this chapter with the prefix ``Xcms''

-are defined in

-<filename class="headerfile">&lt;X11/Xcms.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xcms.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xcms.h&gt;</filename></secondary></indexterm>

-The remaining functions and types are defined in

-<filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-Functions in this chapter manipulate the representation of color on the

-screen.

-For each possible value that a pixel can take in a window,

-there is a color cell in the colormap.

-For example, 

-if a window is 4 bits deep, pixel values 0 through 15 are defined. 

-A colormap is a collection of color cells.

-A color cell consists of a triple of red, green, and blue (<acronym>RGB</acronym>) values.

-The hardware imposes limits on the number of significant

-bits in these values.

-As each pixel is read out of display memory, the pixel

-is looked up in a colormap.

-The <acronym>RGB</acronym> value of the cell determines what color is displayed on the screen.

-On a grayscale display with a black-and-white monitor, 

-the values are combined to determine the brightness on the screen.

-</para>

-<para>

-<!-- .LP -->

-Typically, an application allocates color cells or sets of color cells

-to obtain the desired colors.

-The client can allocate read-only cells.

-In which case, 

-the pixel values for these colors can be shared among multiple applications, 

-and the <acronym>RGB</acronym> value of the cell cannot be changed.

-If the client allocates read/write cells,

-they are exclusively owned by the client,

-and the color associated with the pixel value can be changed at will.

-Cells must be allocated (and, if read/write, initialized with an <acronym>RGB</acronym> value)

-by a client to obtain desired colors.

-The use of pixel value for an

-unallocated cell results in an undefined color.

-</para>

-<para>

-<!-- .LP -->

-Because colormaps are associated with windows, X supports displays

-with multiple colormaps and, indeed, different types of colormaps.

-If there are insufficient colormap resources in the display,

-some windows will display in their true colors, and others

-will display with incorrect colors.

-A window manager usually controls which windows are displayed

-in their true colors if more than one colormap is required for

-the color resources the applications are using.

-At any time, there is a set of installed colormaps for a screen.

-Windows using one of the installed colormaps display with true colors, and

-windows using other colormaps generally display with incorrect colors.

-You can control the set of installed colormaps by using

-<function>XInstallColormap</function>

-and

-<function>XUninstallColormap</function>.

-</para>

-<para>

-<!-- .LP -->

-Colormaps are local to a particular screen.

-Screens always have a default colormap,

-and programs typically allocate cells out of this colormap.

-Generally, you should not write applications that monopolize 

-color resources.

-Although some hardware supports multiple colormaps installed at one time,

-many of the hardware displays

-built today support only a single installed colormap, so the primitives

-are written to encourage sharing of colormap entries between applications.

-</para>

-<para>

-<!-- .LP -->

-The 

-<function>DefaultColormap</function>

-macro returns the default colormap.

-The 

-<function>DefaultVisual</function>

-macro

-returns the default visual type for the specified screen.

-<indexterm><primary>Color map</primary></indexterm>

-Possible visual types are 

-<symbol>StaticGray</symbol>,

-<symbol>GrayScale</symbol>,

-<symbol>StaticColor</symbol>,

-<symbol>PseudoColor</symbol>,

-<symbol>TrueColor</symbol>,

-or 

-<symbol>DirectColor</symbol>

-(see section 3.1).

-</para>

-<sect1 id="Color_Structures">

-<title>Color Structures</title>

-<!-- .XS -->

-<!-- (SN Color Structures -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Functions that operate only on <acronym>RGB</acronym> color space values use an

-<structname>XColor</structname>

-structure, which contains:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XColor</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	unsigned long pixel;	/* pixel value */

-	unsigned short red, green, blue;	/* rgb values */

-	char flags;	/* DoRed, DoGreen, DoBlue */	

-	char pad;

-} XColor;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The red, green, and blue values are always in the range 0 to 65535

-inclusive, independent of the number of bits actually used in the

-display hardware.

-The server scales these values down to the range used by the hardware.

-Black is represented by (0,0,0), 

-and white is represented by (65535,65535,65535).

-<indexterm><primary>Color</primary></indexterm>

-In some functions,

-the flags member controls which of the red, green, and blue members is used 

-and can be the inclusive OR of zero or more of

-<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and 

-<symbol>DoBlue</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-Functions that operate on all color space values use an

-<structname>XcmsColor</structname>

-structure.

-This structure contains a union of substructures,

-each supporting color specification encoding for a particular color space.

-Like the

-<structname>XColor</structname>

-structure, the

-<structname>XcmsColor</structname>

-structure contains pixel

-and color specification information (the spec member in the 

-<structname>XcmsColor</structname>

-structure).

-<indexterm significance="preferred"><primary>XcmsColor</primary></indexterm>

-<!-- .sM -->

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 1i 2.5i -->

-<!-- .ta .5i 1i 2.5i -->

-typedef unsigned long XcmsColorFormat;			/* Color Specification Format */

-

-typedef struct {

-	union {

-		XcmsRGB RGB;

-		XcmsRGBi RGBi;

-		XcmsCIEXYZ CIEXYZ;

-		XcmsCIEuvY CIEuvY;

-		XcmsCIExyY CIExyY;

-		XcmsCIELab CIELab;

-		XcmsCIELuv CIELuv;

-		XcmsTekHVC TekHVC;

-		XcmsPad Pad;

-	} spec;

-	unsigned long pixel;

-	XcmsColorFormat format;

-} XcmsColor;			/* Xcms Color Structure */

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Because the color specification can be encoded for the various color spaces, 

-encoding for the spec member is identified by the format member,

-which is of type

-<type>XcmsColorFormat</type>.

-The following macros define standard formats.

-<!-- .sM -->

-</para>

-

-<literallayout class="monospaced">

-#define          XcmsUndefinedFormat   0x00000000

-#define          XcmsCIEXYZFormat      0x00000001  /* CIE XYZ */

-#define          XcmsCIEuvYFormat      0x00000002  /* CIE u'v'Y */

-#define          XcmsCIExyYFormat      0x00000003  /* CIE xyY */

-#define          XcmsCIELabFormat      0x00000004  /* CIE L*a*b* */

-#define          XcmsCIELuvFormat      0x00000005  /* CIE L*u*v* */

-#define          XcmsTekHVCFormat      0x00000006  /* TekHVC */

-#define          XcmsRGBFormat         0x80000000  /* RGB Device */

-#define          XcmsRGBiFormat        0x80000001  /* RGB Intensity */

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Formats for device-independent color spaces are

-distinguishable from those for device-dependent spaces by the 32nd bit.

-If this bit is set,

-it indicates that the color specification is in a device-dependent form;

-otherwise, it is in a device-independent form.

-If the 31st bit is set,

-this indicates that the color space has been added to Xlib at run time

-(see section 6.12.4).

-The format value for a color space added at run time may be different each

-time the program is executed.

-If references to such a color space must be made outside the client

-(for example, storing a color specification in a file),

-then reference should be made by color space string prefix

-(see 

-<function>XcmsFormatOfPrefix</function>

-and

-<function>XcmsPrefixOfFormat</function>).

-</para>

-<para>

-<!-- .LP -->

-Data types that describe the color specification encoding for the various

-color spaces are defined as follows:

-<!-- .sM -->

-<indexterm significance="preferred"><primary>XcmsRGB</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef double XcmsFloat;

-

-typedef struct {

-	unsigned short red;	/* 0x0000 to 0xffff */

-	unsigned short green;	/* 0x0000 to 0xffff */

-	unsigned short blue;	/* 0x0000 to 0xffff */

-} XcmsRGB;		/* RGB Device */

-</literallayout>

-<indexterm significance="preferred"><primary>XcmsRGBi</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	XcmsFloat red;	/* 0.0 to 1.0 */

-	XcmsFloat green;	/* 0.0 to 1.0 */

-	XcmsFloat blue;	/* 0.0 to 1.0 */

-} XcmsRGBi;		/* RGB Intensity */

-</literallayout>

-<indexterm significance="preferred"><primary>XcmsCIEXYZ</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	XcmsFloat X;

-	XcmsFloat Y;	/* 0.0 to 1.0 */

-	XcmsFloat Z;

-} XcmsCIEXYZ;		/* CIE XYZ */

-</literallayout>

-<indexterm significance="preferred"><primary>XcmsCIEuvY</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	XcmsFloat u_prime;	/* 0.0 to ~0.6 */

-	XcmsFloat v_prime;	/* 0.0 to ~0.6 */

-	XcmsFloat Y; 	/* 0.0 to 1.0 */

-} XcmsCIEuvY;		/* CIE u'v'Y */

-</literallayout>

-<indexterm significance="preferred"><primary>XcmsCIExyY</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	XcmsFloat x; 	/* 0.0 to ~.75 */

-	XcmsFloat y; 	/* 0.0 to ~.85 */

-	XcmsFloat Y; 	/* 0.0 to 1.0 */

-} XcmsCIExyY;		/* CIE xyY */

-</literallayout>

-<indexterm significance="preferred"><primary>XcmsCIELab</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	XcmsFloat L_star; 	/* 0.0 to 100.0 */

-	XcmsFloat a_star;

-	XcmsFloat b_star;

-} XcmsCIELab;		/* CIE L*a*b* */

-</literallayout>

-<indexterm significance="preferred"><primary>XcmsCIELuv</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	XcmsFloat L_star; 	/* 0.0 to 100.0 */

-	XcmsFloat u_star;

-	XcmsFloat v_star;

-} XcmsCIELuv;		/* CIE L*u*v* */

-</literallayout>

-<indexterm significance="preferred"><primary>XcmsTekHVC</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	XcmsFloat H; 	/* 0.0 to 360.0 */

-	XcmsFloat V; 	/* 0.0 to 100.0 */

-	XcmsFloat C; 	/* 0.0 to 100.0 */

-} XcmsTekHVC;		/* TekHVC */

-</literallayout>

-<indexterm significance="preferred"><primary>XcmsPad</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	XcmsFloat pad0;

-	XcmsFloat pad1;

-	XcmsFloat pad2;

-	XcmsFloat pad3;

-} XcmsPad;		/* four doubles */

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The device-dependent formats provided allow color specification in:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-<acronym>RGB</acronym> Intensity

-(<structname>XcmsRGBi</structname>)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Red, green, and blue linear intensity values,

-floating-point values from 0.0 to 1.0,

-where 1.0 indicates full intensity, 0.5 half intensity, and so on.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<acronym>RGB</acronym> Device

-(<structname>XcmsRGB</structname>)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Red, green, and blue values appropriate for the specified output device.

-<structname>XcmsRGB</structname>

-values are of type unsigned short,

-scaled from 0 to 65535 inclusive,

-and are interchangeable with the red, green, and blue values in an 

-<structname>XColor</structname>

-structure. 

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-It is important to note that <acronym>RGB</acronym> Intensity values are not gamma corrected

-values.

-In contrast,

-<acronym>RGB</acronym> Device values generated as a result of converting color specifications 

-are always gamma corrected, and

-<acronym>RGB</acronym> Device values acquired as a result of querying a colormap

-or passed in by the client are assumed by Xlib to be gamma corrected.

-The term <emphasis remap='I'><acronym>RGB</acronym> value</emphasis> in this manual always refers to an <acronym>RGB</acronym> Device value.

-</para>

-</sect1>

-<sect1 id="Color_Strings">

-<title>Color Strings</title>

-<!-- .XS -->

-<!-- (SN Color Strings -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides a mechanism for using string names for colors.

-A color string may either contain an abstract color name

-or a numerical color specification.

-Color strings are case-insensitive.

-</para>

-<para>

-<!-- .LP -->

-Color strings are used in the following functions:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-<function>XAllocNamedColor</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsAllocNamedColor</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XLookupColor</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsLookupColor</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XParseColor</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XStoreNamedColor</function>

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Xlib supports the use of abstract color names, for example, red or blue.

-A value for this abstract name is obtained by searching one or more color

-name databases.

-Xlib first searches zero or more client-side databases;

-the number, location, and content of these databases is

-implementation-dependent and might depend on the current locale.

-If the name is not found, Xlib then looks for the color in the

-X server's database.

-If the color name is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-A numerical color specification

-consists of a color space name and a set of values in the following syntax:

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-<emphasis remap='I'>&lt;color_space_name&gt;</emphasis>:<emphasis remap='I'>&lt;value&gt;/.../&lt;value&gt;</emphasis>

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The following are examples of valid color strings.

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-"CIEXYZ:0.3227/0.28133/0.2493"

-"RGBi:1.0/0.0/0.0"

-"rgb:00/ff/00"

-"CIELuv:50.0/0.0/0.0"

-</literallayout>

-The syntax and semantics of numerical specifications are given

-for each standard color space in the following sections.

-</para>

-<sect2 id="RGB_Device_String_Specification">

-<title><acronym>RGB</acronym> Device String Specification</title>

-<!-- .XS -->

-<!-- (SN <acronym>RGB</acronym> Device String Specification -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-An <acronym>RGB</acronym> Device specification is identified by

-the prefix ``rgb:'' and conforms to the following syntax:

-</para>

-<para>

-<!-- .LP -->

-<!-- .\" Start marker code here -->

-<literallayout class="monospaced">

-rgb:<emphasis remap='I'>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</emphasis>

-

-    <emphasis remap='I'>&lt;red&gt;</emphasis>, <emphasis remap='I'>&lt;green&gt;</emphasis>, <emphasis remap='I'>&lt;blue&gt;</emphasis> := <emphasis remap='I'>h</emphasis> | <emphasis remap='I'>hh</emphasis> | <emphasis remap='I'>hhh</emphasis> | <emphasis remap='I'>hhhh</emphasis>

-    <emphasis remap='I'>h</emphasis> := single hexadecimal digits (case insignificant)

-</literallayout>

-<!-- .\" End marker code here -->

-</para>

-<para>

-<!-- .LP -->

-Note that <emphasis remap='I'>h</emphasis> indicates the value scaled in 4 bits, 

-<emphasis remap='I'>hh</emphasis> the value scaled in 8 bits,

-<emphasis remap='I'>hhh</emphasis> the value scaled in 12 bits,

-and <emphasis remap='I'>hhhh</emphasis> the value scaled in 16 bits, respectively.

-</para>

-<para>

-<!-- .LP -->

-Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'',

-but mixed numbers of hexadecimal digit strings 

-(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'')

-are also allowed.

-</para>

-<para>

-<!-- .LP -->

-For backward compatibility, an older syntax for <acronym>RGB</acronym> Device is

-supported, but its continued use is not encouraged.

-The syntax is an initial sharp sign character followed by

-a numeric specification, in one of the following formats:

-</para>

-<para>

-<!-- .LP -->

-<!-- .\" Start marker code here -->

-<literallayout class="monospaced">

-<!-- .TA 2i -->

-<!-- .ta 2i -->

-#RGB	(4 bits each)

-#RRGGBB	(8 bits each)

-#RRRGGGBBB	(12 bits each)

-#RRRRGGGGBBBB	(16 bits each)

-</literallayout>

-<!-- .\" End marker code here -->

-</para>

-<para>

-<!-- .LP -->

-The R, G, and B represent single hexadecimal digits.

-When fewer than 16 bits each are specified, 

-they represent the most significant bits of the value

-(unlike the ``rgb:'' syntax, in which values are scaled).

-For example, the string ``#3a7'' is the same as ``#3000a0007000''.

-</para>

-</sect2>

-<sect2 id="RGB_Intensity_String_Specification">

-<title><acronym>RGB</acronym> Intensity String Specification</title>

-<!-- .XS -->

-<!-- (SN RGB Intensity String Specification -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-An <acronym>RGB</acronym> intensity specification is identified

-by the prefix ``rgbi:'' and conforms to the following syntax:

-</para>

-<para>

-<!-- .LP -->

-<!-- .\" Start marker code here -->

-<literallayout class="monospaced">

-rgbi:<emphasis remap='I'>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</emphasis>

-</literallayout>

-<!-- .\" End marker code here -->

-</para>

-<para>

-<!-- .LP -->

-Note that red, green, and blue are floating-point values

-between 0.0 and 1.0, inclusive.

-The input format for these values is an optional sign,

-a string of numbers possibly containing a decimal point,

-and an optional exponent field containing an E or e 

-followed by a possibly signed integer string.

-</para>

-</sect2>

-<sect2 id="Device_Independent_String_Specifications">

-<title>Device-Independent String Specifications</title>

-<!-- .XS -->

-<!-- (SN Device-Independent String Specifications -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The standard device-independent string specifications have

-the following syntax:

-</para>

-<para>

-<!-- .LP -->

-<!-- .\" Start marker code here -->

-<literallayout class="monospaced">

-CIEXYZ:<emphasis remap='I'>&lt;X&gt;/&lt;Y&gt;/&lt;Z&gt;</emphasis>

-CIEuvY:<emphasis remap='I'>&lt;u&gt;/&lt;v&gt;/&lt;Y&gt;</emphasis>

-CIExyY:<emphasis remap='I'>&lt;x&gt;/&lt;y&gt;/&lt;Y&gt;</emphasis>

-CIELab:<emphasis remap='I'>&lt;L&gt;/&lt;a&gt;/&lt;b&gt;</emphasis>

-CIELuv:<emphasis remap='I'>&lt;L&gt;/&lt;u&gt;/&lt;v&gt;</emphasis>

-TekHVC:<emphasis remap='I'>&lt;H&gt;/&lt;V&gt;/&lt;C&gt;</emphasis>

-</literallayout>

-<!-- .\" End marker code here -->

-</para>

-<para>

-<!-- .LP -->

-All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are

-floating-point values.

-The syntax for these values is an optional plus or minus sign,

-a string of digits possibly containing a decimal point,

-and an optional exponent field consisting of an ``E'' or ``e''

-followed by an optional plus or minus followed by a string of digits.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Color_Conversion_Contexts_and_Gamut_Mapping">

-<title>Color Conversion Contexts and Gamut Mapping</title>

-<!-- .XS -->

-<!-- (SN Color Conversion Contexts and Gamut Mapping -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-When Xlib converts device-independent color specifications

-into device-dependent specifications and vice versa,

-it uses knowledge about the color limitations of the screen hardware.

-This information, typically called the device profile,

-<indexterm><primary>Device profile</primary></indexterm>

-is available in a Color Conversion Context (CCC).

-<indexterm><primary>Color Conversion Context</primary></indexterm>

-<indexterm><primary>CCC</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-Because a specified color may be outside the color gamut of the target screen

-and the white point associated with the color specification may differ

-from the white point inherent to the screen,

-Xlib applies gamut mapping when it encounters certain conditions:

-<indexterm><primary>White point</primary></indexterm>

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Gamut compression occurs when conversion of device-independent

-color specifications to device-dependent color specifications

-results in a color out of the target screen's gamut.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-White adjustment occurs when the inherent white point of the screen

-differs from the white point assumed by the client.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Gamut handling methods are stored as callbacks in the CCC,

-which in turn are used by the color space conversion routines.

-Client data is also stored in the CCC for each callback.

-The CCC also contains the white point the client assumes to be

-associated with color specifications (that is, the Client White Point).

-<indexterm><primary>Client White Point</primary></indexterm>

-<indexterm><primary>Gamut compression</primary></indexterm>

-<indexterm><primary>Gamut handling</primary></indexterm>

-<indexterm><primary>White point adjustment</primary></indexterm>

-The client can specify the gamut handling callbacks and client data

-as well as the Client White Point.

-Xlib does not preclude the X client from performing other

-forms of gamut handling (for example, gamut expansion); 

-however, Xlib does not provide direct support for gamut handling

-other than white adjustment and gamut compression.

-</para>

-<para>

-<!-- .LP -->

-Associated with each colormap is an initial CCC transparently generated by

-Xlib.

-<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>

-Therefore,

-when you specify a colormap as an argument to an Xlib function,

-you are indirectly specifying a CCC.

-<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>

-There is a default CCC associated with each screen.

-Newly created CCCs inherit attributes from the default CCC,

-so the default CCC attributes can be modified to affect new CCCs.

-<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-Xcms functions in which gamut mapping can occur return

-<type>Status</type>

-and have specific status values defined for them, 

-as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-<symbol>XcmsFailure</symbol>

-indicates that the function failed.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<symbol>XcmsSuccess</symbol>

-indicates that the function succeeded.

-In addition,

-if the function performed any color conversion,

-the colors did not need to be compressed.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<symbol>XcmsSuccessWithCompression</symbol>

-indicates the function performed color conversion

-and at least one of the colors needed to be compressed.

-The gamut compression method is determined by the gamut compression

-procedure in the CCC that is specified directly as a function argument

-or in the CCC indirectly specified by means of the colormap argument.

-    </para>

-  </listitem>

-</itemizedlist>

-</sect1>

-<sect1 id="Creating_Copying_and_Destroying_Colormaps">

-<title>Creating, Copying, and Destroying Colormaps</title>

-<!-- .XS -->

-<!-- (SN Creating, Copying, and Destroying Colormaps -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To create a colormap for a screen, use

-<function>XCreateColormap</function>.</para>

-<indexterm significance="preferred"><primary>XCreateColormap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Colormap <function>XCreateColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Visual<parameter> *visual</parameter></paramdef>

-  <paramdef>int<parameter> alloc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi on whose screen you want to create a colormap -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>visual</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a visual type supported on the screen.

-If the visual type is not one supported by the screen, 

-a

-<errorname>BadMatch</errorname>

-error results.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>alloc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap entries to be allocated.

-You can pass 

-<symbol>AllocNone</symbol>

-or 

-<symbol>AllocAll</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateColormap</function>

-function creates a colormap of the specified visual type for the screen 

-on which the specified window resides and returns the colormap ID 

-associated with it.

-Note that the specified window is only used to determine the screen.

-</para>

-<para>

-<!-- .LP -->

-The initial values of the colormap entries are undefined for the 

-visual classes

-<symbol>GrayScale</symbol>,

-<symbol>PseudoColor</symbol>,

-and

-<symbol>DirectColor</symbol>.

-For

-<symbol>StaticGray</symbol>,

-<symbol>StaticColor</symbol>,

-and

-<symbol>TrueColor</symbol>,

-the entries have defined values,

-but those values are specific to the visual and are not defined by X.

-For

-<symbol>StaticGray</symbol>,

-<symbol>StaticColor</symbol>,

-and

-<symbol>TrueColor</symbol>,

-alloc must be

-<symbol>AllocNone</symbol>,

-or a

-<errorname>BadMatch</errorname>

-error results.

-For the other visual classes,

-if alloc is

-<symbol>AllocNone</symbol>,

-the colormap initially has no allocated entries,

-and clients can allocate them.

-For information about the visual types,

-see section 3.1.

-</para>

-<para>

-<!-- .LP -->

-If alloc is

-<symbol>AllocAll</symbol>,

-the entire colormap is allocated writable.

-The initial values of all allocated entries are undefined.

-For

-<symbol>GrayScale</symbol>

-and

-<symbol>PseudoColor</symbol>,

-the effect is as if an

-<function>XAllocColorCells</function>

-call returned all pixel values from zero to N - 1,

-where N is the colormap entries value in the specified visual.

-For

-<symbol>DirectColor</symbol>,

-the effect is as if an

-<function>XAllocColorPlanes</function>

-call returned a pixel value of zero and red_mask, green_mask, 

-and blue_mask values containing the same bits as the corresponding

-masks in the specified visual.

-However, in all cases,

-none of these entries can be freed by using

-<function>XFreeColors</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateColormap</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadMatch</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a new colormap when the allocation out of a previously

-shared colormap has failed because of resource exhaustion, use

-<function>XCopyColormapAndFree</function>.

-<indexterm significance="preferred"><primary>XCopyColormapAndFree</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Colormap <function>XCopyColormapAndFree</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCopyColormapAndFree</function>

-function creates a colormap of the same visual type and for the same screen

-as the specified colormap and returns the new colormap ID.

-It also moves all of the client's existing allocation from the specified

-colormap to the new colormap with their color values intact 

-and their read-only or writable characteristics intact and frees those entries 

-in the specified colormap.

-Color values in other entries in the new colormap are undefined.

-If the specified colormap was created by the client with alloc set to

-<symbol>AllocAll</symbol>,

-the new colormap is also created with 

-<symbol>AllocAll</symbol>,

-all color values for all entries are copied from the specified colormap,

-and then all entries in the specified colormap are freed.

-If the specified colormap was not created by the client with

-<symbol>AllocAll</symbol>,

-the allocations to be moved are all those pixels and planes

-that have been allocated by the client using

-<function>XAllocColor</function>,

-<function>XAllocNamedColor</function>,

-<function>XAllocColorCells</function>,

-or

-<function>XAllocColorPlanes</function>

-and that have not been freed since they were allocated.

-</para>

-<para>

-<!-- .LP -->

-<function>XCopyColormapAndFree</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadColor</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To destroy a colormap, use 

-<function>XFreeColormap</function>.

-<indexterm significance="preferred"><primary>XFreeColormap</primary></indexterm>

-</para>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Cm that you want to destroy -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap (Cm.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeColormap</function>

-function deletes the association between the colormap resource ID 

-and the colormap and frees the colormap storage.

-However, this function has no effect on the default colormap for a screen.

-If the specified colormap is an installed map for a screen,

-it is uninstalled (see

-<function>XUninstallColormap</function>).

-If the specified colormap is defined as the colormap for a window (by

-<function>XCreateWindow</function>,

-<function>XSetWindowColormap</function>,

-or

-<function>XChangeWindowAttributes</function>),

-<function>XFreeColormap</function>

-changes the colormap associated with the window to

-<symbol>None</symbol>

-and generates a

-<symbol>ColormapNotify</symbol>

-event.

-X does not define the colors displayed for a window with a colormap of

-<symbol>None</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<function>XFreeColormap</function>

-can generate a

-<errorname>BadColor</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Mapping_Color_Names_to_Values">

-<title>Mapping Color Names to Values</title>

-<!-- .XS -->

-<!-- (SN Mapping Color Names to Values -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To map a color name to an <acronym>RGB</acronym> value, use

-<function>XLookupColor</function>.

-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

-<indexterm significance="preferred"><primary>XLookupColor</primary></indexterm>

-<!-- .sM -->

-</para>

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XLookupColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>char<parameter> *color_name</parameter></paramdef>

-  <paramdef>XColor*exact_def_return,<parameter> *screen_def_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color name string (for example, red) whose color 

-definition structure you want returned.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>exact_def_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the exact <acronym>RGB</acronym> values.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_def_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the closest <acronym>RGB</acronym> values provided by the hardware.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLookupColor</function>

-function looks up the string name of a color with respect to the screen

-associated with the specified colormap.

-It returns both the exact color values and

-the closest values provided by the screen 

-with respect to the visual type of the specified colormap.

-If the color name is not in the Host Portable Character Encoding, 

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-<function>XLookupColor</function>

-returns nonzero if the name is resolved;

-otherwise, it returns zero.

-</para>

-<para>

-<!-- .LP -->

-<function>XLookupColor</function>

-can generate a

-<errorname>BadColor</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To map a color name to the exact <acronym>RGB</acronym> value, use

-<function>XParseColor</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

-<indexterm significance="preferred"><primary>XParseColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XParseColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>char<parameter> *spec</parameter></paramdef>

-  <paramdef>XColor<parameter> *exact_def_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>spec</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color name string;

-case is ignored.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>exact_def_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the exact color value for later use and sets the

-<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and

-<symbol>DoBlue</symbol>

-flags.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XParseColor</function>

-function looks up the string name of a color with respect to the screen

-associated with the specified colormap.

-It returns the exact color value.

-If the color name is not in the Host Portable Character Encoding, 

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-<function>XParseColor</function>

-returns nonzero if the name is resolved;

-otherwise, it returns zero.

-</para>

-<para>

-<!-- .LP -->

-<function>XParseColor</function>

-can generate a

-<errorname>BadColor</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To map a color name to a value in an arbitrary color space, use

-<function>XcmsLookupColor</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsLookupColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsLookupColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>char<parameter> *color_string</parameter></paramdef>

-  <paramdef>XcmsColor*color_exact_return,<parameter> *color_screen_return</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-<!-- .ds St -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color string(St.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_exact_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color specification parsed from the color string

-or parsed from the corresponding string found in a color-name database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_screen_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color that can be reproduced on the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>result_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color format for the returned color

-specifications (color_screen_return and color_exact_return arguments).

-If the format is

-<symbol>XcmsUndefinedFormat</symbol>

-and the color string contains a

-numerical color specification,

-the specification is returned in the format used in that numerical

-color specification.

-If the format is

-<symbol>XcmsUndefinedFormat</symbol>

-and the color string contains a color name,

-the specification is returned in the format used 

-to store the color in the database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsLookupColor</function>

-function looks up the string name of a color with respect to the screen

-associated with the specified colormap.

-It returns both the exact color values and

-the closest values provided by the screen 

-with respect to the visual type of the specified colormap.

-The values are returned in the format specified by result_format.

-If the color name is not in the Host Portable Character Encoding, 

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-<function>XcmsLookupColor</function>

-returns

-<symbol>XcmsSuccess</symbol>

-or

-<symbol>XcmsSuccessWithCompression</symbol>

-if the name is resolved; otherwise, it returns

-<symbol>XcmsFailure</symbol>.

-If

-<symbol>XcmsSuccessWithCompression</symbol>

-is returned, the color specification returned in 

-color_screen_return is the result of gamut compression.

-</para>

-</sect1>

-

-<sect1 id="Allocating_and_Freeing_Color_Cells">

-<title>Allocating and Freeing Color Cells</title>

-<!-- .XS -->

-<!-- (SN Allocating and Freeing Color Cells -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-There are two ways of allocating color cells: 

-explicitly as read-only entries, one pixel value at a time,

-or read/write,

-where you can allocate a number of color cells and planes simultaneously.

-<indexterm><primary>Read-only colormap cells</primary></indexterm>

-A read-only cell has its <acronym>RGB</acronym> value set by the server.

-<indexterm><primary>Read/write colormap cells</primary></indexterm>

-Read/write cells do not have defined colors initially;

-functions described in the next section must be used to store values into them.

-Although it is possible for any client to store values into a read/write

-cell allocated by another client,

-read/write cells normally should be considered private to the client

-that allocated them.

-</para>

-<para>

-<!-- .LP -->

-Read-only colormap cells are shared among clients.

-The server counts each allocation and freeing of the cell by clients.

-When the last client frees a shared cell, the cell is finally deallocated.

-If a single client allocates the same read-only cell multiple

-times, the server counts each such allocation, not just the first one.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate a read-only color cell with an <acronym>RGB</acronym> value, use

-<function>XAllocColor</function>.

-</para>

-<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>

-<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

-<indexterm significance="preferred"><primary>XAllocColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XAllocColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XColor<parameter> *screen_in_out</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies and returns the values actually used in the colormap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAllocColor</function>

-function allocates a read-only colormap entry corresponding to the closest

-<acronym>RGB</acronym> value supported by the hardware.

-<function>XAllocColor</function>

-returns the pixel value of the color closest to the specified

-<acronym>RGB</acronym> elements supported by the hardware

-and returns the <acronym>RGB</acronym> value actually used.

-The corresponding colormap cell is read-only.

-In addition,

-<function>XAllocColor</function>

-returns nonzero if it succeeded or zero if it failed.

-<indexterm><primary>Color map</primary></indexterm>

-<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

-<indexterm><primary>Allocation</primary><secondary>colormap</secondary></indexterm>

-<indexterm><primary>read-only colormap cells</primary></indexterm>

-Multiple clients that request the same effective <acronym>RGB</acronym> value can be assigned

-the same read-only entry, thus allowing entries to be shared.

-When the last client deallocates a shared cell, it is deallocated.

-<function>XAllocColor</function>

-does not use or affect the flags in the

-<structname>XColor</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-<function>XAllocColor</function>

-can generate a

-<errorname>BadColor</errorname>

-error.

-<!-- .EQ -->

-delim %%

-<!-- .EN -->

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate a read-only color cell with a color in arbitrary format, use

-<function>XcmsAllocColor</function>.

-</para>

-<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>

-<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsAllocColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsAllocColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_in_out</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color to allocate and returns the pixel and color 

-that is actually used in the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>result_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color format for the returned color specification.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsAllocColor</function>

-function is similar to

-<function>XAllocColor</function>

-except the color can be specified in any format.

-The

-<function>XcmsAllocColor</function>

-function ultimately calls 

-<function>XAllocColor</function>

-to allocate a read-only color cell (colormap entry) with the specified color.

-<function>XcmsAllocColor</function>

-first converts the color specified

-to an <acronym>RGB</acronym> value and then passes this to

-<function>XAllocColor</function>.

-<function>XcmsAllocColor</function>

-returns the pixel value of the color cell and the color specification

-actually allocated.

-This returned color specification is the result of converting the <acronym>RGB</acronym> value

-returned by 

-<function>XAllocColor</function>

-into the format specified with the result_format argument.

-If there is no interest in a returned color specification, 

-unnecessary computation can be bypassed if result_format is set to

-<symbol>XcmsRGBFormat</symbol>.

-The corresponding colormap cell is read-only.

-If this routine returns 

-<symbol>XcmsFailure</symbol>,

-the color_in_out color specification is left unchanged.

-</para>

-<para>

-<!-- .LP -->

-<function>XcmsAllocColor</function>

-can generate a

-<errorname>BadColor</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate a read-only color cell using a color name and return the closest

-color supported by the hardware in <acronym>RGB</acronym> format, use

-<function>XAllocNamedColor</function>.

-</para>

-<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>

-<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

-<indexterm significance="preferred"><primary>XAllocNamedColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XAllocNamedColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>char<parameter> *color_name</parameter></paramdef>

-  <paramdef>XColor*screen_def_return,<parameter> *exact_def_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color name string (for example, red) whose color 

-definition structure you want returned.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_def_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the closest <acronym>RGB</acronym> values provided by the hardware.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>exact_def_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the exact <acronym>RGB</acronym> values.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XAllocNamedColor</function>

-function looks up the named color with respect to the screen that is

-associated with the specified colormap.

-It returns both the exact database definition and

-the closest color supported by the screen.

-The allocated color cell is read-only.

-The pixel value is returned in screen_def_return.

-If the color name is not in the Host Portable Character Encoding, 

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-If screen_def_return and exact_def_return

-point to the same structure, the pixel field will be set correctly,

-but the color values are undefined.

-<function>XAllocNamedColor</function>

-returns nonzero if a cell is allocated;

-otherwise, it returns zero.

-</para>

-<para>

-<!-- .LP -->

-<function>XAllocNamedColor</function>

-can generate a

-<errorname>BadColor</errorname>

-error. 

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate a read-only color cell using a color name and return the closest

-color supported by the hardware in an arbitrary format, use

-<function>XcmsAllocNamedColor</function>.

-</para>

-<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>

-<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsAllocNamedColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsAllocNamedColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>char<parameter> *color_string</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_screen_return</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_exact_return</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-<!-- .ds St \ whose color definition structure is to be returned -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color string(St.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_screen_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the pixel value of the color cell and color specification 

-that actually is stored for that cell.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_exact_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color specification parsed from the color string

-or parsed from the corresponding string found in a color-name database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>result_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color format for the returned color

-specifications (color_screen_return and color_exact_return arguments).

-If the format is

-<symbol>XcmsUndefinedFormat</symbol>

-and the color string contains a

-numerical color specification,

-the specification is returned in the format used in that numerical

-color specification.

-If the format is

-<symbol>XcmsUndefinedFormat</symbol>

-and the color string contains a color name,

-the specification is returned in the format used 

-to store the color in the database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsAllocNamedColor</function>

-function is similar to

-<function>XAllocNamedColor</function>

-except that the color returned can be in any format specified.

-This function

-ultimately calls

-<function>XAllocColor</function>

-to allocate a read-only color cell with

-the color specified by a color string.

-The color string is parsed into an

-<structname>XcmsColor</structname>

-structure (see

-<function>XcmsLookupColor</function>),

-converted

-to an <acronym>RGB</acronym> value, and finally passed to

-<function>XAllocColor</function>.

-If the color name is not in the Host Portable Character Encoding, 

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-</para>

-<para>

-<!-- .LP -->

-This function returns both the color specification as a result

-of parsing (exact specification) and the actual color specification

-stored (screen specification).

-This screen specification is the result of converting the <acronym>RGB</acronym> value

-returned by

-<function>XAllocColor</function>

-into the format specified in result_format.

-If there is no interest in a returned color specification,

-unnecessary computation can be bypassed if result_format is set to

-<symbol>XcmsRGBFormat</symbol>.

-If color_screen_return and color_exact_return

-point to the same structure, the pixel field will be set correctly,

-but the color values are undefined.

-</para>

-<para>

-<!-- .LP -->

-<function>XcmsAllocNamedColor</function>

-can generate a

-<errorname>BadColor</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate read/write color cell and color plane combinations for a

-<symbol>PseudoColor</symbol>

-model, use

-<function>XAllocColorCells</function>.

-</para>

-<indexterm><primary>Read/write colormap cells</primary><secondary>allocating</secondary></indexterm>

-<indexterm><primary>Allocation</primary><secondary>read/write colormap cells</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

-<indexterm significance="preferred"><primary>XAllocColorCells</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XAllocColorCells</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>Bool<parameter> contig</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> plane_masks_return[]</parameter></paramdef>

-  <paramdef>unsignedint<parameter> nplanes</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>

-  <paramdef>unsignedint<parameter> npixels</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>contig</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether the planes must be contiguous.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>plane_mask_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of plane masks.

-<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nplanes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of plane masks that are to be returned in the plane masks 

-array. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pixels_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of pixel values. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>npixels</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of pixel values that are to be returned in the 

-pixels_return array. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAllocColorCells</function>

-function allocates read/write color cells.

-The number of colors must be positive and the number of planes nonnegative,

-or a

-<errorname>BadValue</errorname>

-error results.

-If ncolors and nplanes are requested, 

-then ncolors pixels

-and nplane plane masks are returned.

-No mask will have any bits set to 1 in common with

-any other mask or with any of the pixels.

-By ORing together each pixel with zero or more masks,

-ncolors &times; 2<superscript><emphasis>nplanes</emphasis></superscript>

-distinct pixels can be produced.

-All of these are

-allocated writable by the request.

-For 

-<symbol>GrayScale</symbol>

-or 

-<symbol>PseudoColor</symbol>,

-each mask has exactly one bit set to 1. 

-For 

-<symbol>DirectColor</symbol>,

-each has exactly three bits set to 1.

-If contig is 

-<symbol>True</symbol>

-and if all masks are ORed

-together, a single contiguous set of bits set to 1 will be formed for 

-<symbol>GrayScale</symbol>

-or 

-<symbol>PseudoColor</symbol>

-and three contiguous sets of bits set to 1 (one within each

-pixel subfield) for 

-<symbol>DirectColor</symbol>.

-The <acronym>RGB</acronym> values of the allocated

-entries are undefined.

-<function>XAllocColorCells</function>

-returns nonzero if it succeeded or zero if it failed.

-</para>

-<para>

-<!-- .LP -->

-<function>XAllocColorCells</function>

-can generate

-<errorname>BadColor</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate read/write color resources for a

-<symbol>DirectColor</symbol>

-model, use

-<function>XAllocColorPlanes</function>.

-</para>

-<indexterm><primary>Read/write colormap planes</primary><secondary>allocating</secondary></indexterm>

-<indexterm><primary>Allocation</primary><secondary>read/write colormap planes</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>

-<indexterm significance="preferred"><primary>XAllocColorPlanes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XAllocColorPlanes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>Bool<parameter> contig</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>

-  <paramdef>int<parameter> ncolors</parameter></paramdef>

-  <paramdef>intnreds,ngreens,<parameter> nblues</parameter></paramdef>

-  <paramdef>unsignedlong*rmask_return,*gmask_return,<parameter> *bmask_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>contig</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether the planes must be contiguous.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pixels_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of pixel values. 

-<function>XAllocColorPlanes</function>

-returns the pixel values in this array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of pixel values that are to be returned in the 

-pixels_return array. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nreds</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ngreens</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nblues</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-Specify the number of red, green, and blue planes.

-The value you pass must be nonnegative. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rmask_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gmask_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bmask_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return bit masks for the red, green, and blue planes.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The specified ncolors must be positive; 

-and nreds, ngreens, and nblues must be nonnegative,

-or a

-<errorname>BadValue</errorname>

-error results.

-If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, 

-ncolors pixels are returned; and the masks have nreds, ngreens, and 

-nblues bits set to 1, respectively.

-If contig is 

-<symbol>True</symbol>,

-each mask will have

-a contiguous set of bits set to 1.

-No mask will have any bits set to 1 in common with

-any other mask or with any of the pixels.

-For 

-<symbol>DirectColor</symbol>,

-each mask

-will lie within the corresponding pixel subfield.

-By ORing together

-subsets of masks with each pixel value, 

-ncolors &times; 2<superscript><emphasis>(nreds+ngreens+nblues)</emphasis></superscript>

-distinct pixel values can be produced.

-All of these are allocated by the request.

-However, in the

-colormap, there are only

-ncolors &times; 2<superscript><emphasis>nreds</emphasis></superscript>

-independent red entries,

-ncolors &times; 2<superscript><emphasis>ngreens</emphasis></superscript>

-independent green entries, and

-ncolors &times; 2<superscript><emphasis>nblues</emphasis></superscript>

-independent blue entries.

-This is true even for 

-<symbol>PseudoColor</symbol>.

-When the colormap entry of a pixel

-value is changed (using 

-<function>XStoreColors</function>,

-<function>XStoreColor</function>,

-or 

-<function>XStoreNamedColor</function>),

-the pixel is decomposed according to the masks, 

-and the corresponding independent entries are updated.

-<function>XAllocColorPlanes</function>

-returns nonzero if it succeeded or zero if it failed.

-</para>

-<para>

-<!-- .LP -->

-<function>XAllocColorPlanes</function>

-can generate

-<errorname>BadColor</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-<indexterm><primary>Freeing</primary><secondary>colors</secondary></indexterm>

-To free colormap cells, use

-<function>XFreeColors</function>.

-<indexterm significance="preferred"><primary>XFreeColors</primary></indexterm>

-<indexterm><primary>Color</primary><secondary>deallocation</secondary></indexterm>

-<!-- .sM -->

-</para>

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeColors</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> pixels[]</parameter></paramdef>

-  <paramdef>int<parameter> npixels</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> planes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-<!-- .ds Pi that map to the cells in the specified colormap -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pixels</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of pixel values (Pi. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>npixels</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of pixels. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>planes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the planes you want to free.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeColors</function>

-function frees the cells represented by pixels whose values are in the

-pixels array.

-The planes argument should not have any bits set to 1 in common with any of the

-pixels. 

-The set of all pixels is produced by ORing together subsets of

-the planes argument with the pixels.

-The request frees all of these pixels that

-were allocated by the client (using 

-<indexterm><primary>XAllocColor</primary></indexterm>

-<indexterm><primary>XAllocNamedColor</primary></indexterm>

-<indexterm><primary>XAllocColorCells</primary></indexterm>

-<indexterm><primary>XAllocColorPlanes</primary></indexterm>

-<function>XAllocColor</function>,

-<function>XAllocNamedColor</function>,

-<function>XAllocColorCells</function>,

-and 

-<function>XAllocColorPlanes</function>).

-Note that freeing an

-individual pixel obtained from 

-<function>XAllocColorPlanes</function>

-may not actually allow

-it to be reused until all of its related pixels are also freed.

-Similarly,

-a read-only entry is not actually freed until it has been freed by all clients,

-and if a client allocates the same read-only entry multiple times,

-it must free the entry that many times before the entry is actually freed.

-</para>

-<para>

-<!-- .LP -->

-All specified pixels that are allocated by the client in the colormap are

-freed, even if one or more pixels produce an error. 

-If a specified pixel is not a valid index into the colormap, a 

-<errorname>BadValue</errorname>

-error results.

-If a specified pixel is not allocated by the

-client (that is, is unallocated or is only allocated by another client)

-or if the colormap was created with all entries writable (by passing

-<symbol>AllocAll</symbol>

-to

-<function>XCreateColormap</function>),

-a

-<errorname>BadAccess</errorname>

-error results. 

-If more than one pixel is in error, 

-the one that gets reported is arbitrary.

-</para>

-<para>

-<!-- .LP -->

-<function>XFreeColors</function>

-can generate

-<errorname>BadAccess</errorname>,

-<errorname>BadColor</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Modifying_and_Querying_Colormap_Cells">

-<title>Modifying and Querying Colormap Cells</title>

-<!-- .XS -->

-<!-- (SN Modifying and Querying Colormap Cells  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To store an <acronym>RGB</acronym> value in a single colormap cell, use

-<function>XStoreColor</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XStoreColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XStoreColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XColor<parameter> *color</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the pixel and <acronym>RGB</acronym> values.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XStoreColor</function>

-function changes the colormap entry of the pixel value specified in the

-pixel member of the

-<structname>XColor</structname>

-structure.

-You specified this value in the

-pixel member of the

-<structname>XColor</structname>

-structure.

-This pixel value must be a read/write cell and a valid index into the colormap.

-If a specified pixel is not a valid index into the colormap,

-a

-<errorname>BadValue</errorname>

-error results.

-<function>XStoreColor</function>

-also changes the red, green, and/or blue color components.

-You specify which color components are to be changed by setting

-<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and/or

-<symbol>DoBlue</symbol>

-in the flags member of the

-<structname>XColor</structname>

-structure.

-If the colormap is an installed map for its screen, 

-the changes are visible immediately.

-</para>

-<para>

-<!-- .LP -->

-<function>XStoreColor</function>

-can generate

-<errorname>BadAccess</errorname>,

-<errorname>BadColor</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To store multiple <acronym>RGB</acronym> values in multiple colormap cells, use

-<function>XStoreColors</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XStoreColors</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XStoreColors</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XColor<parameter> color[]</parameter></paramdef>

-  <paramdef>int<parameter> ncolors</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of color definition structures to be stored.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .\"Specifies the number of color definition structures.  -->

-Specifies the number of 

-<structname>XColor</structname>

-structures in the color definition array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XStoreColors</function>

-function changes the colormap entries of the pixel values

-specified in the pixel members of the

-<structname>XColor</structname>

-structures.

-You specify which color components are to be changed by setting 

-<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and/or

-<symbol>DoBlue</symbol>

-in the flags member of the

-<structname>XColor</structname>

-structures.

-If the colormap is an installed map for its screen, the

-changes are visible immediately.

-<function>XStoreColors</function>

-changes the specified pixels if they are allocated writable in the colormap 

-by any client, even if one or more pixels generates an error.

-If a specified pixel is not a valid index into the colormap, a

-<errorname>BadValue</errorname>

-error results.

-If a specified pixel either is unallocated or is allocated read-only, a

-<errorname>BadAccess</errorname>

-error results.

-If more than one pixel is in error, 

-the one that gets reported is arbitrary.

-</para>

-<para>

-<!-- .LP -->

-<function>XStoreColors</function>

-can generate

-<errorname>BadAccess</errorname>,

-<errorname>BadColor</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To store a color of arbitrary format in a single colormap cell, use

-<function>XcmsStoreColor</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsStoreColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsStoreColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color cell and the color to store.

-Values specified in this

-<structname>XcmsColor</structname>

-structure remain unchanged on return.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsStoreColor</function>

-function converts the color specified in the

-<structname>XcmsColor</structname>

-structure into <acronym>RGB</acronym> values.

-It then uses this <acronym>RGB</acronym> specification in an

-<structname>XColor</structname>

-structure, whose three flags 

-(<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and

-<symbol>DoBlue</symbol>)

-are set, in a call to

-<function>XStoreColor</function>

-to change the color cell specified by the pixel member of the

-<structname>XcmsColor</structname>

-structure.

-This pixel value must be a valid index for the specified colormap,

-and the color cell specified by the pixel value must be a read/write cell.

-If the pixel value is not a valid index, a

-<errorname>BadValue</errorname>

-error results.

-If the color cell is unallocated or is allocated read-only, a

-<errorname>BadAccess</errorname>

-error results.

-If the colormap is an installed map for its screen, 

-the changes are visible immediately.

-</para>

-<para>

-<!-- .LP -->

-Note that 

-<function>XStoreColor</function>

-has no return value; therefore, an

-<symbol>XcmsSuccess</symbol>

-return value from this function indicates that the conversion 

-to <acronym>RGB</acronym> succeeded and the call to

-<function>XStoreColor</function>

-was made.

-To obtain the actual color stored, use

-<function>XcmsQueryColor</function>.

-Because of the screen's hardware limitations or gamut compression,

-the color stored in the colormap may not be identical

-to the color specified.

-</para>

-<para>

-<!-- .LP -->

-<function>XcmsStoreColor</function>

-can generate

-<errorname>BadAccess</errorname>,

-<errorname>BadColor</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To store multiple colors of arbitrary format in multiple colormap cells, use

-<function>XcmsStoreColors</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsStoreColors</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsStoreColors</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> colors[]</parameter></paramdef>

-  <paramdef>int<parameter> ncolors</parameter></paramdef>

-  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color specification array of

-<structname>XcmsColor</structname>

-structures, each specifying a color cell and the color to store in that

-cell.

-Values specified in the array remain unchanged upon return.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of 

-<structname>XcmsColor</structname>

-structures in the color-specification array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>compression_flags_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of Boolean values indicating compression status.

-If a non-NULL pointer is supplied,

-each element of the array is set to

-<symbol>True</symbol>

-if the corresponding color was compressed and

-<symbol>False</symbol>

-otherwise.

-Pass NULL if the compression status is not useful.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsStoreColors</function>

-function converts the colors specified in the array of

-<structname>XcmsColor</structname>

-structures into <acronym>RGB</acronym> values and then uses these <acronym>RGB</acronym> specifications in

-<structname>XColor</structname>

-structures, whose three flags 

-(<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and

-<symbol>DoBlue</symbol>)

-are set, in a call to

-<function>XStoreColors</function>

-to change the color cells specified by the pixel member of the corresponding

-<structname>XcmsColor</structname>

-structure.

-Each pixel value must be a valid index for the specified colormap,

-and the color cell specified by each pixel value must be a read/write cell.

-If a pixel value is not a valid index, a

-<errorname>BadValue</errorname>

-error results.

-If a color cell is unallocated or is allocated read-only, a

-<errorname>BadAccess</errorname>

-error results.

-If more than one pixel is in error,

-the one that gets reported is arbitrary.

-If the colormap is an installed map for its screen, 

-the changes are visible immediately.

-</para>

-<para>

-<!-- .LP -->

-Note that 

-<function>XStoreColors</function>

-has no return value; therefore, an

-<symbol>XcmsSuccess</symbol>

-return value from this function indicates that conversions 

-to <acronym>RGB</acronym> succeeded and the call to

-<function>XStoreColors</function>

-was made.

-To obtain the actual colors stored, use

-<function>XcmsQueryColors</function>.

-Because of the screen's hardware limitations or gamut compression,

-the colors stored in the colormap may not be identical

-to the colors specified.

-</para>

-<para>

-<!-- .LP -->

-<function>XcmsStoreColors</function>

-can generate

-<errorname>BadAccess</errorname>,

-<errorname>BadColor</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To store a color specified by name in a single colormap cell, use

-<function>XStoreNamedColor</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>

-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>

-<indexterm significance="preferred"><primary>XStoreNamedColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XStoreNamedColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>char<parameter> *color</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> pixel</parameter></paramdef>

-  <paramdef>int<parameter> flags</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color name string (for example, red). 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pixel</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the entry in the colormap. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>flags</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which red, green, and blue components are set.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XStoreNamedColor</function>

-function looks up the named color with respect to the screen associated with

-the colormap and stores the result in the specified colormap.

-The pixel argument determines the entry in the colormap.

-The flags argument determines which of the red, green, and blue components 

-are set. 

-You can set this member to the

-bitwise inclusive OR of the bits 

-<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and 

-<symbol>DoBlue</symbol>.

-If the color name is not in the Host Portable Character Encoding, 

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-If the specified pixel is not a valid index into the colormap, a

-<errorname>BadValue</errorname>

-error results.

-If the specified pixel either is unallocated or is allocated read-only, a

-<errorname>BadAccess</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XStoreNamedColor</function>

-can generate

-<errorname>BadAccess</errorname>,

-<errorname>BadColor</errorname>,

-<errorname>BadName</errorname>,

-and 

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-The

-<function>XQueryColor</function>

-and

-<function>XQueryColors</function>

-functions take pixel values in the pixel member of

-<structname>XColor</structname>

-structures and store in the structures the <acronym>RGB</acronym> values for those

-pixels from the specified colormap.

-The values returned for an unallocated entry are undefined.

-These functions also set the flags member in the

-<structname>XColor</structname>

-structure to all three colors.

-If a pixel is not a valid index into the specified colormap, a

-<errorname>BadValue</errorname>

-error results.

-If more than one pixel is in error,

-the one that gets reported is arbitrary.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To query the <acronym>RGB</acronym> value of a single colormap cell, use

-<function>XQueryColor</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>

-<indexterm significance="preferred"><primary>XQueryColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XQueryColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XColor<parameter> *def_in_out</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>def_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies and returns the <acronym>RGB</acronym> values for the pixel specified in the structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryColor</function>

-function returns the current <acronym>RGB</acronym> value for the pixel in the

-<structname>XColor</structname>

-structure and sets the

-<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and

-<symbol>DoBlue</symbol>

-flags.

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryColor</function>

-can generate

-<errorname>BadColor</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To query the <acronym>RGB</acronym> values of multiple colormap cells, use

-<function>XQueryColors</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>

-<indexterm significance="preferred"><primary>XQueryColors</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XQueryColors</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XColor<parameter> defs_in_out[]</parameter></paramdef>

-  <paramdef>int<parameter> ncolors</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>defs_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies and returns an array of color definition structures for the pixel

-specified in the structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .\"Specifies the number of color definition structures.  -->

-Specifies the number of 

-<structname>XColor</structname>

-structures in the color definition array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryColors</function>

-function returns the <acronym>RGB</acronym> value for each pixel in each

-<structname>XColor</structname>

-structure and sets the

-<symbol>DoRed</symbol>,

-<symbol>DoGreen</symbol>,

-and

-<symbol>DoBlue</symbol>

-flags in each structure.

-

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryColors</function>

-can generate

-<errorname>BadColor</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To query the color of a single colormap cell in an arbitrary format, use

-<function>XcmsQueryColor</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsQueryColor</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsQueryColor</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_in_out</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the pixel member that indicates the color cell to query.

-The color specification stored for the color cell is returned in this

-<structname>XcmsColor</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>result_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color format for the returned color specification.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsQueryColor</function>

-function obtains the <acronym>RGB</acronym> value

-for the pixel value in the pixel member of the specified

-<structname>XcmsColor</structname>

-structure and then

-converts the value to the target format as

-specified by the result_format argument.

-If the pixel is not a valid index in the specified colormap, a

-<errorname>BadValue</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XcmsQueryColor</function>

-can generate

-<errorname>BadColor</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To query the color of multiple colormap cells in an arbitrary format, use

-<function>XcmsQueryColors</function>.

-</para>

-<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsQueryColors</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsQueryColors</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>

-  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colors_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of

-<structname>XcmsColor</structname>

-structures, each pixel member indicating the color cell to query.

-The color specifications for the color cells are returned in these structures.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of 

-<structname>XcmsColor</structname>

-structures in the color-specification array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>result_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color format for the returned color specification.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsQueryColors</function>

-function obtains the <acronym>RGB</acronym> values

-for pixel values in the pixel members of

-<structname>XcmsColor</structname>

-structures and then

-converts the values to the target format as

-specified by the result_format argument.

-If a pixel is not a valid index into the specified colormap, a

-<errorname>BadValue</errorname>

-error results.

-If more than one pixel is in error,

-the one that gets reported is arbitrary.

-</para>

-<para>

-<!-- .LP -->

-<function>XcmsQueryColors</function>

-can generate

-<errorname>BadColor</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Color_Conversion_Context_Functions">

-<title>Color Conversion Context Functions</title>

-<!-- .XS -->

-<!-- (SN Color Conversion Context Functions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section describes functions to create, modify,

-and query Color Conversion Contexts (CCCs).

-</para>

-<para>

-<!-- .LP -->

-Associated with each colormap is an initial CCC transparently generated by

-Xlib.

-<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>

-Therefore, when you specify a colormap as an argument to a function,

-you are indirectly specifying a CCC.

-<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>

-The CCC attributes that can be modified by the X client are:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Client White Point

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Gamut compression procedure and client data

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-White point adjustment procedure and client data

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The initial values for these attributes are implementation specific.

-The CCC attributes for subsequently created CCCs can be defined

-by changing the CCC attributes of the default CCC.

-<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>

-There is a default CCC associated with each screen.

-</para>

-<sect2 id="Getting_and_Setting_the_Color_Conversion_Context_of_a_Colormap">

-<title>Getting and Setting the Color Conversion Context of a Colormap</title>

-<!-- .XS -->

-<!-- (SN Getting and Setting the Color Conversion Context of a Colormap -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the CCC associated with a colormap, use

-<function>XcmsCCCOfColormap</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsCCCOfColormap</primary></indexterm>

-<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>

-<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsCCC <function>XcmsCCCOfColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsCCCOfColormap</function>

-function returns the CCC associated with the specified colormap.

-Once obtained, 

-the CCC attributes can be queried or modified.

-Unless the CCC associated with the specified colormap is changed with

-<function>XcmsSetCCCOfColormap</function>,

-this CCC is used when the specified colormap is used as an argument 

-to color functions.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To change the CCC associated with a colormap, use

-<function>XcmsSetCCCOfColormap</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsSetCCCOfColormap</primary></indexterm>

-<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>

-<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsCCC <function>XcmsSetCCCOfColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsSetCCCOfColormap</function>

-function changes the CCC associated with the specified colormap.

-It returns the CCC previously associated with the colormap.

-If they are not used again in the application,

-CCCs should be freed by calling

-<function>XcmsFreeCCC</function>.

-Several colormaps may share the same CCC without restriction; this

-includes the CCCs generated by Xlib with each colormap.  Xlib, however,

-creates a new CCC with each new colormap.

-</para>

-</sect2>

-<sect2 id="Obtaining_the_Default_Color_Conversion_Context">

-<title>Obtaining the Default Color Conversion Context</title>

-<!-- .XS -->

-<!-- (SN Obtaining the Default Color Conversion Context -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-You can change the default CCC attributes for subsequently created CCCs

-by changing the CCC attributes of the default CCC.

-<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>

-A default CCC is associated with each screen.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the default CCC for a screen, use

-<function>XcmsDefaultCCC</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsDefaultCCC</primary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>

-<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsCCC <function>XcmsDefaultCCC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> screen_number</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the appropriate screen number on the host server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsDefaultCCC</function>

-function returns the default CCC for the specified screen.

-Its visual is the default visual of the screen.

-Its initial gamut compression and white point

-adjustment procedures as well as the associated client data are implementation

-specific.

-</para>

-</sect2>

-<sect2 id="Color_Conversion_Context_Macros">

-<title>Color Conversion Context Macros</title>

-<!-- .XS -->

-<!-- (SN Color Conversion Context Macros -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Applications should not directly modify any part of the

-<structname>XcmsCCC</structname>.

-The following lists the C language macros, their corresponding function

-equivalents for other language bindings, and what data they both

-can return.

-<!-- .sp -->

-</para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>DisplayOfCCC</primary></indexterm>

-<indexterm significance="preferred"><primary>XcmsDisplayOfCCC</primary></indexterm>

-<!-- .sM -->

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>DisplayOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Display *<function>XcmsDisplayOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Both return the display associated with the specified CCC.

-</para>

-<!-- .LP -->

-<!-- .sp -->

-<indexterm significance="preferred"><primary>VisualOfCCC</primary></indexterm>

-<indexterm significance="preferred"><primary>XcmsVisualOfCCC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>VisualOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Visual *<function>XcmsVisualOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Both return the visual associated with the specified CCC.

-<!-- .sp -->

-</para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>ScreenNumberOfCCC</primary></indexterm>

-<indexterm significance="preferred"><primary>XcmsScreenNumberOfCCC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>ScreenNumberOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XcmsScreenNumberOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Both return the number of the screen associated with the specified CCC.

-<!-- .sp -->

-</para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>ScreenWhitePointOfCCC</primary></indexterm>

-<indexterm significance="preferred"><primary>XcmsScreenWhitePointOfCCC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>ScreenWhitePointOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsColor <function>XcmsScreenWhitePointOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Both return the white point of the screen associated with the specified CCC.

-<!-- .sp -->

-</para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>ClientWhitePointOfCCC</primary></indexterm>

-<indexterm significance="preferred"><primary>XcmsClientWhitePointOfCCC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef> <function>ClientWhitePointOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsColor *<function>XcmsClientWhitePointOfCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Both return the Client White Point of the specified CCC.

-</para>

-</sect2>

-

-<sect2 id="Modifying_Attributes_of_a_Color_Conversion_Context">

-<title>Modifying Attributes of a Color Conversion Context</title>

-<!-- .XS -->

-<!-- (SN Modifying Attributes of a Color Conversion Context -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To set the Client White Point in the CCC, use

-<function>XcmsSetWhitePoint</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsSetWhitePoint</primary></indexterm>

-<indexterm><primary>Client White Point</primary><secondary>of Color Conversion Context</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsSetWhitePoint</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-<!-- .ds Co new Client White Point -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the new Client White Point.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsSetWhitePoint</function>

-function changes the Client White Point in the specified CCC.

-Note that the pixel member is ignored 

-and that the color specification is left unchanged upon return.

-The format for the new white point must be

-<symbol>XcmsCIEXYZFormat</symbol>,

-<symbol>XcmsCIEuvYFormat</symbol>,

-<symbol>XcmsCIExyYFormat</symbol>,

-or

-<symbol>XcmsUndefinedFormat</symbol>.

-If the color argument is NULL, this function sets the format component of the

-Client White Point specification to

-<symbol>XcmsUndefinedFormat</symbol>,

-indicating that the Client White Point is assumed to be the same as the

-Screen White Point.

-</para>

-<para>

-<!-- .LP -->

-This function returns nonzero status

-if the format for the new white point is valid;

-otherwise, it returns zero.

-

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set the gamut compression procedure and corresponding client data

-in a specified CCC, use

-<function>XcmsSetCompressionProc</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsSetCompressionProc</primary></indexterm>

-<indexterm><primary>Gamut compression</primary><secondary>setting in Color Conversion Context</secondary></indexterm>

-<indexterm><primary>Gamut compression</primary><secondary>procedure</secondary></indexterm>

-<indexterm><primary>Gamut compression</primary><secondary>client data</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsCompressionProc <function>XcmsSetCompressionProc</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsCompressionProc<parameter> compression_proc</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>compression_proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the gamut compression procedure that is to be applied 

-when a color lies outside the screen's color gamut.

-If NULL is specified and a function using this CCC must convert

-a color specification to a device-dependent format and encounters a color

-that lies outside the screen's color gamut, 

-that function will return

-<symbol>XcmsFailure</symbol>.

-<!-- .ds Cd the gamut compression procedure -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies client data for gamut compression procedure or NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsSetCompressionProc</function>

-function first sets the gamut compression procedure and client data 

-in the specified CCC with the newly specified procedure and client data

-and then returns the old procedure.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set the white point adjustment procedure and corresponding client data

-in a specified CCC, use

-<function>XcmsSetWhiteAdjustProc</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsSetWhiteAdjustProc</primary></indexterm>

-<indexterm><primary>White point adjustment</primary><secondary>setting in Color Conversion Context</secondary></indexterm>

-<indexterm><primary>White point adjustment</primary><secondary>procedure</secondary></indexterm>

-<indexterm><primary>White point adjustment</primary><secondary>client data</secondary></indexterm>

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsWhiteAdjustProc <function>XcmsSetWhiteAdjustProc</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsWhiteAdjustProc<parameter> white_adjust_proc</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>white_adjust_proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the white point adjustment procedure.

-<!-- .ds Cd the white point adjustment procedure -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies client data for white point adjustment procedure or NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsSetWhiteAdjustProc</function>

-function first sets the white point adjustment procedure and client data 

-in the specified CCC with the newly specified procedure and client data

-and then returns the old procedure.

-</para>

-</sect2>

-<sect2 id="Creating_and_Freeing_a_Color_Conversion_Context">

-<title>Creating and Freeing a Color Conversion Context</title>

-<!-- .XS -->

-<!-- (SN Creating and Freeing a Color Conversion Context -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-You can explicitly create a CCC within your application by calling

-<function>XcmsCreateCCC</function>.

-These created CCCs can then be used by those functions that explicitly

-call for a CCC argument.

-Old CCCs that will not be used by the application should be freed using

-<function>XcmsFreeCCC</function>.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To create a CCC, use

-<function>XcmsCreateCCC</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsCreateCCC</primary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>

-<indexterm><primary>CCC</primary><secondary>creation</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsCCC <function>XcmsCreateCCC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> screen_number</parameter></paramdef>

-  <paramdef>Visual<parameter> *visual</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *client_white_point</parameter></paramdef>

-  <paramdef>XcmsCompressionProc<parameter> compression_proc</parameter></paramdef>

-  <paramdef>XPointer<parameter> compression_client_data</parameter></paramdef>

-  <paramdef>XcmsWhiteAdjustProc<parameter> white_adjust_proc</parameter></paramdef>

-  <paramdef>XPointer<parameter> white_adjust_client_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the appropriate screen number on the host server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>visual</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the visual type.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_white_point</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the Client White Point.

-If NULL is specified, 

-the Client White Point is to be assumed to be the same as the

-Screen White Point.

-Note that the pixel member is ignored.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>compression_proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the gamut compression procedure that is to be applied 

-when a color lies outside the screen's color gamut.

-If NULL is specified and a function using this CCC must convert

-a color specification to a device-dependent format and encounters a color

-that lies outside the screen's color gamut, 

-that function will return

-<symbol>XcmsFailure</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>compression_client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies client data for use by the gamut compression procedure or NULL.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>white_adjust_proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the white adjustment procedure that is to be applied

-when the Client White Point differs from the Screen White Point.

-NULL indicates that no white point adjustment is desired.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>white_adjust_client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies client data for use with the white point adjustment procedure or NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsCreateCCC</function>

-function creates a CCC for the specified display, screen, and visual.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To free a CCC, use

-<function>XcmsFreeCCC</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsFreeCCC</primary></indexterm>

-<indexterm><primary>Color Conversion Context</primary><secondary>freeing</secondary></indexterm>

-<indexterm><primary>CCC</primary><secondary>freeing</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XcmsFreeCCC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsFreeCCC</function>

-function frees the memory used for the specified CCC.

-Note that default CCCs and those currently associated with colormaps

-are ignored.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Converting_between_Color_Spaces">

-<title>Converting between Color Spaces</title>

-<!-- .XS -->

-<!-- (SN Converting between Color Spaces -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To convert an array of color specifications in arbitrary color formats

-to a single destination format, use

-<function>XcmsConvertColors</function>.

-</para>

-<indexterm><primary>Color conversion</primary></indexterm>

-<indexterm><primary>Color</primary><secondary>conversion</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsConvertColors</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsConvertColors</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>

-  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

-  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-If conversion is between device-independent color spaces only

-(for example, TekHVC to CIELuv),

-the CCC is necessary only to specify the Client White Point.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colors_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of color specifications.

-Pixel members are ignored and remain unchanged upon return.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of 

-<structname>XcmsColor</structname>

-structures in the color-specification array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target color specification format.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>compression_flags_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of Boolean values indicating compression status.

-If a non-NULL pointer is supplied,

-each element of the array is set to

-<symbol>True</symbol>

-if the corresponding color was compressed and

-<symbol>False</symbol>

-otherwise.

-Pass NULL if the compression status is not useful.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsConvertColors</function>

-function converts the color specifications in the specified array of

-<structname>XcmsColor</structname>

-structures from their current format to a single target format,

-using the specified CCC.

-When the return value is

-<symbol>XcmsFailure</symbol>,

-the contents of the color specification array are left unchanged.

-</para>

-<para>

-<!-- .LP -->

-The array may contain a mixture of color specification formats

-(for example, 3 <acronym>CIE</acronym> XYZ, 2 <acronym>CIE</acronym> Luv, and so on).

-When the array contains both device-independent and

-device-dependent color specifications and the target_format argument specifies

-a device-dependent format (for example,

-<symbol>XcmsRGBiFormat</symbol>,

-<symbol>XcmsRGBFormat</symbol>),

-all specifications are converted to <acronym>CIE</acronym> XYZ format and then to the target

-device-dependent format.

-</para>

-</sect1>

-<sect1 id="Callback_Functions">

-<title>Callback Functions</title>

-<!-- .XS -->

-<!-- (SN Callback Functions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section describes the gamut compression and white point

-adjustment callbacks.

-</para>

-<para>

-<!-- .LP -->

-The gamut compression procedure specified in the CCC

-is called when an attempt to convert a color specification from

-<structname>XcmsCIEXYZ</structname>

-to a device-dependent format (typically

-<structname>XcmsRGBi</structname>)

-results in a color that lies outside the screen's color gamut.

-If the gamut compression procedure requires client data, this data is passed

-via the gamut compression client data in the CCC.

-</para>

-<para>

-<!-- .LP -->

-During color specification conversion between device-independent

-and device-dependent color spaces,

-if a white point adjustment procedure is specified in the CCC,

-it is triggered when the Client White Point and Screen White Point differ.

-If required, the client data is obtained from the CCC.

-</para>

-<sect2 id="Prototype_Gamut_Compression_Procedure">

-<title>Prototype Gamut Compression Procedure</title>

-<!-- .XS -->

-<!-- (SN Prototype Gamut Compression Procedure -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The gamut compression callback interface must adhere to the

-following:

-</para>

-<indexterm significance="preferred"><primary>XcmsCompressionProc</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>typedef Status<function>(*XcmsCompressionProc</function>)</funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>

-  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

-  <paramdef>unsignedint<parameter> index</parameter></paramdef>

-  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colors_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of color specifications.

-Pixel members should be ignored and must remain unchanged upon return.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of 

-<structname>XcmsColor</structname>

-structures in the color-specification array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>index</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the index into the array of

-<structname>XcmsColor</structname>

-structures for the encountered color specification that lies outside the 

-screen's color gamut.

-Valid values are 0 (for the first element) to ncolors - 1.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>compression_flags_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of Boolean values for indicating compression status.

-If a non-NULL pointer is supplied

-and a color at a given index is compressed, then

-<symbol>True</symbol>

-should be stored at the corresponding index in this array;

-otherwise, the array should not be modified.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-When implementing a gamut compression procedure, consider the following

-rules and assumptions:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The gamut compression procedure can attempt to compress one or multiple

-specifications at a time.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-When called, elements 0 to index - 1 in the color specification

-array can be assumed to fall within the screen's color gamut.

-In addition, these color specifications are already in some device-dependent

-format (typically

-<structname>XcmsRGBi</structname>).

-If any modifications are made to these color specifications,

-they must be in their initial device-dependent format upon return.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-When called, the element in the color specification array specified

-by the index argument contains the color specification outside the 

-screen's color gamut encountered by the calling routine.

-In addition, this color specification can be assumed to be in

-<structname>XcmsCIEXYZ</structname>.

-Upon return, this color specification must be in

-<structname>XcmsCIEXYZ</structname>.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-When called, elements from index to ncolors - 1 

-in the color specification array may or may not fall within the

-screen's color gamut.

-In addition, these color specifications can be assumed to be in

-<structname>XcmsCIEXYZ</structname>.

-If any modifications are made to these color specifications, 

-they must be in

-<structname>XcmsCIEXYZ</structname>

-upon return.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The color specifications passed to the gamut compression procedure

-have already been adjusted to the Screen White Point.

-This means that at this point the color specification's white point

-is the Screen White Point.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the gamut compression procedure uses a device-independent color space not

-initially accessible for use in the color management system, use 

-<function>XcmsAddColorSpace</function>

-to ensure that it is added.

-    </para>

-  </listitem>

-</itemizedlist>

-</sect2>

-<sect2 id="Supplied_Gamut_Compression_Procedures">

-<title>Supplied Gamut Compression Procedures</title>

-<!-- .XS -->

-<!-- (SN Supplied Gamut Compression Procedures -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The following equations are useful in describing gamut compression

-functions:

-<!-- .EQ -->

-delim %%

-<!-- .EN -->

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%

-

-%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%

-

-%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%

-

-%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The gamut compression callback procedures provided by Xlib are as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-<function>XcmsCIELabClipL</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the 

-screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*) 

-in the <acronym>CIE</acronym> L*a*b* color space until the color is within the gamut.

-If the Psychometric Chroma of the color specification 

-is beyond maximum for the Psychometric Hue Angle,

-then while maintaining the same Psychometric Hue Angle,

-the color will be clipped to the <acronym>CIE</acronym> L*a*b* coordinates of maximum

-Psychometric Chroma.

-See

-<function>XcmsCIELabQueryMaxC</function>.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsCIELabClipab</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the 

-screen's color gamut by reducing Psychometric Chroma,

-while maintaining Psychometric Hue Angle,

-until the color is within the gamut.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsCIELabClipLab</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the

-screen's color gamut by replacing it with <acronym>CIE</acronym> L*a*b* coordinates

-that fall within the color gamut while maintaining the original

-Psychometric Hue

-Angle and whose vector to the original coordinates is the shortest attainable.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsCIELuvClipL</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the 

-screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*)

-in the <acronym>CIE</acronym> L*u*v* color space until the color is within the gamut.

-If the Psychometric Chroma of the color specification

-is beyond maximum for the Psychometric Hue Angle,

-then, while maintaining the same Psychometric Hue Angle,

-the color will be clipped to the <acronym>CIE</acronym> L*u*v* coordinates of maximum

-Psychometric Chroma.

-See

-<function>XcmsCIELuvQueryMaxC</function>.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsCIELuvClipuv</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the

-screen's color gamut by reducing

-Psychometric Chroma, while maintaining Psychometric Hue Angle,

-until the color is within the gamut.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsCIELuvClipLuv</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the

-screen's color gamut by replacing it with <acronym>CIE</acronym> L*u*v* coordinates

-that fall within the color gamut while maintaining the original

-Psychometric Hue

-Angle and whose vector to the original coordinates is the shortest attainable.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsTekHVCClipV</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the

-screen's color gamut by reducing or increasing the Value dimension

-in the TekHVC color space until the color is within the gamut.

-If Chroma of the color specification is beyond maximum for the particular Hue,

-then, while maintaining the same Hue,

-the color will be clipped to the Value and Chroma coordinates

-that represent maximum Chroma for that particular Hue.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsTekHVCClipC</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the

-screen's color gamut by reducing the Chroma dimension

-in the TekHVC color space until the color is within the gamut.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsTekHVCClipVC</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This brings the encountered out-of-gamut color specification into the

-screen's color gamut by replacing it with TekHVC coordinates

-that fall within the color gamut while maintaining the original Hue

-and whose vector to the original coordinates is the shortest attainable.

-No client data is necessary.

-    </para>

-  </listitem>

-</itemizedlist>

-</sect2>

-<sect2 id="Prototype_White_Point_Adjustment_Procedure">

-<title>Prototype White Point Adjustment Procedure</title>

-<!-- .XS -->

-<!-- (SN Prototype White Point Adjustment Procedure -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The white point adjustment procedure interface must adhere to the following:

-</para>

-<indexterm significance="preferred"><primary>XcmsWhiteAdjustProc</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>typedef Status <function>(*XcmsWhiteAdjustProc</function>)</funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *initial_white_point</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *target_white_point</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>

-  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

-  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>initial_white_point</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the initial white point.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_white_point</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target white point.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target color specification format.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colors_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of color specifications.

-Pixel members should be ignored and must remain unchanged upon return.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of 

-<structname>XcmsColor</structname>

-structures in the color-specification array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>compression_flags_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of Boolean values for indicating compression status.

-If a non-NULL pointer is supplied

-and a color at a given index is compressed, then

-<symbol>True</symbol>

-should be stored at the corresponding index in this array;

-otherwise, the array should not be modified.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-</sect2>

-<sect2 id="Supplied_White_Point_Adjustment_Procedures">

-<title>Supplied White Point Adjustment Procedures</title>

-<!-- .XS -->

-<!-- (SN Supplied White Point Adjustment Procedures -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-White point adjustment procedures provided by Xlib are as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-<function>XcmsCIELabWhiteShiftColors</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This uses the <acronym>CIE</acronym> L*a*b* color space for adjusting the chromatic character

-of colors to compensate for the chromatic differences between the source

-and destination white points.

-This procedure simply converts the color specifications to 

-<structname>XcmsCIELab</structname>

-using the source white point and then converts to the target specification

-format using the destination's white point.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsCIELuvWhiteShiftColors</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This uses the <acronym>CIE</acronym> L*u*v* color space for adjusting the chromatic character

-of colors to compensate for the chromatic differences between the source

-and destination white points.

-This procedure simply converts the color specifications to 

-<structname>XcmsCIELuv</structname>

-using the source white point and then converts to the target specification

-format using the destination's white point.

-No client data is necessary.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>XcmsTekHVCWhiteShiftColors</function>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-This uses the TekHVC color space for adjusting the chromatic character

-of colors to compensate for the chromatic differences between the source

-and destination white points.

-This procedure simply converts the color specifications to

-<structname>XcmsTekHVC</structname>

-using the source white point and then converts to the target specification

-format using the destination's white point.

-An advantage of this procedure over those previously described

-is an attempt to minimize hue shift.

-No client data is necessary.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-From an implementation point of view,

-these white point adjustment procedures convert the color specifications

-to a device-independent but white-point-dependent color space 

-(for example, <acronym>CIE</acronym> L*u*v*, <acronym>CIE</acronym> L*a*b*, TekHVC) using one white point

-and then converting those specifications to the target color space 

-using another white point.

-In other words,

-the specification goes in the color space with one white point 

-but comes out with another white point, 

-resulting in a chromatic shift based on the chromatic displacement

-between the initial white point and target white point.

-The <acronym>CIE</acronym> color spaces that are assumed to be white-point-independent

-are <acronym>CIE</acronym> u'v'Y, <acronym>CIE</acronym> XYZ, and <acronym>CIE</acronym> xyY.

-When developing a custom white point adjustment procedure that uses a

-device-independent color space not initially accessible for use in the

-color management system, use

-<function>XcmsAddColorSpace</function>

-to ensure that it is added.

-</para>

-<para>

-<!-- .LP -->

-As an example, 

-if the CCC specifies a white point adjustment procedure

-and if the Client White Point and Screen White Point differ, the

-<function>XcmsAllocColor</function>

-function will use the white point adjustment

-procedure twice: 

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Once to convert to

-<structname>XcmsRGB</structname>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A second time to convert from

-<structname>XcmsRGB</structname>

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-For example, assume the specification is in

-<structname>XcmsCIEuvY</structname>

-and the adjustment procedure is

-<function>XcmsCIELuvWhiteShiftColors</function>.

-During conversion to

-<structname>XcmsRGB</structname>,

-the call to 

-<function>XcmsAllocColor</function>

-results in the following series of color specification conversions:

-<!-- .\" Do these need to be font coded? -->

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-From 

-<structname>XcmsCIEuvY</structname>

-to

-<structname>XcmsCIELuv</structname>

-using the Client White Point

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-From 

-<structname>XcmsCIELuv</structname>

-to

-<structname>XcmsCIEuvY</structname>

-using the Screen White Point

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-From

-<structname>XcmsCIEuvY</structname>

-to

-<structname>XcmsCIEXYZ</structname>

-(<acronym>CIE</acronym> u'v'Y and XYZ are white-point-independent color spaces)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-From 

-<structname>XcmsCIEXYZ</structname>

-to 

-<structname>XcmsRGBi</structname>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-From 

-<structname>XcmsRGBi</structname>

-to

-<structname>XcmsRGB</structname>

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The resulting <acronym>RGB</acronym> specification is passed to

-<function>XAllocColor</function>,

-and the <acronym>RGB</acronym>

-specification returned by

-<function>XAllocColor</function>

-is converted back to 

-<structname>XcmsCIEuvY</structname>

-by reversing the color conversion sequence.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Gamut_Querying_Functions">

-<title>Gamut Querying Functions</title>

-<!-- .XS -->

-<!-- (SN Gamut Querying Functions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section describes the gamut querying functions that Xlib provides.

-These functions allow the client to query the boundary 

-of the screen's color gamut in terms of the <acronym>CIE</acronym> L*a*b*, <acronym>CIE</acronym> L*u*v*, 

-and TekHVC color spaces.

-<indexterm><primary>Gamut querying</primary></indexterm>

-Functions are also provided that allow you to query 

-the color specification of:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-White (full-intensity red, green, and blue)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Red (full-intensity red while green and blue are zero)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Green (full-intensity green while red and blue are zero)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Blue (full-intensity blue while red and green are zero)

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Black (zero-intensity red, green, and blue)

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The white point associated with color specifications passed to 

-and returned from these gamut querying

-functions is assumed to be the Screen White Point.

-<indexterm><primary>Screen White Point</primary></indexterm>

-This is a reasonable assumption,

-because the client is trying to query the screen's color gamut.

-</para>

-<para>

-<!-- .LP -->

-The following naming convention is used for the Max and Min functions:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-Xcms<emphasis remap='I'>&lt;color_space&gt;</emphasis>QueryMax<emphasis remap='I'>&lt;dimensions&gt;</emphasis>

-

-Xcms<emphasis remap='I'>&lt;color_space&gt;</emphasis>QueryMin<emphasis remap='I'>&lt;dimensions&gt;</emphasis>

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The &lt;dimensions&gt; consists of a letter or letters 

-that identify the dimensions of the color space 

-that are not fixed.

-For example, 

-<function>XcmsTekHVCQueryMaxC</function>

-is given a fixed Hue and Value for which maximum Chroma is found.

-</para>

-<sect2 id="Red_Green_and_Blue_Queries">

-<title>Red, Green, and Blue Queries</title>

-<!-- .XS -->

-<!-- (SN Red, Green, and Blue Queries -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To obtain the color specification for black 

-(zero-intensity red, green, and blue), use

-<function>XcmsQueryBlack</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsQueryBlack</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsQueryBlack</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target color specification format.

-<!-- .ds Cs zero-intensity red, green, and blue -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color specification in the specified target format

-for (Cs.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsQueryBlack</function>

-function returns the color specification in the specified target format

-for zero-intensity red, green, and blue.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the color specification for blue 

-(full-intensity blue while red and green are zero), use

-<function>XcmsQueryBlue</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsQueryBlue</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsQueryBlue</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target color specification format.

-<!-- .ds Cs full-intensity blue while red and green are zero -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color specification in the specified target format

-for (Cs.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsQueryBlue</function>

-function returns the color specification in the specified target format

-for full-intensity blue while red and green are zero.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the color specification for green

-(full-intensity green while red and blue are zero), use

-<function>XcmsQueryGreen</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsQueryGreen</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsQueryGreen</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target color specification format.

-<!-- .ds Cs full-intensity green while red and blue are zero -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color specification in the specified target format

-for (Cs.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsQueryGreen</function>

-function returns the color specification in the specified target format

-for full-intensity green while red and blue are zero.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the color specification for red

-(full-intensity red while green and blue are zero), use

-<function>XcmsQueryRed</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsQueryRed</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsQueryRed</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target color specification format.

-<!-- .ds Cs full-intensity red while green and blue are zero -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color specification in the specified target format

-for (Cs.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsQueryRed</function>

-function returns the color specification in the specified target format

-for full-intensity red while green and blue are zero.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the color specification for white

-(full-intensity red, green, and blue), use

-<function>XcmsQueryWhite</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsQueryWhite</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsQueryWhite</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target color specification format.

-<!-- .ds Cs full-intensity red, green, and blue -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color specification in the specified target format

-for (Cs.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsQueryWhite</function>

-function returns the color specification in the specified target format

-for full-intensity red, green, and blue.

-</para>

-</sect2>

-<sect2 id="CIELab_Queries">

-<title>CIELab Queries</title>

-<!-- .XS -->

-<!-- (SN CIELab Queries -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The following equations are useful in describing the CIELab query functions:

-<!-- .EQ -->

-delim %%

-<!-- .EN -->

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

-<indexterm><primary>Psychometric Chroma</primary></indexterm>

-<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>

-<literallayout class="monospaced">

-%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%

-

-%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%

-</literallayout>

-<!-- .sp -->

-To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma

-for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use

-<function>XcmsCIELabQueryMaxC</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsCIELabQueryMaxC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> L_star</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Ha maximum chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue_angle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the hue angle (in degrees) at which to find (Ha.

-<!-- .ds Ls maximum chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>L_star</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the lightness (L*) at which to find (Ls.

-<!-- .ds Lc maximum chroma -->

-<!-- .ds lC hue angle and lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc

-displayable by the screen for the given (lC.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsCIELabQueryMaxC</function>

-function, given a hue angle and lightness,

-finds the point of maximum chroma displayable by the screen.

-It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)

-for a given Psychometric Hue Angle and Psychometric Chroma, use

-<function>XcmsCIELabQueryMaxL</function>.

-</para>

-<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxL</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsCIELabQueryMaxL</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Ha maximum lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue_angle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the hue angle (in degrees) at which to find (Ha.

-<!-- .ds Ch maximum lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>chroma</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the chroma at which to find (Ch.

-<!-- .ds Lc maximum lightness -->

-<!-- .ds lC hue angle and chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc

-displayable by the screen for the given (lC.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsCIELabQueryMaxL</function>

-function, given a hue angle and chroma,

-finds the point in <acronym>CIE</acronym> L*a*b* color space of maximum 

-lightness (L*) displayable by the screen.

-It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.

-An 

-<symbol>XcmsFailure</symbol>

-return value usually indicates that the given chroma

-is beyond maximum for the given hue angle.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma

-for a given Psychometric Hue Angle, use

-<function>XcmsCIELabQueryMaxLC</function>.

-</para>

-<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

-<indexterm><primary>Psychometric Chroma</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

-<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxLC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsCIELabQueryMaxLC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Ha maximum chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue_angle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the hue angle (in degrees) at which to find (Ha.

-<!-- .ds Lc maximum chroma -->

-<!-- .ds lC hue angle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc

-displayable by the screen for the given (lC.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsCIELabQueryMaxLC</function>

-function, given a hue angle,

-finds the point of maximum chroma displayable by the screen.

-It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the <acronym>CIE</acronym> L*a*b* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)

-for a given Psychometric Hue Angle and Psychometric Chroma, use

-<function>XcmsCIELabQueryMinL</function>.

-</para>

-<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsCIELabQueryMinL</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsCIELabQueryMinL</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Ha minimum lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue_angle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the hue angle (in degrees) at which to find (Ha.

-<!-- .ds Ch minimum lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>chroma</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the chroma at which to find (Ch.

-<!-- .ds Lc minimum lightness -->

-<!-- .ds lC hue angle and chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc

-displayable by the screen for the given (lC.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsCIELabQueryMinL</function>

-function, given a hue angle and chroma,

-finds the point of minimum lightness (L*) displayable by the screen.

-It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.

-An 

-<symbol>XcmsFailure</symbol>

-return value usually indicates that the given chroma

-is beyond maximum for the given hue angle.

-</para>

-</sect2>

-<sect2 id="CIELuv_Queries">

-<title>CIELuv Queries</title>

-<!-- .XS -->

-<!-- (SN CIELuv Queries -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The following equations are useful in describing the CIELuv query functions:

-<!-- .EQ -->

-delim %%

-<!-- .EN -->

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

-<indexterm><primary>Psychometric Chroma</primary></indexterm>

-<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>

-<literallayout class="monospaced">

-%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%

-

-%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%

-</literallayout>

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma

-for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use

-<function>XcmsCIELuvQueryMaxC</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsCIELuvQueryMaxC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> L_star</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Ha maximum chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue_angle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the hue angle (in degrees) at which to find (Ha.

-<!-- .ds Ls maximum chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>L_star</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the lightness (L*) at which to find (Ls.

-<!-- .ds Lc maximum chroma -->

-<!-- .ds lC hue angle and lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc

-displayable by the screen for the given (lC.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsCIELuvQueryMaxC</function>

-function, given a hue angle and lightness,

-finds the point of maximum chroma displayable by the screen.

-It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)

-for a given Psychometric Hue Angle and Psychometric Chroma, use

-<function>XcmsCIELuvQueryMaxL</function>.

-</para>

-<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxL</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsCIELuvQueryMaxL</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Ha maximum lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue_angle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the hue angle (in degrees) at which to find (Ha.

-<!-- .ds Ls maximum lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>L_star</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the lightness (L*) at which to find (Ls.

-<!-- .ds Lc maximum lightness -->

-<!-- .ds lC hue angle and chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc

-displayable by the screen for the given (lC.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsCIELuvQueryMaxL</function>

-function, given a hue angle and chroma,

-finds the point in <acronym>CIE</acronym> L*u*v* color space of maximum 

-lightness (L*) displayable by the screen.

-It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.

-An 

-<symbol>XcmsFailure</symbol>

-return value usually indicates that the given chroma

-is beyond maximum for the given hue angle.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma

-for a given Psychometric Hue Angle, use

-<function>XcmsCIELuvQueryMaxLC</function>.

-</para>

-<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

-<indexterm><primary>Psychometric Chroma</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

-<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxLC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsCIELuvQueryMaxLC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Ha maximum chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue_angle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the hue angle (in degrees) at which to find (Ha.

-<!-- .ds Lc maximum chroma -->

-<!-- .ds lC hue angle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc

-displayable by the screen for the given (lC.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsCIELuvQueryMaxLC</function>

-function, given a hue angle,

-finds the point of maximum chroma displayable by the screen.

-It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the <acronym>CIE</acronym> L*u*v* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)

-for a given Psychometric Hue Angle and Psychometric Chroma, use

-<function>XcmsCIELuvQueryMinL</function>.

-</para>

-<indexterm><primary>Psychometric Hue Angle</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>

-<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsCIELuvQueryMinL</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsCIELuvQueryMinL</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Ha minimum lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue_angle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the hue angle (in degrees) at which to find (Ha.

-<!-- .ds Ch minimum lightness -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>chroma</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the chroma at which to find (Ch.

-<!-- .ds Lc minimum lightness -->

-<!-- .ds lC hue angle and chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc

-displayable by the screen for the given (lC.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsCIELuvQueryMinL</function>

-function, given a hue angle and chroma,

-finds the point of minimum lightness (L*) displayable by the screen.

-It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.

-An 

-<symbol>XcmsFailure</symbol>

-return value usually indicates that the given chroma

-is beyond maximum for the given hue angle.

-</para>

-</sect2>

-<sect2 id="TekHVC_Queries">

-<title>TekHVC Queries</title>

-<!-- .XS -->

-<!-- (SN TekHVC Queries -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To obtain the maximum Chroma for a given Hue and Value, use

-<function>XcmsTekHVCQueryMaxC</function>.

-</para>

-<indexterm><primary>Chroma</primary></indexterm>

-<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsTekHVCQueryMaxC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> value</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Hu in which to find the maximum Chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the Hue (Hu.

-<!-- .ds Va maximum Chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the Value in which to find the (Va.

-<!-- .ds Lc maximum Chroma along with the actual Hue and Value  -->

-<!-- .ds lC maximum Chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the (Lc at which the (lC was found.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsTekHVCQueryMaxC</function>

-function, given a Hue and Value,

-determines the maximum Chroma in TekHVC color space

-displayable by the screen.

-It returns the maximum Chroma along with the actual Hue

-and Value at which the maximum Chroma was found.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the maximum Value for a given Hue and Chroma, use

-<function>XcmsTekHVCQueryMaxV</function>.

-</para>

-<indexterm><primary>Value</primary></indexterm>

-<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxV</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsTekHVCQueryMaxV</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Hu in which to find the maximum Value -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the Hue (Hu.

-<!-- .ds Ch maximum Value -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>chroma</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the chroma at which to find (Ch.

-<!-- .ds Lc maximum Value along with the Hue and Chroma -->

-<!-- .ds lC maximum Value -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the (Lc at which the (lC was found.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsTekHVCQueryMaxV</function>

-function, given a Hue and Chroma,

-determines the maximum Value in TekHVC color space

-displayable by the screen.

-It returns the maximum Value and the actual Hue and Chroma

-at which the maximum Value was found.

-<!-- .sp -->

-</para>

-

-<para>

-<!-- .LP -->

-To obtain the maximum Chroma and Value at which it is reached

-for a specified Hue, use

-<function>XcmsTekHVCQueryMaxVC</function>.

-</para>

-<indexterm><primary>Chroma</primary></indexterm>

-<indexterm><primary>Value</primary></indexterm>

-<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>

-<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsTekHVCQueryMaxVC</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Hu in which to find the maximum Chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the Hue (Hu.

-<!-- .ds Lc color specification in \ -->

-XcmsTekHVC for the maximum Chroma, the Value at which \

-that maximum Chroma is reached, and the actual Hue

-<!-- .ds lC maximum Chroma -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the (Lc at which the (lC was found.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsTekHVCQueryMaxVC</function>

-function, given a Hue,

-determines the maximum Chroma in TekHVC color space displayable by the screen

-and the Value at which that maximum Chroma is reached.

-It returns the maximum Chroma,

-the Value at which that maximum Chroma is reached,

-and the actual Hue for which the maximum Chroma was found.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain a specified number of TekHVC specifications such that they

-contain maximum Values for a specified Hue and the

-Chroma at which the maximum Values are reached, use

-<function>XcmsTekHVCQueryMaxVSamples</function>.

-</para>

-<indexterm><primary>Chroma</primary></indexterm>

-<indexterm><primary>Value</primary></indexterm>

-<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>

-<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVSamples</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsTekHVCQueryMaxVSamples</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> colors_return[]</parameter></paramdef>

-  <paramdef>unsignedint<parameter> nsamples</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Hu for maximum Chroma/Value samples -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the Hue (Hu.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nsamples</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of samples.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colors_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns nsamples of color specifications in XcmsTekHVC

-such that the Chroma is the maximum attainable for the Value and Hue.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsTekHVCQueryMaxVSamples</function>

-returns nsamples of maximum Value, the Chroma at which that maximum Value

-is reached, and the actual Hue for which the maximum Chroma was found.

-These sample points may then be used to plot the maximum Value/Chroma

-boundary of the screen's color gamut for the specified Hue in TekHVC color

-space.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the minimum Value for a given Hue and Chroma, use

-<function>XcmsTekHVCQueryMinV</function>.

-</para>

-<indexterm><primary>Value</primary></indexterm>

-<indexterm><primary>Value</primary><secondary>minimum</secondary></indexterm>

-<indexterm significance="preferred"><primary>XcmsTekHVCQueryMinV</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsTekHVCQueryMinV</function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>

-  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-The CCC's Client White Point and white point adjustment procedures

-are ignored.

-<!-- .ds Hu in which to find the minimum Value -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hue</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the Hue (Hu.

-<!-- .ds Va minimum Value -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the Value in which to find the (Va.

-<!-- .ds Lc minimum Value and the actual Hue and Chroma -->

-<!-- .ds lC minimum Value -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the (Lc at which the (lC was found.

-The white point associated with the returned

-color specification is the Screen White Point.

-The value returned in the pixel member is undefined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XcmsTekHVCQueryMinV</function>

-function, given a Hue and Chroma,

-determines the minimum Value in TekHVC color space displayable by the screen.

-It returns the minimum Value and the actual Hue and Chroma at which

-the minimum Value was found.

-</para>

-

-</sect2>

-</sect1>

-<sect1 id="Color_Management_Extensions">

-<title>Color Management Extensions</title>

-<!-- .XS -->

-<!-- (SN Color Management Extensions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The Xlib color management facilities can be extended in two ways:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Device-Independent Color Spaces

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Device-independent color spaces that are derivable to <acronym>CIE</acronym> XYZ

-space can be added using the

-<function>XcmsAddColorSpace</function>

-function.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Color Characterization Function Set

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A Color Characterization Function Set consists of

-device-dependent color spaces and their functions that

-convert between these color spaces and the <acronym>CIE</acronym> XYZ

-color space, bundled together for a specific class of output devices.

-A function set can be added using the

-<function>XcmsAddFunctionSet</function>

-function.

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Color_Spaces">

-<title>Color Spaces</title>

-<!-- .XS -->

-<!-- (SN Color Spaces -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The <acronym>CIE</acronym> XYZ color space serves as the hub for all

-conversions between device-independent and device-dependent color spaces.

-Therefore, the knowledge to convert an 

-<structname>XcmsColor</structname>

-structure to and from <acronym>CIE</acronym> XYZ format is associated with each color space.

-For example, conversion from <acronym>CIE</acronym> L*u*v* to <acronym>RGB</acronym> requires the knowledge

-to convert from <acronym>CIE</acronym> L*u*v* to <acronym>CIE</acronym> XYZ and from <acronym>CIE</acronym> XYZ to <acronym>RGB</acronym>.

-This knowledge is stored as an array of functions that,

-when applied in series, will convert the 

-<structname>XcmsColor</structname>

-structure to or from <acronym>CIE</acronym> XYZ format.

-This color specification conversion mechanism facilitates

-the addition of color spaces.

-</para>

-<para>

-<!-- .LP -->

-Of course, when converting between only device-independent color spaces

-or only device-dependent color spaces,

-shortcuts are taken whenever possible.

-For example, conversion from TekHVC to <acronym>CIE</acronym> L*u*v* is performed 

-by intermediate conversion to <acronym>CIE</acronym> u*v*Y and then to <acronym>CIE</acronym> L*u*v*, 

-thus bypassing conversion between <acronym>CIE</acronym> u*v*Y and <acronym>CIE</acronym> XYZ.

-</para>

-</sect2>

-<sect2 id="Adding_Device_Independent_Color_Spaces">

-<title>Adding Device-Independent Color Spaces</title>

-<!-- .XS -->

-<!-- (SN Adding Device-Independent Color Spaces -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To add a device-independent color space, use

-<function>XcmsAddColorSpace</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsAddColorSpace</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsAddColorSpace</function></funcdef>

-  <paramdef>XcmsColorSpace<parameter> *color_space</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_space</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the device-independent color space to add.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsAddColorSpace</function>

-function makes a device-independent color space (actually an

-<structname>XcmsColorSpace</structname>

-structure) accessible by the color management system.

-Because format values for unregistered color spaces are assigned at run time,

-they should be treated as private to the client.

-If references to an unregistered color space must be made

-outside the client (for example, storing color specifications 

-in a file using the unregistered color space), 

-then reference should be made by color space prefix

-(see

-<function>XcmsFormatOfPrefix</function>

-and

-<function>XcmsPrefixOfFormat</function>).

-</para>

-<para>

-<!-- .LP -->

-If the 

-<structname>XcmsColorSpace</structname>

-structure is already accessible in the color management system, 

-<function>XcmsAddColorSpace</function>

-returns 

-<symbol>XcmsSuccess</symbol>.

-</para>

-<para>

-<!-- .LP -->

-Note that added 

-<structname>XcmsColorSpace</structname>s

-must be retained for reference by Xlib.

-</para>

-</sect2>

-<sect2 id="Querying_Color_Space_Format_and_Prefix">

-<title>Querying Color Space Format and Prefix</title>

-<!-- .XS -->

-<!-- (SN Querying Color Space Format and Prefix -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To obtain the format associated with the color space

-associated with a specified color string prefix, use

-<function>XcmsFormatOfPrefix</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsFormatOfPrefix</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XcmsColorFormat <function>XcmsFormatOfPrefix</function></funcdef>

-  <paramdef>char<parameter> *prefix</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>prefix</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the string that contains the color space prefix.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsFormatOfPrefix</function>

-function returns the format for the specified color space prefix

-(for example, the string ``CIEXYZ'').

-The prefix is case-insensitive.

-If the color space is not accessible in the color management system,

-<function>XcmsFormatOfPrefix</function>

-returns 

-<symbol>XcmsUndefinedFormat</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the color string prefix associated with the color space

-specified by a color format, use

-<function>XcmsPrefixOfFormat</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsPrefixOfFormat</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XcmsPrefixOfFormat</function></funcdef>

-  <paramdef>XcmsColorFormat<parameter> format</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color specification format.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsPrefixOfFormat</function>

-function returns the string prefix associated with the color specification

-encoding specified by the format argument.

-Otherwise, if no encoding is found, it returns NULL.

-The returned string must be treated as read-only.

-</para>

-</sect2>

-<sect2 id="Creating_Additional_Color_Spaces">

-<title>Creating Additional Color Spaces</title>

-<!-- .XS -->

-<!-- (SN Creating Additional Color Spaces -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Color space specific information necessary 

-for color space conversion and color string parsing is stored in an

-<structname>XcmsColorSpace</structname>

-structure.

-Therefore, a new structure containing this information is required

-for each additional color space.

-In the case of device-independent color spaces,

-a handle to this new structure (that is, by means of a global variable)

-is usually made accessible to the client program for use with the

-<function>XcmsAddColorSpace</function>

-function.

-</para>

-<para>

-<!-- .LP -->

-If a new 

-<structname>XcmsColorSpace</structname>

-structure specifies a color space not registered with the X Consortium,

-they should be treated as private to the client

-because format values for unregistered color spaces are assigned at run time.

-If references to an unregistered color space must be made outside the

-client (for example, storing color specifications in a file using the

-unregistered color space), then reference should be made by color space prefix

-(see

-<function>XcmsFormatOfPrefix</function>

-and

-<function>XcmsPrefixOfFormat</function>).

-<!-- .sM -->

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef (*XcmsConversionProc)();

-typedef XcmsConversionProc *XcmsFuncListPtr;

-		/* A NULL terminated list of function pointers*/

-

-typedef struct _XcmsColorSpace {

-	char *prefix;

-	XcmsColorFormat format;

-	XcmsParseStringProc parseString;

-	XcmsFuncListPtr to_CIEXYZ;

-	XcmsFuncListPtr from_CIEXYZ;

-	int inverse_flag;

-} XcmsColorSpace;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The prefix member specifies the prefix that indicates a color string 

-is in this color space's string format.

-For example, the strings ``ciexyz'' or ``CIEXYZ'' for <acronym>CIE</acronym> XYZ,

-and ``rgb'' or ``<acronym>RGB</acronym>'' for <acronym>RGB</acronym>.

-The prefix is case insensitive.

-The format member specifies the color specification format.

-Formats for unregistered color spaces are assigned at run time.

-The parseString member contains a pointer to the function 

-that can parse a color string into an 

-<structname>XcmsColor</structname>

-structure.

-This function returns an integer (int): nonzero if it succeeded

-and zero otherwise.

-The to_CIEXYZ and from_CIEXYZ members contain pointers,

-each to a NULL terminated list of function pointers.

-When the list of functions is executed in series,

-it will convert the color specified in an 

-<structname>XcmsColor</structname>

-structure from/to the current color space format to/from the <acronym>CIE</acronym> XYZ format.

-Each function returns an integer (int): nonzero if it succeeded

-and zero otherwise.

-The white point to be associated with the colors is specified

-explicitly, even though white points can be found in the CCC.

-The inverse_flag member, if nonzero, specifies that for each function listed 

-in to_CIEXYZ,

-its inverse function can be found in from_CIEXYZ such that:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-Given:  n = number of functions in each list

-

-for each i, such that 0 &lt;= i &lt; n

-    from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-This allows Xlib to use the shortest conversion path,

-thus bypassing <acronym>CIE</acronym> XYZ if possible (for example, TekHVC to <acronym>CIE</acronym> L*u*v*).

-</para>

-</sect2>

-<sect2 id="Parse_String_Callback">

-<title>Parse String Callback</title>

-<!-- .XS -->

-<!-- (SN Parse String Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The callback in the

-<structname>XcmsColorSpace</structname>

-structure for parsing a color string for the particular color space must

-adhere to the following software interface specification:

-</para>

-<indexterm significance="preferred"><primary>XcmsParseStringProc</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsParseStringProc</function></funcdef>

-  <paramdef>char<parameter> *color_string</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the color string to parse.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>color_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the color specification in the color space's format.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-</sect2>

-<sect2 id="Color_Specification_Conversion_Callback">

-<title>Color Specification Conversion Callback</title>

-<!-- .XS -->

-<!-- (SN Color Specification Conversion Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Callback functions in the

-<structname>XcmsColorSpace</structname>

-structure for converting a color specification between device-independent

-spaces must adhere to the

-following software interface specification:

-</para>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function><replaceable>ConversionProc</replaceable></function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *white_point</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *colors_in_out</parameter></paramdef>

-  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>white_point</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the white point associated with color specifications.

-The pixel member should be ignored,

-and the entire structure remain unchanged upon return.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colors_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of color specifications.

-Pixel members should be ignored and must remain unchanged upon return.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of 

-<structname>XcmsColor</structname>

-structures in the color-specification array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-Callback functions in the

-<structname>XcmsColorSpace</structname>

-structure for converting a color specification to or from a device-dependent

-space must adhere to the

-following software interface specification:

-</para>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function><replaceable>ConversionProc</replaceable></function></funcdef>

-  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>

-  <paramdef>XcmsColor<parameter> *colors_in_out</parameter></paramdef>

-  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>

-  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ccc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the CCC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colors_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of color specifications.

-Pixel members should be ignored and must remain unchanged upon return.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ncolors</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of 

-<structname>XcmsColor</structname>

-structures in the color-specification array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>compression_flags_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of Boolean values for indicating compression status.

-If a non-NULL pointer is supplied

-and a color at a given index is compressed, then

-<symbol>True</symbol>

-should be stored at the corresponding index in this array;

-otherwise, the array should not be modified.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Conversion functions are available globally for use by other color

-spaces.

-The conversion functions provided by Xlib are:

-</para>

-<informaltable>

-  <tgroup cols='3' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <thead>

-    <row>

-      <entry>Function</entry>

-      <entry>Converts from</entry>

-      <entry>Converts to</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry><function>XcmsCIELabToCIEXYZ</function></entry>

-      <entry><symbol>XcmsCIELabFormat</symbol></entry>

-      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIELuvToCIEuvY</function></entry>

-      <entry><symbol>XcmsCIELuvFormat</symbol></entry>

-      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIEXYZToCIELab</function></entry>

-      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>

-      <entry><symbol>XcmsCIELabFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIEXYZToCIEuvY</function></entry>

-      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>

-      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIEXYZToCIExyY</function></entry>

-      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>

-      <entry><symbol>XcmsCIExyYFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIEXYZToRGBi</function></entry>

-      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>

-      <entry><symbol>XcmsRGBiFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIEuvYToCIELuv</function></entry>

-      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>

-      <entry><symbol>XcmsCIELabFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIEuvYToCIEXYZ</function></entry>

-      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>

-      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIEuvYToTekHVC</function></entry>

-      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>

-      <entry><symbol>XcmsTekHVCFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsCIExyYToCIEXYZ</function></entry>

-      <entry><symbol>XcmsCIExyYFormat</symbol></entry>

-      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsRGBToRGBi</function></entry>

-      <entry><symbol>XcmsRGBFormat</symbol></entry>

-      <entry><symbol>XcmsRGBiFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsRGBiToCIEXYZ</function></entry>

-      <entry><symbol>XcmsRGBiFormat</symbol></entry>

-      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsRGBiToRGB</function></entry>

-      <entry><symbol>XcmsRGBiFormat</symbol></entry>

-      <entry><symbol>XcmsRGBFormat</symbol></entry>

-    </row>

-    <row>

-      <entry><function>XcmsTekHVCToCIEuvY</function></entry>

-      <entry><symbol>XcmsTekHVCFormat</symbol></entry>

-      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-</sect2>

-<sect2 id="Function_Sets">

-<title>Function Sets</title>

-<!-- .XS -->

-<!-- (SN Function Sets -->

-<!-- .XE -->

-<indexterm><primary>Function set</primary></indexterm>

-<indexterm><primary>Function set</primary><secondary>LINEAR_RGB</secondary></indexterm>

-<para>

-<!-- .LP -->

-Functions to convert between device-dependent color spaces

-and <acronym>CIE</acronym> XYZ may differ for different classes of output devices

-(for example, color versus gray monitors).

-Therefore, the notion of a Color Characterization Function Set

-has been developed.

-A function set consists of device-dependent color spaces

-and the functions that convert color specifications 

-between these device-dependent color spaces and the <acronym>CIE</acronym> XYZ color space

-appropriate for a particular class of output devices.

-The function set also contains a function that reads

-color characterization data off root window properties.

-It is this characterization data that will differ between devices within

-a class of output devices.

-<indexterm><primary>Device Color Characterization</primary></indexterm>

-For details about how color characterization data is

-stored in root window properties,

-see the section on Device Color Characterization in the

-<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.

-The LINEAR_RGB function set is provided by Xlib

-and will support most color monitors.

-Function sets may require data that differs

-from those needed for the LINEAR_RGB function set.

-In that case, 

-its corresponding data may be stored on different root window properties.

-</para>

-</sect2>

-<sect2 id="Adding_Function_Sets">

-<title>Adding Function Sets</title>

-<!-- .XS -->

-<!-- (SN Adding Function Sets -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To add a function set, use

-<function>XcmsAddFunctionSet</function>.

-</para>

-<indexterm significance="preferred"><primary>XcmsAddFunctionSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XcmsAddFunctionSet</function></funcdef>

-  <paramdef>XcmsFunctionSet<parameter> *function_set</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>function_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the function set to add.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XcmsAddFunctionSet</function>

-function adds a function set to the color management system.

-If the function set uses device-dependent 

-<structname>XcmsColorSpace</structname>

-structures not accessible in the color management system,

-<function>XcmsAddFunctionSet</function>

-adds them.

-If an added

-<structname>XcmsColorSpace</structname>

-structure is for a device-dependent color space not registered

-with the X Consortium,

-they should be treated as private to the client

-because format values for unregistered color spaces are assigned at run time.

-If references to an unregistered color space must be made outside the

-client (for example, storing color specifications in a file

-using the unregistered color space),

-then reference should be made by color space prefix

-(see 

-<function>XcmsFormatOfPrefix</function>

-and

-<function>XcmsPrefixOfFormat</function>).

-</para>

-<para>

-<!-- .LP -->

-Additional function sets should be added before any calls to other

-Xlib routines are made.

-If not, the 

-<structname>XcmsPerScrnInfo</structname>

-member of a previously created 

-<structname>XcmsCCC</structname>

-does not have the opportunity to initialize

-with the added function set.

-</para>

-</sect2>

-<sect2 id="Creating_Additional_Function_Sets">

-<title>Creating Additional Function Sets</title>

-<!-- .XS -->

-<!-- (SN Creating Additional Function Sets -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The creation of additional function sets should be

-required only when an output device does not conform to existing 

-function sets or when additional device-dependent color spaces are necessary.

-A function set consists primarily of a collection of device-dependent

-<structname>XcmsColorSpace</structname>

-structures and a means to read and store a 

-screen's color characterization data.

-This data is stored in an

-<structname>XcmsFunctionSet</structname>

-structure.

-A handle to this structure (that is, by means of global variable)

-is usually made accessible to the client program for use with

-<function>XcmsAddFunctionSet</function>.

-</para>

-<para>

-<!-- .LP -->

-If a function set uses new device-dependent 

-<structname>XcmsColorSpace</structname>

-structures,

-they will be transparently processed into the color management system.

-Function sets can share an 

-<structname>XcmsColorSpace</structname>

-structure for a device-dependent color space.

-In addition, multiple 

-<structname>XcmsColorSpace</structname>

-structures are allowed for a device-dependent color space;

-however, a function set can reference only one of them.

-These 

-<structname>XcmsColorSpace</structname>

-structures will differ in the functions to convert to and from <acronym>CIE</acronym> XYZ,

-thus tailored for the specific function set.

-<!-- .sM -->

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct _XcmsFunctionSet {

-	XcmsColorSpace **DDColorSpaces;

-	XcmsScreenInitProc screenInitProc;

-	XcmsScreenFreeProc screenFreeProc;

-} XcmsFunctionSet;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The DDColorSpaces member is a pointer to a NULL terminated list

-of pointers to 

-<structname>XcmsColorSpace</structname>

-structures for the device-dependent color spaces that are supported

-by the function set.

-The screenInitProc member is set to the callback procedure (see the following

-interface specification) that initializes the 

-<structname>XcmsPerScrnInfo</structname>

-structure for a particular screen.

-</para>

-<para>

-<!-- .LP -->

-The screen initialization callback must adhere to the following software

-interface specification:

-<indexterm significance="preferred"><primary>XcmsScreenInitProc</primary></indexterm>

-<!-- .sM -->

-</para>

-<funcsynopsis>

-<funcprototype>

-  <funcdef>typedef Status <function>(*XcmsScreenInitProc</function>)</funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> screen_number</parameter></paramdef>

-  <paramdef>ScmsPerScrnInfo<parameter> *screen_info</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the appropriate screen number on the host server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_info</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XcmsPerScrnInfo</structname>

-structure, which contains the per screen information.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The screen initialization callback in the

-<structname>XcmsFunctionSet</structname>

-structure fetches the color characterization data (device profile) for

-the specified screen,

-typically off properties on the 

-screen's root window.

-It then initializes the specified

-<structname>XcmsPerScrnInfo</structname>

-structure.

-<indexterm><primary>Device profile</primary></indexterm>

-<indexterm><primary>Color Characterization Data</primary></indexterm>

-If successful, the procedure fills in the 

-<structname>XcmsPerScrnInfo</structname>

-structure as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-It sets the screenData member to the address 

-of the created device profile data structure 

-(contents known only by the function set).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-It next sets the screenWhitePoint member.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-It next sets the functionSet member to the address of the

-<structname>XcmsFunctionSet</structname>

-structure.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-It then sets the state member to 

-<symbol>XcmsInitSuccess</symbol>

-and finally returns

-<symbol>XcmsSuccess</symbol>.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-If unsuccessful, the procedure sets the state member to 

-<symbol>XcmsInitFailure</symbol>

-and returns

-<symbol>XcmsFailure</symbol>.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XcmsPerScrnInfo</structname>

-structure contains:

-<!-- .sM -->

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct _XcmsPerScrnInfo {

-	XcmsColor screenWhitePoint;

-	XPointer functionSet;

-	XPointer screenData;

-	unsigned char state;

-	char pad[3];

-} XcmsPerScrnInfo;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The screenWhitePoint member specifies the white point inherent to

-the screen.

-The functionSet member specifies the appropriate function set.

-The screenData member specifies the device profile.

-The state member is set to one of the following:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-<symbol>XcmsInitNone</symbol>

-indicates initialization has not been previously attempted.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<symbol>XcmsInitFailure</symbol>

-indicates initialization has been previously attempted but failed.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<symbol>XcmsInitSuccess</symbol>

-indicates initialization has been previously attempted and succeeded.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The screen free callback must adhere to the following software

-interface specification:

-</para>

-<funcsynopsis>

-<funcprototype>

-  <funcdef>typedef void (*XcmsScreenFreeProc)</funcdef>

-  <paramdef>XPointer<parameter> screenData</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screenData</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the data to be freed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-This function is called to free the screenData stored in an

-<structname>XcmsPerScrnInfo</structname>

-structure.

-<!-- .bp -->

-

-</para>

-</sect2>

-</sect1>

-</chapter>

+<?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="color_management_functions">
+<title>Color Management Functions</title>
+<!-- .sp 2 -->
+<!-- .nr H1 6 -->
+<!-- .nr H2 0 -->
+<!-- .nr H3 0 -->
+<!-- .nr H4 0 -->
+<!-- .nr H5 0 -->
+<!-- .na -->
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Chapter 6: Color Management Functions  -->
+<!-- .XE -->
+Each X window always has an associated colormap that
+provides a level of indirection between pixel values and colors displayed
+on the screen.
+Xlib provides functions that you can use to manipulate a colormap.
+The X protocol defines colors using values in the <acronym>RGB</acronym> color space.
+The <acronym>RGB</acronym> color space is device dependent;
+rendering an <acronym>RGB</acronym> value on differing output devices typically results
+in different colors.
+Xlib also provides a means for clients to specify color using
+device-independent color spaces for consistent results across devices.
+Xlib supports device-independent color spaces derivable from the <acronym>CIE</acronym> XYZ
+color space.
+This includes the <acronym>CIE</acronym> XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as
+the TekHVC color space.
+</para>
+<para>
+<!-- .LP -->
+This chapter discusses how to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Create, copy, and destroy a colormap
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Specify colors by name or value
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Allocate, modify, and free color cells
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Read entries in a colormap
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Convert between color spaces
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Control aspects of color conversion
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Query the color gamut of a screen
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Add new color spaces
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+All functions, types, and symbols in this chapter with the prefix ``Xcms''
+are defined in
+<filename class="headerfile">&lt;X11/Xcms.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xcms.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xcms.h&gt;</filename></secondary></indexterm>
+The remaining functions and types are defined in
+<filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Functions in this chapter manipulate the representation of color on the
+screen.
+For each possible value that a pixel can take in a window,
+there is a color cell in the colormap.
+For example, 
+if a window is 4 bits deep, pixel values 0 through 15 are defined. 
+A colormap is a collection of color cells.
+A color cell consists of a triple of red, green, and blue (<acronym>RGB</acronym>) values.
+The hardware imposes limits on the number of significant
+bits in these values.
+As each pixel is read out of display memory, the pixel
+is looked up in a colormap.
+The <acronym>RGB</acronym> value of the cell determines what color is displayed on the screen.
+On a grayscale display with a black-and-white monitor, 
+the values are combined to determine the brightness on the screen.
+</para>
+<para>
+<!-- .LP -->
+Typically, an application allocates color cells or sets of color cells
+to obtain the desired colors.
+The client can allocate read-only cells.
+In which case, 
+the pixel values for these colors can be shared among multiple applications, 
+and the <acronym>RGB</acronym> value of the cell cannot be changed.
+If the client allocates read/write cells,
+they are exclusively owned by the client,
+and the color associated with the pixel value can be changed at will.
+Cells must be allocated (and, if read/write, initialized with an <acronym>RGB</acronym> value)
+by a client to obtain desired colors.
+The use of pixel value for an
+unallocated cell results in an undefined color.
+</para>
+<para>
+<!-- .LP -->
+Because colormaps are associated with windows, X supports displays
+with multiple colormaps and, indeed, different types of colormaps.
+If there are insufficient colormap resources in the display,
+some windows will display in their true colors, and others
+will display with incorrect colors.
+A window manager usually controls which windows are displayed
+in their true colors if more than one colormap is required for
+the color resources the applications are using.
+At any time, there is a set of installed colormaps for a screen.
+Windows using one of the installed colormaps display with true colors, and
+windows using other colormaps generally display with incorrect colors.
+You can control the set of installed colormaps by using
+<function>XInstallColormap</function>
+and
+<function>XUninstallColormap</function>.
+</para>
+<para>
+<!-- .LP -->
+Colormaps are local to a particular screen.
+Screens always have a default colormap,
+and programs typically allocate cells out of this colormap.
+Generally, you should not write applications that monopolize 
+color resources.
+Although some hardware supports multiple colormaps installed at one time,
+many of the hardware displays
+built today support only a single installed colormap, so the primitives
+are written to encourage sharing of colormap entries between applications.
+</para>
+<para>
+<!-- .LP -->
+The 
+<function>DefaultColormap</function>
+macro returns the default colormap.
+The 
+<function>DefaultVisual</function>
+macro
+returns the default visual type for the specified screen.
+<indexterm><primary>Color map</primary></indexterm>
+Possible visual types are 
+<symbol>StaticGray</symbol>,
+<symbol>GrayScale</symbol>,
+<symbol>StaticColor</symbol>,
+<symbol>PseudoColor</symbol>,
+<symbol>TrueColor</symbol>,
+or 
+<symbol>DirectColor</symbol>
+(see section 3.1).
+</para>
+<sect1 id="Color_Structures">
+<title>Color Structures</title>
+<!-- .XS -->
+<!-- (SN Color Structures -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Functions that operate only on <acronym>RGB</acronym> color space values use an
+<structname>XColor</structname>
+structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XColor</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	unsigned long pixel;	/* pixel value */
+	unsigned short red, green, blue;	/* rgb values */
+	char flags;	/* DoRed, DoGreen, DoBlue */	
+	char pad;
+} XColor;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The red, green, and blue values are always in the range 0 to 65535
+inclusive, independent of the number of bits actually used in the
+display hardware.
+The server scales these values down to the range used by the hardware.
+Black is represented by (0,0,0), 
+and white is represented by (65535,65535,65535).
+<indexterm><primary>Color</primary></indexterm>
+In some functions,
+the flags member controls which of the red, green, and blue members is used 
+and can be the inclusive OR of zero or more of
+<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and 
+<symbol>DoBlue</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Functions that operate on all color space values use an
+<structname>XcmsColor</structname>
+structure.
+This structure contains a union of substructures,
+each supporting color specification encoding for a particular color space.
+Like the
+<structname>XColor</structname>
+structure, the
+<structname>XcmsColor</structname>
+structure contains pixel
+and color specification information (the spec member in the 
+<structname>XcmsColor</structname>
+structure).
+<indexterm significance="preferred"><primary>XcmsColor</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 2.5i -->
+<!-- .ta .5i 1i 2.5i -->
+typedef unsigned long XcmsColorFormat;			/* Color Specification Format */
+
+typedef struct {
+	union {
+		XcmsRGB RGB;
+		XcmsRGBi RGBi;
+		XcmsCIEXYZ CIEXYZ;
+		XcmsCIEuvY CIEuvY;
+		XcmsCIExyY CIExyY;
+		XcmsCIELab CIELab;
+		XcmsCIELuv CIELuv;
+		XcmsTekHVC TekHVC;
+		XcmsPad Pad;
+	} spec;
+	unsigned long pixel;
+	XcmsColorFormat format;
+} XcmsColor;			/* Xcms Color Structure */
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Because the color specification can be encoded for the various color spaces, 
+encoding for the spec member is identified by the format member,
+which is of type
+<type>XcmsColorFormat</type>.
+The following macros define standard formats.
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+#define          XcmsUndefinedFormat   0x00000000
+#define          XcmsCIEXYZFormat      0x00000001  /* CIE XYZ */
+#define          XcmsCIEuvYFormat      0x00000002  /* CIE u'v'Y */
+#define          XcmsCIExyYFormat      0x00000003  /* CIE xyY */
+#define          XcmsCIELabFormat      0x00000004  /* CIE L*a*b* */
+#define          XcmsCIELuvFormat      0x00000005  /* CIE L*u*v* */
+#define          XcmsTekHVCFormat      0x00000006  /* TekHVC */
+#define          XcmsRGBFormat         0x80000000  /* RGB Device */
+#define          XcmsRGBiFormat        0x80000001  /* RGB Intensity */
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Formats for device-independent color spaces are
+distinguishable from those for device-dependent spaces by the 32nd bit.
+If this bit is set,
+it indicates that the color specification is in a device-dependent form;
+otherwise, it is in a device-independent form.
+If the 31st bit is set,
+this indicates that the color space has been added to Xlib at run time
+(see section 6.12.4).
+The format value for a color space added at run time may be different each
+time the program is executed.
+If references to such a color space must be made outside the client
+(for example, storing a color specification in a file),
+then reference should be made by color space string prefix
+(see 
+<function>XcmsFormatOfPrefix</function>
+and
+<function>XcmsPrefixOfFormat</function>).
+</para>
+<para>
+<!-- .LP -->
+Data types that describe the color specification encoding for the various
+color spaces are defined as follows:
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XcmsRGB</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef double XcmsFloat;
+
+typedef struct {
+	unsigned short red;	/* 0x0000 to 0xffff */
+	unsigned short green;	/* 0x0000 to 0xffff */
+	unsigned short blue;	/* 0x0000 to 0xffff */
+} XcmsRGB;		/* RGB Device */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsRGBi</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	XcmsFloat red;	/* 0.0 to 1.0 */
+	XcmsFloat green;	/* 0.0 to 1.0 */
+	XcmsFloat blue;	/* 0.0 to 1.0 */
+} XcmsRGBi;		/* RGB Intensity */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIEXYZ</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	XcmsFloat X;
+	XcmsFloat Y;	/* 0.0 to 1.0 */
+	XcmsFloat Z;
+} XcmsCIEXYZ;		/* CIE XYZ */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIEuvY</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	XcmsFloat u_prime;	/* 0.0 to ~0.6 */
+	XcmsFloat v_prime;	/* 0.0 to ~0.6 */
+	XcmsFloat Y; 	/* 0.0 to 1.0 */
+} XcmsCIEuvY;		/* CIE u'v'Y */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIExyY</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	XcmsFloat x; 	/* 0.0 to ~.75 */
+	XcmsFloat y; 	/* 0.0 to ~.85 */
+	XcmsFloat Y; 	/* 0.0 to 1.0 */
+} XcmsCIExyY;		/* CIE xyY */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIELab</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	XcmsFloat L_star; 	/* 0.0 to 100.0 */
+	XcmsFloat a_star;
+	XcmsFloat b_star;
+} XcmsCIELab;		/* CIE L*a*b* */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsCIELuv</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	XcmsFloat L_star; 	/* 0.0 to 100.0 */
+	XcmsFloat u_star;
+	XcmsFloat v_star;
+} XcmsCIELuv;		/* CIE L*u*v* */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsTekHVC</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	XcmsFloat H; 	/* 0.0 to 360.0 */
+	XcmsFloat V; 	/* 0.0 to 100.0 */
+	XcmsFloat C; 	/* 0.0 to 100.0 */
+} XcmsTekHVC;		/* TekHVC */
+</literallayout>
+<indexterm significance="preferred"><primary>XcmsPad</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	XcmsFloat pad0;
+	XcmsFloat pad1;
+	XcmsFloat pad2;
+	XcmsFloat pad3;
+} XcmsPad;		/* four doubles */
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The device-dependent formats provided allow color specification in:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<acronym>RGB</acronym> Intensity
+(<structname>XcmsRGBi</structname>)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Red, green, and blue linear intensity values,
+floating-point values from 0.0 to 1.0,
+where 1.0 indicates full intensity, 0.5 half intensity, and so on.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<acronym>RGB</acronym> Device
+(<structname>XcmsRGB</structname>)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Red, green, and blue values appropriate for the specified output device.
+<structname>XcmsRGB</structname>
+values are of type unsigned short,
+scaled from 0 to 65535 inclusive,
+and are interchangeable with the red, green, and blue values in an 
+<structname>XColor</structname>
+structure. 
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+It is important to note that <acronym>RGB</acronym> Intensity values are not gamma corrected
+values.
+In contrast,
+<acronym>RGB</acronym> Device values generated as a result of converting color specifications 
+are always gamma corrected, and
+<acronym>RGB</acronym> Device values acquired as a result of querying a colormap
+or passed in by the client are assumed by Xlib to be gamma corrected.
+The term <emphasis remap='I'><acronym>RGB</acronym> value</emphasis> in this manual always refers to an <acronym>RGB</acronym> Device value.
+</para>
+</sect1>
+<sect1 id="Color_Strings">
+<title>Color Strings</title>
+<!-- .XS -->
+<!-- (SN Color Strings -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides a mechanism for using string names for colors.
+A color string may either contain an abstract color name
+or a numerical color specification.
+Color strings are case-insensitive.
+</para>
+<para>
+<!-- .LP -->
+Color strings are used in the following functions:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<function>XAllocNamedColor</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsAllocNamedColor</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XLookupColor</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsLookupColor</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XParseColor</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XStoreNamedColor</function>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Xlib supports the use of abstract color names, for example, red or blue.
+A value for this abstract name is obtained by searching one or more color
+name databases.
+Xlib first searches zero or more client-side databases;
+the number, location, and content of these databases is
+implementation-dependent and might depend on the current locale.
+If the name is not found, Xlib then looks for the color in the
+X server's database.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+A numerical color specification
+consists of a color space name and a set of values in the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<emphasis remap='I'>&lt;color_space_name&gt;</emphasis>:<emphasis remap='I'>&lt;value&gt;/.../&lt;value&gt;</emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The following are examples of valid color strings.
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+"CIEXYZ:0.3227/0.28133/0.2493"
+"RGBi:1.0/0.0/0.0"
+"rgb:00/ff/00"
+"CIELuv:50.0/0.0/0.0"
+</literallayout>
+The syntax and semantics of numerical specifications are given
+for each standard color space in the following sections.
+</para>
+<sect2 id="RGB_Device_String_Specification">
+<title><acronym>RGB</acronym> Device String Specification</title>
+<!-- .XS -->
+<!-- (SN <acronym>RGB</acronym> Device String Specification -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An <acronym>RGB</acronym> Device specification is identified by
+the prefix ``rgb:'' and conforms to the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+rgb:<emphasis remap='I'>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</emphasis>
+
+    <emphasis remap='I'>&lt;red&gt;</emphasis>, <emphasis remap='I'>&lt;green&gt;</emphasis>, <emphasis remap='I'>&lt;blue&gt;</emphasis> := <emphasis remap='I'>h</emphasis> | <emphasis remap='I'>hh</emphasis> | <emphasis remap='I'>hhh</emphasis> | <emphasis remap='I'>hhhh</emphasis>
+    <emphasis remap='I'>h</emphasis> := single hexadecimal digits (case insignificant)
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+Note that <emphasis remap='I'>h</emphasis> indicates the value scaled in 4 bits, 
+<emphasis remap='I'>hh</emphasis> the value scaled in 8 bits,
+<emphasis remap='I'>hhh</emphasis> the value scaled in 12 bits,
+and <emphasis remap='I'>hhhh</emphasis> the value scaled in 16 bits, respectively.
+</para>
+<para>
+<!-- .LP -->
+Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'',
+but mixed numbers of hexadecimal digit strings 
+(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'')
+are also allowed.
+</para>
+<para>
+<!-- .LP -->
+For backward compatibility, an older syntax for <acronym>RGB</acronym> Device is
+supported, but its continued use is not encouraged.
+The syntax is an initial sharp sign character followed by
+a numeric specification, in one of the following formats:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+<!-- .TA 2i -->
+<!-- .ta 2i -->
+#RGB	(4 bits each)
+#RRGGBB	(8 bits each)
+#RRRGGGBBB	(12 bits each)
+#RRRRGGGGBBBB	(16 bits each)
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+The R, G, and B represent single hexadecimal digits.
+When fewer than 16 bits each are specified, 
+they represent the most significant bits of the value
+(unlike the ``rgb:'' syntax, in which values are scaled).
+For example, the string ``#3a7'' is the same as ``#3000a0007000''.
+</para>
+</sect2>
+<sect2 id="RGB_Intensity_String_Specification">
+<title><acronym>RGB</acronym> Intensity String Specification</title>
+<!-- .XS -->
+<!-- (SN RGB Intensity String Specification -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An <acronym>RGB</acronym> intensity specification is identified
+by the prefix ``rgbi:'' and conforms to the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+rgbi:<emphasis remap='I'>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</emphasis>
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+Note that red, green, and blue are floating-point values
+between 0.0 and 1.0, inclusive.
+The input format for these values is an optional sign,
+a string of numbers possibly containing a decimal point,
+and an optional exponent field containing an E or e 
+followed by a possibly signed integer string.
+</para>
+</sect2>
+<sect2 id="Device_Independent_String_Specifications">
+<title>Device-Independent String Specifications</title>
+<!-- .XS -->
+<!-- (SN Device-Independent String Specifications -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The standard device-independent string specifications have
+the following syntax:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+CIEXYZ:<emphasis remap='I'>&lt;X&gt;/&lt;Y&gt;/&lt;Z&gt;</emphasis>
+CIEuvY:<emphasis remap='I'>&lt;u&gt;/&lt;v&gt;/&lt;Y&gt;</emphasis>
+CIExyY:<emphasis remap='I'>&lt;x&gt;/&lt;y&gt;/&lt;Y&gt;</emphasis>
+CIELab:<emphasis remap='I'>&lt;L&gt;/&lt;a&gt;/&lt;b&gt;</emphasis>
+CIELuv:<emphasis remap='I'>&lt;L&gt;/&lt;u&gt;/&lt;v&gt;</emphasis>
+TekHVC:<emphasis remap='I'>&lt;H&gt;/&lt;V&gt;/&lt;C&gt;</emphasis>
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
+floating-point values.
+The syntax for these values is an optional plus or minus sign,
+a string of digits possibly containing a decimal point,
+and an optional exponent field consisting of an ``E'' or ``e''
+followed by an optional plus or minus followed by a string of digits.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Color_Conversion_Contexts_and_Gamut_Mapping">
+<title>Color Conversion Contexts and Gamut Mapping</title>
+<!-- .XS -->
+<!-- (SN Color Conversion Contexts and Gamut Mapping -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When Xlib converts device-independent color specifications
+into device-dependent specifications and vice versa,
+it uses knowledge about the color limitations of the screen hardware.
+This information, typically called the device profile,
+<indexterm><primary>Device profile</primary></indexterm>
+is available in a Color Conversion Context (CCC).
+<indexterm><primary>Color Conversion Context</primary></indexterm>
+<indexterm><primary>CCC</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Because a specified color may be outside the color gamut of the target screen
+and the white point associated with the color specification may differ
+from the white point inherent to the screen,
+Xlib applies gamut mapping when it encounters certain conditions:
+<indexterm><primary>White point</primary></indexterm>
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Gamut compression occurs when conversion of device-independent
+color specifications to device-dependent color specifications
+results in a color out of the target screen's gamut.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+White adjustment occurs when the inherent white point of the screen
+differs from the white point assumed by the client.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Gamut handling methods are stored as callbacks in the CCC,
+which in turn are used by the color space conversion routines.
+Client data is also stored in the CCC for each callback.
+The CCC also contains the white point the client assumes to be
+associated with color specifications (that is, the Client White Point).
+<indexterm><primary>Client White Point</primary></indexterm>
+<indexterm><primary>Gamut compression</primary></indexterm>
+<indexterm><primary>Gamut handling</primary></indexterm>
+<indexterm><primary>White point adjustment</primary></indexterm>
+The client can specify the gamut handling callbacks and client data
+as well as the Client White Point.
+Xlib does not preclude the X client from performing other
+forms of gamut handling (for example, gamut expansion); 
+however, Xlib does not provide direct support for gamut handling
+other than white adjustment and gamut compression.
+</para>
+<para>
+<!-- .LP -->
+Associated with each colormap is an initial CCC transparently generated by
+Xlib.
+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
+Therefore,
+when you specify a colormap as an argument to an Xlib function,
+you are indirectly specifying a CCC.
+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
+There is a default CCC associated with each screen.
+Newly created CCCs inherit attributes from the default CCC,
+so the default CCC attributes can be modified to affect new CCCs.
+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Xcms functions in which gamut mapping can occur return
+<type>Status</type>
+and have specific status values defined for them, 
+as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<symbol>XcmsFailure</symbol>
+indicates that the function failed.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<symbol>XcmsSuccess</symbol>
+indicates that the function succeeded.
+In addition,
+if the function performed any color conversion,
+the colors did not need to be compressed.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<symbol>XcmsSuccessWithCompression</symbol>
+indicates the function performed color conversion
+and at least one of the colors needed to be compressed.
+The gamut compression method is determined by the gamut compression
+procedure in the CCC that is specified directly as a function argument
+or in the CCC indirectly specified by means of the colormap argument.
+    </para>
+  </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Creating_Copying_and_Destroying_Colormaps">
+<title>Creating, Copying, and Destroying Colormaps</title>
+<!-- .XS -->
+<!-- (SN Creating, Copying, and Destroying Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To create a colormap for a screen, use
+<function>XCreateColormap</function>.</para>
+<indexterm significance="preferred"><primary>XCreateColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatecolormap'>
+<funcprototype>
+  <funcdef>Colormap <function>XCreateColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Visual<parameter> *visual</parameter></paramdef>
+  <paramdef>int<parameter> alloc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi on whose screen you want to create a colormap -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>visual</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a visual type supported on the screen.
+If the visual type is not one supported by the screen, 
+a
+<errorname>BadMatch</errorname>
+error results.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>alloc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap entries to be allocated.
+You can pass 
+<symbol>AllocNone</symbol>
+or 
+<symbol>AllocAll</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateColormap</function>
+function creates a colormap of the specified visual type for the screen 
+on which the specified window resides and returns the colormap ID 
+associated with it.
+Note that the specified window is only used to determine the screen.
+</para>
+<para>
+<!-- .LP -->
+The initial values of the colormap entries are undefined for the 
+visual classes
+<symbol>GrayScale</symbol>,
+<symbol>PseudoColor</symbol>,
+and
+<symbol>DirectColor</symbol>.
+For
+<symbol>StaticGray</symbol>,
+<symbol>StaticColor</symbol>,
+and
+<symbol>TrueColor</symbol>,
+the entries have defined values,
+but those values are specific to the visual and are not defined by X.
+For
+<symbol>StaticGray</symbol>,
+<symbol>StaticColor</symbol>,
+and
+<symbol>TrueColor</symbol>,
+alloc must be
+<symbol>AllocNone</symbol>,
+or a
+<errorname>BadMatch</errorname>
+error results.
+For the other visual classes,
+if alloc is
+<symbol>AllocNone</symbol>,
+the colormap initially has no allocated entries,
+and clients can allocate them.
+For information about the visual types,
+see section 3.1.
+</para>
+<para>
+<!-- .LP -->
+If alloc is
+<symbol>AllocAll</symbol>,
+the entire colormap is allocated writable.
+The initial values of all allocated entries are undefined.
+For
+<symbol>GrayScale</symbol>
+and
+<symbol>PseudoColor</symbol>,
+the effect is as if an
+<function>XAllocColorCells</function>
+call returned all pixel values from zero to N - 1,
+where N is the colormap entries value in the specified visual.
+For
+<symbol>DirectColor</symbol>,
+the effect is as if an
+<function>XAllocColorPlanes</function>
+call returned a pixel value of zero and red_mask, green_mask, 
+and blue_mask values containing the same bits as the corresponding
+masks in the specified visual.
+However, in all cases,
+none of these entries can be freed by using
+<function>XFreeColors</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateColormap</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a new colormap when the allocation out of a previously
+shared colormap has failed because of resource exhaustion, use
+<function>XCopyColormapAndFree</function>.
+<indexterm significance="preferred"><primary>XCopyColormapAndFree</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcopycolormapandfree'>
+<funcprototype>
+  <funcdef>Colormap <function>XCopyColormapAndFree</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCopyColormapAndFree</function>
+function creates a colormap of the same visual type and for the same screen
+as the specified colormap and returns the new colormap ID.
+It also moves all of the client's existing allocation from the specified
+colormap to the new colormap with their color values intact 
+and their read-only or writable characteristics intact and frees those entries 
+in the specified colormap.
+Color values in other entries in the new colormap are undefined.
+If the specified colormap was created by the client with alloc set to
+<symbol>AllocAll</symbol>,
+the new colormap is also created with 
+<symbol>AllocAll</symbol>,
+all color values for all entries are copied from the specified colormap,
+and then all entries in the specified colormap are freed.
+If the specified colormap was not created by the client with
+<symbol>AllocAll</symbol>,
+the allocations to be moved are all those pixels and planes
+that have been allocated by the client using
+<function>XAllocColor</function>,
+<function>XAllocNamedColor</function>,
+<function>XAllocColorCells</function>,
+or
+<function>XAllocColorPlanes</function>
+and that have not been freed since they were allocated.
+</para>
+<para>
+<!-- .LP -->
+<function>XCopyColormapAndFree</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadColor</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy a colormap, use 
+<function>XFreeColormap</function>.
+<indexterm significance="preferred"><primary>XFreeColormap</primary></indexterm>
+</para>
+<!-- .sM -->
+<funcsynopsis id='xfreecolormap'>
+<funcprototype>
+  <funcdef><function>XFreeColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Cm that you want to destroy -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap (Cm.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeColormap</function>
+function deletes the association between the colormap resource ID 
+and the colormap and frees the colormap storage.
+However, this function has no effect on the default colormap for a screen.
+If the specified colormap is an installed map for a screen,
+it is uninstalled (see
+<function>XUninstallColormap</function>).
+If the specified colormap is defined as the colormap for a window (by
+<function>XCreateWindow</function>,
+<function>XSetWindowColormap</function>,
+or
+<function>XChangeWindowAttributes</function>),
+<function>XFreeColormap</function>
+changes the colormap associated with the window to
+<symbol>None</symbol>
+and generates a
+<symbol>ColormapNotify</symbol>
+event.
+X does not define the colors displayed for a window with a colormap of
+<symbol>None</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeColormap</function>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Mapping_Color_Names_to_Values">
+<title>Mapping Color Names to Values</title>
+<!-- .XS -->
+<!-- (SN Mapping Color Names to Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a color name to an <acronym>RGB</acronym> value, use
+<function>XLookupColor</function>.
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm significance="preferred"><primary>XLookupColor</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='xlookupcolor'>
+<funcprototype>
+  <funcdef>Status <function>XLookupColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>char<parameter> *color_name</parameter></paramdef>
+  <paramdef>XColor*exact_def_return,<parameter> *screen_def_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color name string (for example, red) whose color 
+definition structure you want returned.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>exact_def_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the exact <acronym>RGB</acronym> values.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_def_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the closest <acronym>RGB</acronym> values provided by the hardware.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLookupColor</function>
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns both the exact color values and
+the closest values provided by the screen 
+with respect to the visual type of the specified colormap.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+<function>XLookupColor</function>
+returns nonzero if the name is resolved;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XLookupColor</function>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a color name to the exact <acronym>RGB</acronym> value, use
+<function>XParseColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm significance="preferred"><primary>XParseColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xparsecolor'>
+<funcprototype>
+  <funcdef>Status <function>XParseColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>char<parameter> *spec</parameter></paramdef>
+  <paramdef>XColor<parameter> *exact_def_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>spec</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color name string;
+case is ignored.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>exact_def_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the exact color value for later use and sets the
+<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and
+<symbol>DoBlue</symbol>
+flags.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XParseColor</function>
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns the exact color value.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+<function>XParseColor</function>
+returns nonzero if the name is resolved;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XParseColor</function>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a color name to a value in an arbitrary color space, use
+<function>XcmsLookupColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsLookupColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmslookupcolor'>
+<funcprototype>
+  <funcdef>Status <function>XcmsLookupColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>char<parameter> *color_string</parameter></paramdef>
+  <paramdef>XcmsColor*color_exact_return,<parameter> *color_screen_return</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+<!-- .ds St -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color string(St.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_exact_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color specification parsed from the color string
+or parsed from the corresponding string found in a color-name database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_screen_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color that can be reproduced on the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>result_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color format for the returned color
+specifications (color_screen_return and color_exact_return arguments).
+If the format is
+<symbol>XcmsUndefinedFormat</symbol>
+and the color string contains a
+numerical color specification,
+the specification is returned in the format used in that numerical
+color specification.
+If the format is
+<symbol>XcmsUndefinedFormat</symbol>
+and the color string contains a color name,
+the specification is returned in the format used 
+to store the color in the database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsLookupColor</function>
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns both the exact color values and
+the closest values provided by the screen 
+with respect to the visual type of the specified colormap.
+The values are returned in the format specified by result_format.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+<function>XcmsLookupColor</function>
+returns
+<symbol>XcmsSuccess</symbol>
+or
+<symbol>XcmsSuccessWithCompression</symbol>
+if the name is resolved; otherwise, it returns
+<symbol>XcmsFailure</symbol>.
+If
+<symbol>XcmsSuccessWithCompression</symbol>
+is returned, the color specification returned in 
+color_screen_return is the result of gamut compression.
+</para>
+</sect1>
+
+<sect1 id="Allocating_and_Freeing_Color_Cells">
+<title>Allocating and Freeing Color Cells</title>
+<!-- .XS -->
+<!-- (SN Allocating and Freeing Color Cells -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+There are two ways of allocating color cells: 
+explicitly as read-only entries, one pixel value at a time,
+or read/write,
+where you can allocate a number of color cells and planes simultaneously.
+<indexterm><primary>Read-only colormap cells</primary></indexterm>
+A read-only cell has its <acronym>RGB</acronym> value set by the server.
+<indexterm><primary>Read/write colormap cells</primary></indexterm>
+Read/write cells do not have defined colors initially;
+functions described in the next section must be used to store values into them.
+Although it is possible for any client to store values into a read/write
+cell allocated by another client,
+read/write cells normally should be considered private to the client
+that allocated them.
+</para>
+<para>
+<!-- .LP -->
+Read-only colormap cells are shared among clients.
+The server counts each allocation and freeing of the cell by clients.
+When the last client frees a shared cell, the cell is finally deallocated.
+If a single client allocates the same read-only cell multiple
+times, the server counts each such allocation, not just the first one.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a read-only color cell with an <acronym>RGB</acronym> value, use
+<function>XAllocColor</function>.
+</para>
+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XAllocColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xalloccolor'>
+<funcprototype>
+  <funcdef>Status <function>XAllocColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XColor<parameter> *screen_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies and returns the values actually used in the colormap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocColor</function>
+function allocates a read-only colormap entry corresponding to the closest
+<acronym>RGB</acronym> value supported by the hardware.
+<function>XAllocColor</function>
+returns the pixel value of the color closest to the specified
+<acronym>RGB</acronym> elements supported by the hardware
+and returns the <acronym>RGB</acronym> value actually used.
+The corresponding colormap cell is read-only.
+In addition,
+<function>XAllocColor</function>
+returns nonzero if it succeeded or zero if it failed.
+<indexterm><primary>Color map</primary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm><primary>Allocation</primary><secondary>colormap</secondary></indexterm>
+<indexterm><primary>read-only colormap cells</primary></indexterm>
+Multiple clients that request the same effective <acronym>RGB</acronym> value can be assigned
+the same read-only entry, thus allowing entries to be shared.
+When the last client deallocates a shared cell, it is deallocated.
+<function>XAllocColor</function>
+does not use or affect the flags in the
+<structname>XColor</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllocColor</function>
+can generate a
+<errorname>BadColor</errorname>
+error.
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a read-only color cell with a color in arbitrary format, use
+<function>XcmsAllocColor</function>.
+</para>
+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsAllocColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsalloccolor'>
+<funcprototype>
+  <funcdef>Status <function>XcmsAllocColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_in_out</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color to allocate and returns the pixel and color 
+that is actually used in the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>result_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color format for the returned color specification.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsAllocColor</function>
+function is similar to
+<function>XAllocColor</function>
+except the color can be specified in any format.
+The
+<function>XcmsAllocColor</function>
+function ultimately calls 
+<function>XAllocColor</function>
+to allocate a read-only color cell (colormap entry) with the specified color.
+<function>XcmsAllocColor</function>
+first converts the color specified
+to an <acronym>RGB</acronym> value and then passes this to
+<function>XAllocColor</function>.
+<function>XcmsAllocColor</function>
+returns the pixel value of the color cell and the color specification
+actually allocated.
+This returned color specification is the result of converting the <acronym>RGB</acronym> value
+returned by 
+<function>XAllocColor</function>
+into the format specified with the result_format argument.
+If there is no interest in a returned color specification, 
+unnecessary computation can be bypassed if result_format is set to
+<symbol>XcmsRGBFormat</symbol>.
+The corresponding colormap cell is read-only.
+If this routine returns 
+<symbol>XcmsFailure</symbol>,
+the color_in_out color specification is left unchanged.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsAllocColor</function>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a read-only color cell using a color name and return the closest
+color supported by the hardware in <acronym>RGB</acronym> format, use
+<function>XAllocNamedColor</function>.
+</para>
+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XAllocNamedColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xallocnamedcolor'>
+<funcprototype>
+  <funcdef>Status <function>XAllocNamedColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>char<parameter> *color_name</parameter></paramdef>
+  <paramdef>XColor*screen_def_return,<parameter> *exact_def_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color name string (for example, red) whose color 
+definition structure you want returned.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_def_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the closest <acronym>RGB</acronym> values provided by the hardware.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>exact_def_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the exact <acronym>RGB</acronym> values.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XAllocNamedColor</function>
+function looks up the named color with respect to the screen that is
+associated with the specified colormap.
+It returns both the exact database definition and
+the closest color supported by the screen.
+The allocated color cell is read-only.
+The pixel value is returned in screen_def_return.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+If screen_def_return and exact_def_return
+point to the same structure, the pixel field will be set correctly,
+but the color values are undefined.
+<function>XAllocNamedColor</function>
+returns nonzero if a cell is allocated;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllocNamedColor</function>
+can generate a
+<errorname>BadColor</errorname>
+error. 
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a read-only color cell using a color name and return the closest
+color supported by the hardware in an arbitrary format, use
+<function>XcmsAllocNamedColor</function>.
+</para>
+<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
+<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsAllocNamedColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsallocnamedcolor'>
+<funcprototype>
+  <funcdef>Status <function>XcmsAllocNamedColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>char<parameter> *color_string</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_screen_return</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_exact_return</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+<!-- .ds St \ whose color definition structure is to be returned -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color string(St.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_screen_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the pixel value of the color cell and color specification 
+that actually is stored for that cell.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_exact_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color specification parsed from the color string
+or parsed from the corresponding string found in a color-name database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>result_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color format for the returned color
+specifications (color_screen_return and color_exact_return arguments).
+If the format is
+<symbol>XcmsUndefinedFormat</symbol>
+and the color string contains a
+numerical color specification,
+the specification is returned in the format used in that numerical
+color specification.
+If the format is
+<symbol>XcmsUndefinedFormat</symbol>
+and the color string contains a color name,
+the specification is returned in the format used 
+to store the color in the database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsAllocNamedColor</function>
+function is similar to
+<function>XAllocNamedColor</function>
+except that the color returned can be in any format specified.
+This function
+ultimately calls
+<function>XAllocColor</function>
+to allocate a read-only color cell with
+the color specified by a color string.
+The color string is parsed into an
+<structname>XcmsColor</structname>
+structure (see
+<function>XcmsLookupColor</function>),
+converted
+to an <acronym>RGB</acronym> value, and finally passed to
+<function>XAllocColor</function>.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+</para>
+<para>
+<!-- .LP -->
+This function returns both the color specification as a result
+of parsing (exact specification) and the actual color specification
+stored (screen specification).
+This screen specification is the result of converting the <acronym>RGB</acronym> value
+returned by
+<function>XAllocColor</function>
+into the format specified in result_format.
+If there is no interest in a returned color specification,
+unnecessary computation can be bypassed if result_format is set to
+<symbol>XcmsRGBFormat</symbol>.
+If color_screen_return and color_exact_return
+point to the same structure, the pixel field will be set correctly,
+but the color values are undefined.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsAllocNamedColor</function>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate read/write color cell and color plane combinations for a
+<symbol>PseudoColor</symbol>
+model, use
+<function>XAllocColorCells</function>.
+</para>
+<indexterm><primary>Read/write colormap cells</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Allocation</primary><secondary>read/write colormap cells</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XAllocColorCells</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xalloccolorcells'>
+<funcprototype>
+  <funcdef>Status <function>XAllocColorCells</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>Bool<parameter> contig</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> plane_masks_return[]</parameter></paramdef>
+  <paramdef>unsignedint<parameter> nplanes</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>
+  <paramdef>unsignedint<parameter> npixels</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>contig</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether the planes must be contiguous.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>plane_mask_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of plane masks.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nplanes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of plane masks that are to be returned in the plane masks 
+array. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pixels_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of pixel values. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>npixels</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of pixel values that are to be returned in the 
+pixels_return array. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocColorCells</function>
+function allocates read/write color cells.
+The number of colors must be positive and the number of planes nonnegative,
+or a
+<errorname>BadValue</errorname>
+error results.
+If ncolors and nplanes are requested, 
+then ncolors pixels
+and nplane plane masks are returned.
+No mask will have any bits set to 1 in common with
+any other mask or with any of the pixels.
+By ORing together each pixel with zero or more masks,
+ncolors &times; 2<superscript><emphasis>nplanes</emphasis></superscript>
+distinct pixels can be produced.
+All of these are
+allocated writable by the request.
+For 
+<symbol>GrayScale</symbol>
+or 
+<symbol>PseudoColor</symbol>,
+each mask has exactly one bit set to 1. 
+For 
+<symbol>DirectColor</symbol>,
+each has exactly three bits set to 1.
+If contig is 
+<symbol>True</symbol>
+and if all masks are ORed
+together, a single contiguous set of bits set to 1 will be formed for 
+<symbol>GrayScale</symbol>
+or 
+<symbol>PseudoColor</symbol>
+and three contiguous sets of bits set to 1 (one within each
+pixel subfield) for 
+<symbol>DirectColor</symbol>.
+The <acronym>RGB</acronym> values of the allocated
+entries are undefined.
+<function>XAllocColorCells</function>
+returns nonzero if it succeeded or zero if it failed.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllocColorCells</function>
+can generate
+<errorname>BadColor</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate read/write color resources for a
+<symbol>DirectColor</symbol>
+model, use
+<function>XAllocColorPlanes</function>.
+</para>
+<indexterm><primary>Read/write colormap planes</primary><secondary>allocating</secondary></indexterm>
+<indexterm><primary>Allocation</primary><secondary>read/write colormap planes</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
+<indexterm significance="preferred"><primary>XAllocColorPlanes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xalloccolorplanes'>
+<funcprototype>
+  <funcdef>Status <function>XAllocColorPlanes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>Bool<parameter> contig</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>
+  <paramdef>int<parameter> ncolors</parameter></paramdef>
+  <paramdef>intnreds,ngreens,<parameter> nblues</parameter></paramdef>
+  <paramdef>unsignedlong*rmask_return,*gmask_return,<parameter> *bmask_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>contig</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether the planes must be contiguous.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pixels_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of pixel values. 
+<function>XAllocColorPlanes</function>
+returns the pixel values in this array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of pixel values that are to be returned in the 
+pixels_return array. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nreds</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ngreens</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nblues</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+Specify the number of red, green, and blue planes.
+The value you pass must be nonnegative. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rmask_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gmask_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bmask_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return bit masks for the red, green, and blue planes.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The specified ncolors must be positive; 
+and nreds, ngreens, and nblues must be nonnegative,
+or a
+<errorname>BadValue</errorname>
+error results.
+If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, 
+ncolors pixels are returned; and the masks have nreds, ngreens, and 
+nblues bits set to 1, respectively.
+If contig is 
+<symbol>True</symbol>,
+each mask will have
+a contiguous set of bits set to 1.
+No mask will have any bits set to 1 in common with
+any other mask or with any of the pixels.
+For 
+<symbol>DirectColor</symbol>,
+each mask
+will lie within the corresponding pixel subfield.
+By ORing together
+subsets of masks with each pixel value, 
+ncolors &times; 2<superscript><emphasis>(nreds+ngreens+nblues)</emphasis></superscript>
+distinct pixel values can be produced.
+All of these are allocated by the request.
+However, in the
+colormap, there are only
+ncolors &times; 2<superscript><emphasis>nreds</emphasis></superscript>
+independent red entries,
+ncolors &times; 2<superscript><emphasis>ngreens</emphasis></superscript>
+independent green entries, and
+ncolors &times; 2<superscript><emphasis>nblues</emphasis></superscript>
+independent blue entries.
+This is true even for 
+<symbol>PseudoColor</symbol>.
+When the colormap entry of a pixel
+value is changed (using 
+<function>XStoreColors</function>,
+<function>XStoreColor</function>,
+or 
+<function>XStoreNamedColor</function>),
+the pixel is decomposed according to the masks, 
+and the corresponding independent entries are updated.
+<function>XAllocColorPlanes</function>
+returns nonzero if it succeeded or zero if it failed.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllocColorPlanes</function>
+can generate
+<errorname>BadColor</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm><primary>Freeing</primary><secondary>colors</secondary></indexterm>
+To free colormap cells, use
+<function>XFreeColors</function>.
+<indexterm significance="preferred"><primary>XFreeColors</primary></indexterm>
+<indexterm><primary>Color</primary><secondary>deallocation</secondary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='xfreecolors'>
+<funcprototype>
+  <funcdef><function>XFreeColors</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> pixels[]</parameter></paramdef>
+  <paramdef>int<parameter> npixels</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> planes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+<!-- .ds Pi that map to the cells in the specified colormap -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pixels</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of pixel values (Pi. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>npixels</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of pixels. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>planes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the planes you want to free.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeColors</function>
+function frees the cells represented by pixels whose values are in the
+pixels array.
+The planes argument should not have any bits set to 1 in common with any of the
+pixels. 
+The set of all pixels is produced by ORing together subsets of
+the planes argument with the pixels.
+The request frees all of these pixels that
+were allocated by the client (using 
+<indexterm><primary>XAllocColor</primary></indexterm>
+<indexterm><primary>XAllocNamedColor</primary></indexterm>
+<indexterm><primary>XAllocColorCells</primary></indexterm>
+<indexterm><primary>XAllocColorPlanes</primary></indexterm>
+<function>XAllocColor</function>,
+<function>XAllocNamedColor</function>,
+<function>XAllocColorCells</function>,
+and 
+<function>XAllocColorPlanes</function>).
+Note that freeing an
+individual pixel obtained from 
+<function>XAllocColorPlanes</function>
+may not actually allow
+it to be reused until all of its related pixels are also freed.
+Similarly,
+a read-only entry is not actually freed until it has been freed by all clients,
+and if a client allocates the same read-only entry multiple times,
+it must free the entry that many times before the entry is actually freed.
+</para>
+<para>
+<!-- .LP -->
+All specified pixels that are allocated by the client in the colormap are
+freed, even if one or more pixels produce an error. 
+If a specified pixel is not a valid index into the colormap, a 
+<errorname>BadValue</errorname>
+error results.
+If a specified pixel is not allocated by the
+client (that is, is unallocated or is only allocated by another client)
+or if the colormap was created with all entries writable (by passing
+<symbol>AllocAll</symbol>
+to
+<function>XCreateColormap</function>),
+a
+<errorname>BadAccess</errorname>
+error results. 
+If more than one pixel is in error, 
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeColors</function>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadColor</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Modifying_and_Querying_Colormap_Cells">
+<title>Modifying and Querying Colormap Cells</title>
+<!-- .XS -->
+<!-- (SN Modifying and Querying Colormap Cells  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store an <acronym>RGB</acronym> value in a single colormap cell, use
+<function>XStoreColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xstorecolor'>
+<funcprototype>
+  <funcdef><function>XStoreColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XColor<parameter> *color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the pixel and <acronym>RGB</acronym> values.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStoreColor</function>
+function changes the colormap entry of the pixel value specified in the
+pixel member of the
+<structname>XColor</structname>
+structure.
+You specified this value in the
+pixel member of the
+<structname>XColor</structname>
+structure.
+This pixel value must be a read/write cell and a valid index into the colormap.
+If a specified pixel is not a valid index into the colormap,
+a
+<errorname>BadValue</errorname>
+error results.
+<function>XStoreColor</function>
+also changes the red, green, and/or blue color components.
+You specify which color components are to be changed by setting
+<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and/or
+<symbol>DoBlue</symbol>
+in the flags member of the
+<structname>XColor</structname>
+structure.
+If the colormap is an installed map for its screen, 
+the changes are visible immediately.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreColor</function>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadColor</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store multiple <acronym>RGB</acronym> values in multiple colormap cells, use
+<function>XStoreColors</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xstorecolors'>
+<funcprototype>
+  <funcdef><function>XStoreColors</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XColor<parameter> color[]</parameter></paramdef>
+  <paramdef>int<parameter> ncolors</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of color definition structures to be stored.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .\"Specifies the number of color definition structures.  -->
+Specifies the number of 
+<structname>XColor</structname>
+structures in the color definition array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStoreColors</function>
+function changes the colormap entries of the pixel values
+specified in the pixel members of the
+<structname>XColor</structname>
+structures.
+You specify which color components are to be changed by setting 
+<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and/or
+<symbol>DoBlue</symbol>
+in the flags member of the
+<structname>XColor</structname>
+structures.
+If the colormap is an installed map for its screen, the
+changes are visible immediately.
+<function>XStoreColors</function>
+changes the specified pixels if they are allocated writable in the colormap 
+by any client, even if one or more pixels generates an error.
+If a specified pixel is not a valid index into the colormap, a
+<errorname>BadValue</errorname>
+error results.
+If a specified pixel either is unallocated or is allocated read-only, a
+<errorname>BadAccess</errorname>
+error results.
+If more than one pixel is in error, 
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreColors</function>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadColor</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store a color of arbitrary format in a single colormap cell, use
+<function>XcmsStoreColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsStoreColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsstorecolor'>
+<funcprototype>
+  <funcdef>Status <function>XcmsStoreColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color cell and the color to store.
+Values specified in this
+<structname>XcmsColor</structname>
+structure remain unchanged on return.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsStoreColor</function>
+function converts the color specified in the
+<structname>XcmsColor</structname>
+structure into <acronym>RGB</acronym> values.
+It then uses this <acronym>RGB</acronym> specification in an
+<structname>XColor</structname>
+structure, whose three flags 
+(<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and
+<symbol>DoBlue</symbol>)
+are set, in a call to
+<function>XStoreColor</function>
+to change the color cell specified by the pixel member of the
+<structname>XcmsColor</structname>
+structure.
+This pixel value must be a valid index for the specified colormap,
+and the color cell specified by the pixel value must be a read/write cell.
+If the pixel value is not a valid index, a
+<errorname>BadValue</errorname>
+error results.
+If the color cell is unallocated or is allocated read-only, a
+<errorname>BadAccess</errorname>
+error results.
+If the colormap is an installed map for its screen, 
+the changes are visible immediately.
+</para>
+<para>
+<!-- .LP -->
+Note that 
+<function>XStoreColor</function>
+has no return value; therefore, an
+<symbol>XcmsSuccess</symbol>
+return value from this function indicates that the conversion 
+to <acronym>RGB</acronym> succeeded and the call to
+<function>XStoreColor</function>
+was made.
+To obtain the actual color stored, use
+<function>XcmsQueryColor</function>.
+Because of the screen's hardware limitations or gamut compression,
+the color stored in the colormap may not be identical
+to the color specified.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsStoreColor</function>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadColor</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store multiple colors of arbitrary format in multiple colormap cells, use
+<function>XcmsStoreColors</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsStoreColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsstorecolors'>
+<funcprototype>
+  <funcdef>Status <function>XcmsStoreColors</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> colors[]</parameter></paramdef>
+  <paramdef>int<parameter> ncolors</parameter></paramdef>
+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color specification array of
+<structname>XcmsColor</structname>
+structures, each specifying a color cell and the color to store in that
+cell.
+Values specified in the array remain unchanged upon return.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of 
+<structname>XcmsColor</structname>
+structures in the color-specification array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>compression_flags_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of Boolean values indicating compression status.
+If a non-NULL pointer is supplied,
+each element of the array is set to
+<symbol>True</symbol>
+if the corresponding color was compressed and
+<symbol>False</symbol>
+otherwise.
+Pass NULL if the compression status is not useful.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsStoreColors</function>
+function converts the colors specified in the array of
+<structname>XcmsColor</structname>
+structures into <acronym>RGB</acronym> values and then uses these <acronym>RGB</acronym> specifications in
+<structname>XColor</structname>
+structures, whose three flags 
+(<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and
+<symbol>DoBlue</symbol>)
+are set, in a call to
+<function>XStoreColors</function>
+to change the color cells specified by the pixel member of the corresponding
+<structname>XcmsColor</structname>
+structure.
+Each pixel value must be a valid index for the specified colormap,
+and the color cell specified by each pixel value must be a read/write cell.
+If a pixel value is not a valid index, a
+<errorname>BadValue</errorname>
+error results.
+If a color cell is unallocated or is allocated read-only, a
+<errorname>BadAccess</errorname>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+If the colormap is an installed map for its screen, 
+the changes are visible immediately.
+</para>
+<para>
+<!-- .LP -->
+Note that 
+<function>XStoreColors</function>
+has no return value; therefore, an
+<symbol>XcmsSuccess</symbol>
+return value from this function indicates that conversions 
+to <acronym>RGB</acronym> succeeded and the call to
+<function>XStoreColors</function>
+was made.
+To obtain the actual colors stored, use
+<function>XcmsQueryColors</function>.
+Because of the screen's hardware limitations or gamut compression,
+the colors stored in the colormap may not be identical
+to the colors specified.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsStoreColors</function>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadColor</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store a color specified by name in a single colormap cell, use
+<function>XStoreNamedColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
+<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreNamedColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xstorenamedcolor'>
+<funcprototype>
+  <funcdef><function>XStoreNamedColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>char<parameter> *color</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> pixel</parameter></paramdef>
+  <paramdef>int<parameter> flags</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color name string (for example, red). 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pixel</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the entry in the colormap. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>flags</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which red, green, and blue components are set.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XStoreNamedColor</function>
+function looks up the named color with respect to the screen associated with
+the colormap and stores the result in the specified colormap.
+The pixel argument determines the entry in the colormap.
+The flags argument determines which of the red, green, and blue components 
+are set. 
+You can set this member to the
+bitwise inclusive OR of the bits 
+<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and 
+<symbol>DoBlue</symbol>.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+If the specified pixel is not a valid index into the colormap, a
+<errorname>BadValue</errorname>
+error results.
+If the specified pixel either is unallocated or is allocated read-only, a
+<errorname>BadAccess</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreNamedColor</function>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadColor</errorname>,
+<errorname>BadName</errorname>,
+and 
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XQueryColor</function>
+and
+<function>XQueryColors</function>
+functions take pixel values in the pixel member of
+<structname>XColor</structname>
+structures and store in the structures the <acronym>RGB</acronym> values for those
+pixels from the specified colormap.
+The values returned for an unallocated entry are undefined.
+These functions also set the flags member in the
+<structname>XColor</structname>
+structure to all three colors.
+If a pixel is not a valid index into the specified colormap, a
+<errorname>BadValue</errorname>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To query the <acronym>RGB</acronym> value of a single colormap cell, use
+<function>XQueryColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
+<indexterm significance="preferred"><primary>XQueryColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerycolor'>
+<funcprototype>
+  <funcdef><function>XQueryColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XColor<parameter> *def_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>def_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies and returns the <acronym>RGB</acronym> values for the pixel specified in the structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryColor</function>
+function returns the current <acronym>RGB</acronym> value for the pixel in the
+<structname>XColor</structname>
+structure and sets the
+<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and
+<symbol>DoBlue</symbol>
+flags.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryColor</function>
+can generate
+<errorname>BadColor</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To query the <acronym>RGB</acronym> values of multiple colormap cells, use
+<function>XQueryColors</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
+<indexterm significance="preferred"><primary>XQueryColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerycolors'>
+<funcprototype>
+  <funcdef><function>XQueryColors</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XColor<parameter> defs_in_out[]</parameter></paramdef>
+  <paramdef>int<parameter> ncolors</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>defs_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies and returns an array of color definition structures for the pixel
+specified in the structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .\"Specifies the number of color definition structures.  -->
+Specifies the number of 
+<structname>XColor</structname>
+structures in the color definition array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryColors</function>
+function returns the <acronym>RGB</acronym> value for each pixel in each
+<structname>XColor</structname>
+structure and sets the
+<symbol>DoRed</symbol>,
+<symbol>DoGreen</symbol>,
+and
+<symbol>DoBlue</symbol>
+flags in each structure.
+
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryColors</function>
+can generate
+<errorname>BadColor</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To query the color of a single colormap cell in an arbitrary format, use
+<function>XcmsQueryColor</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsQueryColor</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsquerycolor'>
+<funcprototype>
+  <funcdef>Status <function>XcmsQueryColor</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_in_out</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the pixel member that indicates the color cell to query.
+The color specification stored for the color cell is returned in this
+<structname>XcmsColor</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>result_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color format for the returned color specification.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryColor</function>
+function obtains the <acronym>RGB</acronym> value
+for the pixel value in the pixel member of the specified
+<structname>XcmsColor</structname>
+structure and then
+converts the value to the target format as
+specified by the result_format argument.
+If the pixel is not a valid index in the specified colormap, a
+<errorname>BadValue</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsQueryColor</function>
+can generate
+<errorname>BadColor</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To query the color of multiple colormap cells in an arbitrary format, use
+<function>XcmsQueryColors</function>.
+</para>
+<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsQueryColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsquerycolors'>
+<funcprototype>
+  <funcdef>Status <function>XcmsQueryColors</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> result_format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colors_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of
+<structname>XcmsColor</structname>
+structures, each pixel member indicating the color cell to query.
+The color specifications for the color cells are returned in these structures.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of 
+<structname>XcmsColor</structname>
+structures in the color-specification array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>result_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color format for the returned color specification.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsQueryColors</function>
+function obtains the <acronym>RGB</acronym> values
+for pixel values in the pixel members of
+<structname>XcmsColor</structname>
+structures and then
+converts the values to the target format as
+specified by the result_format argument.
+If a pixel is not a valid index into the specified colormap, a
+<errorname>BadValue</errorname>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<function>XcmsQueryColors</function>
+can generate
+<errorname>BadColor</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Color_Conversion_Context_Functions">
+<title>Color Conversion Context Functions</title>
+<!-- .XS -->
+<!-- (SN Color Conversion Context Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section describes functions to create, modify,
+and query Color Conversion Contexts (CCCs).
+</para>
+<para>
+<!-- .LP -->
+Associated with each colormap is an initial CCC transparently generated by
+Xlib.
+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
+Therefore, when you specify a colormap as an argument to a function,
+you are indirectly specifying a CCC.
+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
+The CCC attributes that can be modified by the X client are:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Client White Point
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Gamut compression procedure and client data
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+White point adjustment procedure and client data
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The initial values for these attributes are implementation specific.
+The CCC attributes for subsequently created CCCs can be defined
+by changing the CCC attributes of the default CCC.
+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
+There is a default CCC associated with each screen.
+</para>
+<sect2 id="Getting_and_Setting_the_Color_Conversion_Context_of_a_Colormap">
+<title>Getting and Setting the Color Conversion Context of a Colormap</title>
+<!-- .XS -->
+<!-- (SN Getting and Setting the Color Conversion Context of a Colormap -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the CCC associated with a colormap, use
+<function>XcmsCCCOfColormap</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCCCOfColormap</primary></indexterm>
+<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscccofcolormap'>
+<funcprototype>
+  <funcdef>XcmsCCC <function>XcmsCCCOfColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCCCOfColormap</function>
+function returns the CCC associated with the specified colormap.
+Once obtained, 
+the CCC attributes can be queried or modified.
+Unless the CCC associated with the specified colormap is changed with
+<function>XcmsSetCCCOfColormap</function>,
+this CCC is used when the specified colormap is used as an argument 
+to color functions.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To change the CCC associated with a colormap, use
+<function>XcmsSetCCCOfColormap</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsSetCCCOfColormap</primary></indexterm>
+<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmssetcccofcolormap'>
+<funcprototype>
+  <funcdef>XcmsCCC <function>XcmsSetCCCOfColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsSetCCCOfColormap</function>
+function changes the CCC associated with the specified colormap.
+It returns the CCC previously associated with the colormap.
+If they are not used again in the application,
+CCCs should be freed by calling
+<function>XcmsFreeCCC</function>.
+Several colormaps may share the same CCC without restriction; this
+includes the CCCs generated by Xlib with each colormap.  Xlib, however,
+creates a new CCC with each new colormap.
+</para>
+</sect2>
+<sect2 id="Obtaining_the_Default_Color_Conversion_Context">
+<title>Obtaining the Default Color Conversion Context</title>
+<!-- .XS -->
+<!-- (SN Obtaining the Default Color Conversion Context -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You can change the default CCC attributes for subsequently created CCCs
+by changing the CCC attributes of the default CCC.
+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
+A default CCC is associated with each screen.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the default CCC for a screen, use
+<function>XcmsDefaultCCC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsDefaultCCC</primary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsdefaultccc'>
+<funcprototype>
+  <funcdef>XcmsCCC <function>XcmsDefaultCCC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the appropriate screen number on the host server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsDefaultCCC</function>
+function returns the default CCC for the specified screen.
+Its visual is the default visual of the screen.
+Its initial gamut compression and white point
+adjustment procedures as well as the associated client data are implementation
+specific.
+</para>
+</sect2>
+<sect2 id="Color_Conversion_Context_Macros">
+<title>Color Conversion Context Macros</title>
+<!-- .XS -->
+<!-- (SN Color Conversion Context Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications should not directly modify any part of the
+<structname>XcmsCCC</structname>.
+The following lists the C language macros, their corresponding function
+equivalents for other language bindings, and what data they both
+can return.
+<!-- .sp -->
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>DisplayOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsDisplayOfCCC</primary></indexterm>
+<!-- .sM -->
+
+<funcsynopsis id='displayofccc'>
+<funcprototype>
+  <funcdef><function>DisplayOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis id='xcmsdisplayofccc'>
+<funcprototype>
+  <funcdef>Display *<function>XcmsDisplayOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the display associated with the specified CCC.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>VisualOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsVisualOfCCC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='visualofccc'>
+<funcprototype>
+  <funcdef><function>VisualOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis id='xcmsvisualofccc'>
+<funcprototype>
+  <funcdef>Visual *<function>XcmsVisualOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the visual associated with the specified CCC.
+<!-- .sp -->
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>ScreenNumberOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsScreenNumberOfCCC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='screennumberofccc'>
+<funcprototype>
+  <funcdef><function>ScreenNumberOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis id='xcmsscreennumberofccc'>
+<funcprototype>
+  <funcdef>int <function>XcmsScreenNumberOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the number of the screen associated with the specified CCC.
+<!-- .sp -->
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>ScreenWhitePointOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsScreenWhitePointOfCCC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='screenwhitepointofccc'>
+<funcprototype>
+  <funcdef><function>ScreenWhitePointOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='xcmsscreenwhitepointofccc'>
+<funcprototype>
+  <funcdef>XcmsColor <function>XcmsScreenWhitePointOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the white point of the screen associated with the specified CCC.
+<!-- .sp -->
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>ClientWhitePointOfCCC</primary></indexterm>
+<indexterm significance="preferred"><primary>XcmsClientWhitePointOfCCC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='clientwhitepointofccc'>
+<funcprototype>
+  <funcdef> <function>ClientWhitePointOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis id='xcmsclientwhitepointofccc'>
+<funcprototype>
+  <funcdef>XcmsColor *<function>XcmsClientWhitePointOfCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both return the Client White Point of the specified CCC.
+</para>
+</sect2>
+
+<sect2 id="Modifying_Attributes_of_a_Color_Conversion_Context">
+<title>Modifying Attributes of a Color Conversion Context</title>
+<!-- .XS -->
+<!-- (SN Modifying Attributes of a Color Conversion Context -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the Client White Point in the CCC, use
+<function>XcmsSetWhitePoint</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsSetWhitePoint</primary></indexterm>
+<indexterm><primary>Client White Point</primary><secondary>of Color Conversion Context</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmssetwhitepoint'>
+<funcprototype>
+  <funcdef>Status <function>XcmsSetWhitePoint</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+<!-- .ds Co new Client White Point -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the new Client White Point.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsSetWhitePoint</function>
+function changes the Client White Point in the specified CCC.
+Note that the pixel member is ignored 
+and that the color specification is left unchanged upon return.
+The format for the new white point must be
+<symbol>XcmsCIEXYZFormat</symbol>,
+<symbol>XcmsCIEuvYFormat</symbol>,
+<symbol>XcmsCIExyYFormat</symbol>,
+or
+<symbol>XcmsUndefinedFormat</symbol>.
+If the color argument is NULL, this function sets the format component of the
+Client White Point specification to
+<symbol>XcmsUndefinedFormat</symbol>,
+indicating that the Client White Point is assumed to be the same as the
+Screen White Point.
+</para>
+<para>
+<!-- .LP -->
+This function returns nonzero status
+if the format for the new white point is valid;
+otherwise, it returns zero.
+
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the gamut compression procedure and corresponding client data
+in a specified CCC, use
+<function>XcmsSetCompressionProc</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsSetCompressionProc</primary></indexterm>
+<indexterm><primary>Gamut compression</primary><secondary>setting in Color Conversion Context</secondary></indexterm>
+<indexterm><primary>Gamut compression</primary><secondary>procedure</secondary></indexterm>
+<indexterm><primary>Gamut compression</primary><secondary>client data</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmssetcompressionproc'>
+<funcprototype>
+  <funcdef>XcmsCompressionProc <function>XcmsSetCompressionProc</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsCompressionProc<parameter> compression_proc</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>compression_proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the gamut compression procedure that is to be applied 
+when a color lies outside the screen's color gamut.
+If NULL is specified and a function using this CCC must convert
+a color specification to a device-dependent format and encounters a color
+that lies outside the screen's color gamut, 
+that function will return
+<symbol>XcmsFailure</symbol>.
+<!-- .ds Cd the gamut compression procedure -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies client data for gamut compression procedure or NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsSetCompressionProc</function>
+function first sets the gamut compression procedure and client data 
+in the specified CCC with the newly specified procedure and client data
+and then returns the old procedure.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the white point adjustment procedure and corresponding client data
+in a specified CCC, use
+<function>XcmsSetWhiteAdjustProc</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsSetWhiteAdjustProc</primary></indexterm>
+<indexterm><primary>White point adjustment</primary><secondary>setting in Color Conversion Context</secondary></indexterm>
+<indexterm><primary>White point adjustment</primary><secondary>procedure</secondary></indexterm>
+<indexterm><primary>White point adjustment</primary><secondary>client data</secondary></indexterm>
+<funcsynopsis id='xcmssetwhiteadjustproc'>
+<funcprototype>
+  <funcdef>XcmsWhiteAdjustProc <function>XcmsSetWhiteAdjustProc</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsWhiteAdjustProc<parameter> white_adjust_proc</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>white_adjust_proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the white point adjustment procedure.
+<!-- .ds Cd the white point adjustment procedure -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies client data for white point adjustment procedure or NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsSetWhiteAdjustProc</function>
+function first sets the white point adjustment procedure and client data 
+in the specified CCC with the newly specified procedure and client data
+and then returns the old procedure.
+</para>
+</sect2>
+<sect2 id="Creating_and_Freeing_a_Color_Conversion_Context">
+<title>Creating and Freeing a Color Conversion Context</title>
+<!-- .XS -->
+<!-- (SN Creating and Freeing a Color Conversion Context -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You can explicitly create a CCC within your application by calling
+<function>XcmsCreateCCC</function>.
+These created CCCs can then be used by those functions that explicitly
+call for a CCC argument.
+Old CCCs that will not be used by the application should be freed using
+<function>XcmsFreeCCC</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To create a CCC, use
+<function>XcmsCreateCCC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCreateCCC</primary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>creation</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscreateccc'>
+<funcprototype>
+  <funcdef>XcmsCCC <function>XcmsCreateCCC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> screen_number</parameter></paramdef>
+  <paramdef>Visual<parameter> *visual</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *client_white_point</parameter></paramdef>
+  <paramdef>XcmsCompressionProc<parameter> compression_proc</parameter></paramdef>
+  <paramdef>XPointer<parameter> compression_client_data</parameter></paramdef>
+  <paramdef>XcmsWhiteAdjustProc<parameter> white_adjust_proc</parameter></paramdef>
+  <paramdef>XPointer<parameter> white_adjust_client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the appropriate screen number on the host server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>visual</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the visual type.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_white_point</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the Client White Point.
+If NULL is specified, 
+the Client White Point is to be assumed to be the same as the
+Screen White Point.
+Note that the pixel member is ignored.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>compression_proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the gamut compression procedure that is to be applied 
+when a color lies outside the screen's color gamut.
+If NULL is specified and a function using this CCC must convert
+a color specification to a device-dependent format and encounters a color
+that lies outside the screen's color gamut, 
+that function will return
+<symbol>XcmsFailure</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>compression_client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies client data for use by the gamut compression procedure or NULL.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>white_adjust_proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the white adjustment procedure that is to be applied
+when the Client White Point differs from the Screen White Point.
+NULL indicates that no white point adjustment is desired.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>white_adjust_client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies client data for use with the white point adjustment procedure or NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCreateCCC</function>
+function creates a CCC for the specified display, screen, and visual.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free a CCC, use
+<function>XcmsFreeCCC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsFreeCCC</primary></indexterm>
+<indexterm><primary>Color Conversion Context</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>CCC</primary><secondary>freeing</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsfreeccc'>
+<funcprototype>
+  <funcdef>void <function>XcmsFreeCCC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsFreeCCC</function>
+function frees the memory used for the specified CCC.
+Note that default CCCs and those currently associated with colormaps
+are ignored.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Converting_between_Color_Spaces">
+<title>Converting between Color Spaces</title>
+<!-- .XS -->
+<!-- (SN Converting between Color Spaces -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert an array of color specifications in arbitrary color formats
+to a single destination format, use
+<function>XcmsConvertColors</function>.
+</para>
+<indexterm><primary>Color conversion</primary></indexterm>
+<indexterm><primary>Color</primary><secondary>conversion</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsConvertColors</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsconvertcolors'>
+<funcprototype>
+  <funcdef>Status <function>XcmsConvertColors</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+If conversion is between device-independent color spaces only
+(for example, TekHVC to CIELuv),
+the CCC is necessary only to specify the Client White Point.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colors_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of color specifications.
+Pixel members are ignored and remain unchanged upon return.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of 
+<structname>XcmsColor</structname>
+structures in the color-specification array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target color specification format.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>compression_flags_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of Boolean values indicating compression status.
+If a non-NULL pointer is supplied,
+each element of the array is set to
+<symbol>True</symbol>
+if the corresponding color was compressed and
+<symbol>False</symbol>
+otherwise.
+Pass NULL if the compression status is not useful.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsConvertColors</function>
+function converts the color specifications in the specified array of
+<structname>XcmsColor</structname>
+structures from their current format to a single target format,
+using the specified CCC.
+When the return value is
+<symbol>XcmsFailure</symbol>,
+the contents of the color specification array are left unchanged.
+</para>
+<para>
+<!-- .LP -->
+The array may contain a mixture of color specification formats
+(for example, 3 <acronym>CIE</acronym> XYZ, 2 <acronym>CIE</acronym> Luv, and so on).
+When the array contains both device-independent and
+device-dependent color specifications and the target_format argument specifies
+a device-dependent format (for example,
+<symbol>XcmsRGBiFormat</symbol>,
+<symbol>XcmsRGBFormat</symbol>),
+all specifications are converted to <acronym>CIE</acronym> XYZ format and then to the target
+device-dependent format.
+</para>
+</sect1>
+<sect1 id="Callback_Functions">
+<title>Callback Functions</title>
+<!-- .XS -->
+<!-- (SN Callback Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section describes the gamut compression and white point
+adjustment callbacks.
+</para>
+<para>
+<!-- .LP -->
+The gamut compression procedure specified in the CCC
+is called when an attempt to convert a color specification from
+<structname>XcmsCIEXYZ</structname>
+to a device-dependent format (typically
+<structname>XcmsRGBi</structname>)
+results in a color that lies outside the screen's color gamut.
+If the gamut compression procedure requires client data, this data is passed
+via the gamut compression client data in the CCC.
+</para>
+<para>
+<!-- .LP -->
+During color specification conversion between device-independent
+and device-dependent color spaces,
+if a white point adjustment procedure is specified in the CCC,
+it is triggered when the Client White Point and Screen White Point differ.
+If required, the client data is obtained from the CCC.
+</para>
+<sect2 id="Prototype_Gamut_Compression_Procedure">
+<title>Prototype Gamut Compression Procedure</title>
+<!-- .XS -->
+<!-- (SN Prototype Gamut Compression Procedure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The gamut compression callback interface must adhere to the
+following:
+</para>
+<indexterm significance="preferred"><primary>XcmsCompressionProc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscompressionproc'>
+<funcprototype>
+  <funcdef>typedef Status<function>(*XcmsCompressionProc</function>)</funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+  <paramdef>unsignedint<parameter> index</parameter></paramdef>
+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colors_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of 
+<structname>XcmsColor</structname>
+structures in the color-specification array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>index</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the index into the array of
+<structname>XcmsColor</structname>
+structures for the encountered color specification that lies outside the 
+screen's color gamut.
+Valid values are 0 (for the first element) to ncolors - 1.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>compression_flags_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+<symbol>True</symbol>
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When implementing a gamut compression procedure, consider the following
+rules and assumptions:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The gamut compression procedure can attempt to compress one or multiple
+specifications at a time.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+When called, elements 0 to index - 1 in the color specification
+array can be assumed to fall within the screen's color gamut.
+In addition, these color specifications are already in some device-dependent
+format (typically
+<structname>XcmsRGBi</structname>).
+If any modifications are made to these color specifications,
+they must be in their initial device-dependent format upon return.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+When called, the element in the color specification array specified
+by the index argument contains the color specification outside the 
+screen's color gamut encountered by the calling routine.
+In addition, this color specification can be assumed to be in
+<structname>XcmsCIEXYZ</structname>.
+Upon return, this color specification must be in
+<structname>XcmsCIEXYZ</structname>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+When called, elements from index to ncolors - 1 
+in the color specification array may or may not fall within the
+screen's color gamut.
+In addition, these color specifications can be assumed to be in
+<structname>XcmsCIEXYZ</structname>.
+If any modifications are made to these color specifications, 
+they must be in
+<structname>XcmsCIEXYZ</structname>
+upon return.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The color specifications passed to the gamut compression procedure
+have already been adjusted to the Screen White Point.
+This means that at this point the color specification's white point
+is the Screen White Point.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the gamut compression procedure uses a device-independent color space not
+initially accessible for use in the color management system, use 
+<function>XcmsAddColorSpace</function>
+to ensure that it is added.
+    </para>
+  </listitem>
+</itemizedlist>
+</sect2>
+<sect2 id="Supplied_Gamut_Compression_Procedures">
+<title>Supplied Gamut Compression Procedures</title>
+<!-- .XS -->
+<!-- (SN Supplied Gamut Compression Procedures -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following equations are useful in describing gamut compression
+functions:
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
+
+%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
+
+%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
+
+%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The gamut compression callback procedures provided by Xlib are as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<function>XcmsCIELabClipL</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the 
+screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*) 
+in the <acronym>CIE</acronym> L*a*b* color space until the color is within the gamut.
+If the Psychometric Chroma of the color specification 
+is beyond maximum for the Psychometric Hue Angle,
+then while maintaining the same Psychometric Hue Angle,
+the color will be clipped to the <acronym>CIE</acronym> L*a*b* coordinates of maximum
+Psychometric Chroma.
+See
+<function>XcmsCIELabQueryMaxC</function>.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsCIELabClipab</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the 
+screen's color gamut by reducing Psychometric Chroma,
+while maintaining Psychometric Hue Angle,
+until the color is within the gamut.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsCIELabClipLab</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with <acronym>CIE</acronym> L*a*b* coordinates
+that fall within the color gamut while maintaining the original
+Psychometric Hue
+Angle and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsCIELuvClipL</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the 
+screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*)
+in the <acronym>CIE</acronym> L*u*v* color space until the color is within the gamut.
+If the Psychometric Chroma of the color specification
+is beyond maximum for the Psychometric Hue Angle,
+then, while maintaining the same Psychometric Hue Angle,
+the color will be clipped to the <acronym>CIE</acronym> L*u*v* coordinates of maximum
+Psychometric Chroma.
+See
+<function>XcmsCIELuvQueryMaxC</function>.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsCIELuvClipuv</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing
+Psychometric Chroma, while maintaining Psychometric Hue Angle,
+until the color is within the gamut.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsCIELuvClipLuv</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with <acronym>CIE</acronym> L*u*v* coordinates
+that fall within the color gamut while maintaining the original
+Psychometric Hue
+Angle and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsTekHVCClipV</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing or increasing the Value dimension
+in the TekHVC color space until the color is within the gamut.
+If Chroma of the color specification is beyond maximum for the particular Hue,
+then, while maintaining the same Hue,
+the color will be clipped to the Value and Chroma coordinates
+that represent maximum Chroma for that particular Hue.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsTekHVCClipC</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing the Chroma dimension
+in the TekHVC color space until the color is within the gamut.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsTekHVCClipVC</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with TekHVC coordinates
+that fall within the color gamut while maintaining the original Hue
+and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+    </para>
+  </listitem>
+</itemizedlist>
+</sect2>
+<sect2 id="Prototype_White_Point_Adjustment_Procedure">
+<title>Prototype White Point Adjustment Procedure</title>
+<!-- .XS -->
+<!-- (SN Prototype White Point Adjustment Procedure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The white point adjustment procedure interface must adhere to the following:
+</para>
+<indexterm significance="preferred"><primary>XcmsWhiteAdjustProc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmswhiteadjustproc'>
+<funcprototype>
+  <funcdef>typedef Status <function>(*XcmsWhiteAdjustProc</function>)</funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *initial_white_point</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *target_white_point</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>initial_white_point</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the initial white point.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_white_point</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target white point.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target color specification format.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colors_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of 
+<structname>XcmsColor</structname>
+structures in the color-specification array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>compression_flags_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+<symbol>True</symbol>
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Supplied_White_Point_Adjustment_Procedures">
+<title>Supplied White Point Adjustment Procedures</title>
+<!-- .XS -->
+<!-- (SN Supplied White Point Adjustment Procedures -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+White point adjustment procedures provided by Xlib are as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<function>XcmsCIELabWhiteShiftColors</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This uses the <acronym>CIE</acronym> L*a*b* color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to 
+<structname>XcmsCIELab</structname>
+using the source white point and then converts to the target specification
+format using the destination's white point.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsCIELuvWhiteShiftColors</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This uses the <acronym>CIE</acronym> L*u*v* color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to 
+<structname>XcmsCIELuv</structname>
+using the source white point and then converts to the target specification
+format using the destination's white point.
+No client data is necessary.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XcmsTekHVCWhiteShiftColors</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+This uses the TekHVC color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to
+<structname>XcmsTekHVC</structname>
+using the source white point and then converts to the target specification
+format using the destination's white point.
+An advantage of this procedure over those previously described
+is an attempt to minimize hue shift.
+No client data is necessary.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+From an implementation point of view,
+these white point adjustment procedures convert the color specifications
+to a device-independent but white-point-dependent color space 
+(for example, <acronym>CIE</acronym> L*u*v*, <acronym>CIE</acronym> L*a*b*, TekHVC) using one white point
+and then converting those specifications to the target color space 
+using another white point.
+In other words,
+the specification goes in the color space with one white point 
+but comes out with another white point, 
+resulting in a chromatic shift based on the chromatic displacement
+between the initial white point and target white point.
+The <acronym>CIE</acronym> color spaces that are assumed to be white-point-independent
+are <acronym>CIE</acronym> u'v'Y, <acronym>CIE</acronym> XYZ, and <acronym>CIE</acronym> xyY.
+When developing a custom white point adjustment procedure that uses a
+device-independent color space not initially accessible for use in the
+color management system, use
+<function>XcmsAddColorSpace</function>
+to ensure that it is added.
+</para>
+<para>
+<!-- .LP -->
+As an example, 
+if the CCC specifies a white point adjustment procedure
+and if the Client White Point and Screen White Point differ, the
+<function>XcmsAllocColor</function>
+function will use the white point adjustment
+procedure twice: 
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Once to convert to
+<structname>XcmsRGB</structname>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A second time to convert from
+<structname>XcmsRGB</structname>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For example, assume the specification is in
+<structname>XcmsCIEuvY</structname>
+and the adjustment procedure is
+<function>XcmsCIELuvWhiteShiftColors</function>.
+During conversion to
+<structname>XcmsRGB</structname>,
+the call to 
+<function>XcmsAllocColor</function>
+results in the following series of color specification conversions:
+<!-- .\" Do these need to be font coded? -->
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+From 
+<structname>XcmsCIEuvY</structname>
+to
+<structname>XcmsCIELuv</structname>
+using the Client White Point
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+From 
+<structname>XcmsCIELuv</structname>
+to
+<structname>XcmsCIEuvY</structname>
+using the Screen White Point
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+From
+<structname>XcmsCIEuvY</structname>
+to
+<structname>XcmsCIEXYZ</structname>
+(<acronym>CIE</acronym> u'v'Y and XYZ are white-point-independent color spaces)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+From 
+<structname>XcmsCIEXYZ</structname>
+to 
+<structname>XcmsRGBi</structname>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+From 
+<structname>XcmsRGBi</structname>
+to
+<structname>XcmsRGB</structname>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The resulting <acronym>RGB</acronym> specification is passed to
+<function>XAllocColor</function>,
+and the <acronym>RGB</acronym>
+specification returned by
+<function>XAllocColor</function>
+is converted back to 
+<structname>XcmsCIEuvY</structname>
+by reversing the color conversion sequence.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Gamut_Querying_Functions">
+<title>Gamut Querying Functions</title>
+<!-- .XS -->
+<!-- (SN Gamut Querying Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section describes the gamut querying functions that Xlib provides.
+These functions allow the client to query the boundary 
+of the screen's color gamut in terms of the <acronym>CIE</acronym> L*a*b*, <acronym>CIE</acronym> L*u*v*, 
+and TekHVC color spaces.
+<indexterm><primary>Gamut querying</primary></indexterm>
+Functions are also provided that allow you to query 
+the color specification of:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+White (full-intensity red, green, and blue)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Red (full-intensity red while green and blue are zero)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Green (full-intensity green while red and blue are zero)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Blue (full-intensity blue while red and green are zero)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Black (zero-intensity red, green, and blue)
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The white point associated with color specifications passed to 
+and returned from these gamut querying
+functions is assumed to be the Screen White Point.
+<indexterm><primary>Screen White Point</primary></indexterm>
+This is a reasonable assumption,
+because the client is trying to query the screen's color gamut.
+</para>
+<para>
+<!-- .LP -->
+The following naming convention is used for the Max and Min functions:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+Xcms<emphasis remap='I'>&lt;color_space&gt;</emphasis>QueryMax<emphasis remap='I'>&lt;dimensions&gt;</emphasis>
+
+Xcms<emphasis remap='I'>&lt;color_space&gt;</emphasis>QueryMin<emphasis remap='I'>&lt;dimensions&gt;</emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The &lt;dimensions&gt; consists of a letter or letters 
+that identify the dimensions of the color space 
+that are not fixed.
+For example, 
+<function>XcmsTekHVCQueryMaxC</function>
+is given a fixed Hue and Value for which maximum Chroma is found.
+</para>
+<sect2 id="Red_Green_and_Blue_Queries">
+<title>Red, Green, and Blue Queries</title>
+<!-- .XS -->
+<!-- (SN Red, Green, and Blue Queries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To obtain the color specification for black 
+(zero-intensity red, green, and blue), use
+<function>XcmsQueryBlack</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryBlack</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsqueryblack'>
+<funcprototype>
+  <funcdef>Status <function>XcmsQueryBlack</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target color specification format.
+<!-- .ds Cs zero-intensity red, green, and blue -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsQueryBlack</function>
+function returns the color specification in the specified target format
+for zero-intensity red, green, and blue.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the color specification for blue 
+(full-intensity blue while red and green are zero), use
+<function>XcmsQueryBlue</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryBlue</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsqueryblue'>
+<funcprototype>
+  <funcdef>Status <function>XcmsQueryBlue</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target color specification format.
+<!-- .ds Cs full-intensity blue while red and green are zero -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsQueryBlue</function>
+function returns the color specification in the specified target format
+for full-intensity blue while red and green are zero.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the color specification for green
+(full-intensity green while red and blue are zero), use
+<function>XcmsQueryGreen</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryGreen</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsquerygreen'>
+<funcprototype>
+  <funcdef>Status <function>XcmsQueryGreen</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target color specification format.
+<!-- .ds Cs full-intensity green while red and blue are zero -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsQueryGreen</function>
+function returns the color specification in the specified target format
+for full-intensity green while red and blue are zero.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the color specification for red
+(full-intensity red while green and blue are zero), use
+<function>XcmsQueryRed</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryRed</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsqueryred'>
+<funcprototype>
+  <funcdef>Status <function>XcmsQueryRed</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target color specification format.
+<!-- .ds Cs full-intensity red while green and blue are zero -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsQueryRed</function>
+function returns the color specification in the specified target format
+for full-intensity red while green and blue are zero.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the color specification for white
+(full-intensity red, green, and blue), use
+<function>XcmsQueryWhite</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsQueryWhite</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsquerywhite'>
+<funcprototype>
+  <funcdef>Status <function>XcmsQueryWhite</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColorFormat<parameter> target_format</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target color specification format.
+<!-- .ds Cs full-intensity red, green, and blue -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color specification in the specified target format
+for (Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsQueryWhite</function>
+function returns the color specification in the specified target format
+for full-intensity red, green, and blue.
+</para>
+</sect2>
+<sect2 id="CIELab_Queries">
+<title>CIELab Queries</title>
+<!-- .XS -->
+<!-- (SN CIELab Queries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following equations are useful in describing the CIELab query functions:
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
+<literallayout class="monospaced">
+%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
+
+%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
+</literallayout>
+<!-- .sp -->
+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use
+<function>XcmsCIELabQueryMaxC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscielabquerymaxc'>
+<funcprototype>
+  <funcdef>Status <function>XcmsCIELabQueryMaxC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> L_star</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue_angle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ls maximum chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>L_star</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the lightness (L*) at which to find (Ls.
+<!-- .ds Lc maximum chroma -->
+<!-- .ds lC hue angle and lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsCIELabQueryMaxC</function>
+function, given a hue angle and lightness,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+<function>XcmsCIELabQueryMaxL</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxL</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscielabquerymaxl'>
+<funcprototype>
+  <funcdef>Status <function>XcmsCIELabQueryMaxL</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue_angle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ch maximum lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>chroma</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the chroma at which to find (Ch.
+<!-- .ds Lc maximum lightness -->
+<!-- .ds lC hue angle and chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsCIELabQueryMaxL</function>
+function, given a hue angle and chroma,
+finds the point in <acronym>CIE</acronym> L*a*b* color space of maximum 
+lightness (L*) displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
+An 
+<symbol>XcmsFailure</symbol>
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle, use
+<function>XcmsCIELabQueryMaxLC</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxLC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscielabquerymaxlc'>
+<funcprototype>
+  <funcdef>Status <function>XcmsCIELabQueryMaxLC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue_angle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Lc maximum chroma -->
+<!-- .ds lC hue angle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsCIELabQueryMaxLC</function>
+function, given a hue angle,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*a*b* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+<function>XcmsCIELabQueryMinL</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELabQueryMinL</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscielabqueryminlc'>
+<funcprototype>
+  <funcdef>Status <function>XcmsCIELabQueryMinL</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha minimum lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue_angle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ch minimum lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>chroma</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the chroma at which to find (Ch.
+<!-- .ds Lc minimum lightness -->
+<!-- .ds lC hue angle and chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsCIELabQueryMinL</function>
+function, given a hue angle and chroma,
+finds the point of minimum lightness (L*) displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
+An 
+<symbol>XcmsFailure</symbol>
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+</para>
+</sect2>
+<sect2 id="CIELuv_Queries">
+<title>CIELuv Queries</title>
+<!-- .XS -->
+<!-- (SN CIELuv Queries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following equations are useful in describing the CIELuv query functions:
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
+<literallayout class="monospaced">
+%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
+
+%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use
+<function>XcmsCIELuvQueryMaxC</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmxcieluvquerymaxc'>
+<funcprototype>
+  <funcdef>Status <function>XcmsCIELuvQueryMaxC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> L_star</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue_angle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ls maximum chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>L_star</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the lightness (L*) at which to find (Ls.
+<!-- .ds Lc maximum chroma -->
+<!-- .ds lC hue angle and lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsCIELuvQueryMaxC</function>
+function, given a hue angle and lightness,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+<function>XcmsCIELuvQueryMaxL</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxL</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscieluvquerymaxl'>
+<funcprototype>
+  <funcdef>Status <function>XcmsCIELuvQueryMaxL</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue_angle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ls maximum lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>L_star</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the lightness (L*) at which to find (Ls.
+<!-- .ds Lc maximum lightness -->
+<!-- .ds lC hue angle and chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsCIELuvQueryMaxL</function>
+function, given a hue angle and chroma,
+finds the point in <acronym>CIE</acronym> L*u*v* color space of maximum 
+lightness (L*) displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
+An 
+<symbol>XcmsFailure</symbol>
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle, use
+<function>XcmsCIELuvQueryMaxLC</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxLC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscieluvquerymaxlc'>
+<funcprototype>
+  <funcdef>Status <function>XcmsCIELuvQueryMaxLC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha maximum chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue_angle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Lc maximum chroma -->
+<!-- .ds lC hue angle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsCIELuvQueryMaxLC</function>
+function, given a hue angle,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the <acronym>CIE</acronym> L*u*v* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+<function>XcmsCIELuvQueryMinL</function>.
+</para>
+<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
+<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMinL</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmscieluvqueryminl'>
+<funcprototype>
+  <funcdef>Status <function>XcmsCIELuvQueryMinL</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue_angle</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Ha minimum lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue_angle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the hue angle (in degrees) at which to find (Ha.
+<!-- .ds Ch minimum lightness -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>chroma</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the chroma at which to find (Ch.
+<!-- .ds Lc minimum lightness -->
+<!-- .ds lC hue angle and chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
+displayable by the screen for the given (lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsCIELuvQueryMinL</function>
+function, given a hue angle and chroma,
+finds the point of minimum lightness (L*) displayable by the screen.
+It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
+An 
+<symbol>XcmsFailure</symbol>
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+</para>
+</sect2>
+<sect2 id="TekHVC_Queries">
+<title>TekHVC Queries</title>
+<!-- .XS -->
+<!-- (SN TekHVC Queries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To obtain the maximum Chroma for a given Hue and Value, use
+<function>XcmsTekHVCQueryMaxC</function>.
+</para>
+<indexterm><primary>Chroma</primary></indexterm>
+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmstekhvcquerymaxc'>
+<funcprototype>
+  <funcdef>Status <function>XcmsTekHVCQueryMaxC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> value</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu in which to find the maximum Chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the Hue (Hu.
+<!-- .ds Va maximum Chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the Value in which to find the (Va.
+<!-- .ds Lc maximum Chroma along with the actual Hue and Value  -->
+<!-- .ds lC maximum Chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the (Lc at which the (lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsTekHVCQueryMaxC</function>
+function, given a Hue and Value,
+determines the maximum Chroma in TekHVC color space
+displayable by the screen.
+It returns the maximum Chroma along with the actual Hue
+and Value at which the maximum Chroma was found.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the maximum Value for a given Hue and Chroma, use
+<function>XcmsTekHVCQueryMaxV</function>.
+</para>
+<indexterm><primary>Value</primary></indexterm>
+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxV</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmstekhvcquerymaxv'>
+<funcprototype>
+  <funcdef>Status <function>XcmsTekHVCQueryMaxV</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu in which to find the maximum Value -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the Hue (Hu.
+<!-- .ds Ch maximum Value -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>chroma</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the chroma at which to find (Ch.
+<!-- .ds Lc maximum Value along with the Hue and Chroma -->
+<!-- .ds lC maximum Value -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the (Lc at which the (lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsTekHVCQueryMaxV</function>
+function, given a Hue and Chroma,
+determines the maximum Value in TekHVC color space
+displayable by the screen.
+It returns the maximum Value and the actual Hue and Chroma
+at which the maximum Value was found.
+<!-- .sp -->
+</para>
+
+<para>
+<!-- .LP -->
+To obtain the maximum Chroma and Value at which it is reached
+for a specified Hue, use
+<function>XcmsTekHVCQueryMaxVC</function>.
+</para>
+<indexterm><primary>Chroma</primary></indexterm>
+<indexterm><primary>Value</primary></indexterm>
+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmstekhvcquerymaxvc'>
+<funcprototype>
+  <funcdef>Status <function>XcmsTekHVCQueryMaxVC</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu in which to find the maximum Chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the Hue (Hu.
+<!-- .ds Lc color specification in \ -->
+XcmsTekHVC for the maximum Chroma, the Value at which \
+that maximum Chroma is reached, and the actual Hue
+<!-- .ds lC maximum Chroma -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the (Lc at which the (lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsTekHVCQueryMaxVC</function>
+function, given a Hue,
+determines the maximum Chroma in TekHVC color space displayable by the screen
+and the Value at which that maximum Chroma is reached.
+It returns the maximum Chroma,
+the Value at which that maximum Chroma is reached,
+and the actual Hue for which the maximum Chroma was found.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a specified number of TekHVC specifications such that they
+contain maximum Values for a specified Hue and the
+Chroma at which the maximum Values are reached, use
+<function>XcmsTekHVCQueryMaxVSamples</function>.
+</para>
+<indexterm><primary>Chroma</primary></indexterm>
+<indexterm><primary>Value</primary></indexterm>
+<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
+<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVSamples</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmstekhvcquerymaxvsamples'>
+<funcprototype>
+  <funcdef>Status <function>XcmsTekHVCQueryMaxVSamples</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> colors_return[]</parameter></paramdef>
+  <paramdef>unsignedint<parameter> nsamples</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu for maximum Chroma/Value samples -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the Hue (Hu.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nsamples</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of samples.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colors_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns nsamples of color specifications in XcmsTekHVC
+such that the Chroma is the maximum attainable for the Value and Hue.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsTekHVCQueryMaxVSamples</function>
+returns nsamples of maximum Value, the Chroma at which that maximum Value
+is reached, and the actual Hue for which the maximum Chroma was found.
+These sample points may then be used to plot the maximum Value/Chroma
+boundary of the screen's color gamut for the specified Hue in TekHVC color
+space.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the minimum Value for a given Hue and Chroma, use
+<function>XcmsTekHVCQueryMinV</function>.
+</para>
+<indexterm><primary>Value</primary></indexterm>
+<indexterm><primary>Value</primary><secondary>minimum</secondary></indexterm>
+<indexterm significance="preferred"><primary>XcmsTekHVCQueryMinV</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmstekhvcqueryminv'>
+<funcprototype>
+  <funcdef>Status <function>XcmsTekHVCQueryMinV</function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> hue</parameter></paramdef>
+  <paramdef>XcmsFloat<parameter> chroma</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+<!-- .ds Hu in which to find the minimum Value -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hue</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the Hue (Hu.
+<!-- .ds Va minimum Value -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the Value in which to find the (Va.
+<!-- .ds Lc minimum Value and the actual Hue and Chroma -->
+<!-- .ds lC minimum Value -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the (Lc at which the (lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XcmsTekHVCQueryMinV</function>
+function, given a Hue and Chroma,
+determines the minimum Value in TekHVC color space displayable by the screen.
+It returns the minimum Value and the actual Hue and Chroma at which
+the minimum Value was found.
+</para>
+
+</sect2>
+</sect1>
+<sect1 id="Color_Management_Extensions">
+<title>Color Management Extensions</title>
+<!-- .XS -->
+<!-- (SN Color Management Extensions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The Xlib color management facilities can be extended in two ways:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Device-Independent Color Spaces
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Device-independent color spaces that are derivable to <acronym>CIE</acronym> XYZ
+space can be added using the
+<function>XcmsAddColorSpace</function>
+function.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Color Characterization Function Set
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A Color Characterization Function Set consists of
+device-dependent color spaces and their functions that
+convert between these color spaces and the <acronym>CIE</acronym> XYZ
+color space, bundled together for a specific class of output devices.
+A function set can be added using the
+<function>XcmsAddFunctionSet</function>
+function.
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Color_Spaces">
+<title>Color Spaces</title>
+<!-- .XS -->
+<!-- (SN Color Spaces -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The <acronym>CIE</acronym> XYZ color space serves as the hub for all
+conversions between device-independent and device-dependent color spaces.
+Therefore, the knowledge to convert an 
+<structname>XcmsColor</structname>
+structure to and from <acronym>CIE</acronym> XYZ format is associated with each color space.
+For example, conversion from <acronym>CIE</acronym> L*u*v* to <acronym>RGB</acronym> requires the knowledge
+to convert from <acronym>CIE</acronym> L*u*v* to <acronym>CIE</acronym> XYZ and from <acronym>CIE</acronym> XYZ to <acronym>RGB</acronym>.
+This knowledge is stored as an array of functions that,
+when applied in series, will convert the 
+<structname>XcmsColor</structname>
+structure to or from <acronym>CIE</acronym> XYZ format.
+This color specification conversion mechanism facilitates
+the addition of color spaces.
+</para>
+<para>
+<!-- .LP -->
+Of course, when converting between only device-independent color spaces
+or only device-dependent color spaces,
+shortcuts are taken whenever possible.
+For example, conversion from TekHVC to <acronym>CIE</acronym> L*u*v* is performed 
+by intermediate conversion to <acronym>CIE</acronym> u*v*Y and then to <acronym>CIE</acronym> L*u*v*, 
+thus bypassing conversion between <acronym>CIE</acronym> u*v*Y and <acronym>CIE</acronym> XYZ.
+</para>
+</sect2>
+<sect2 id="Adding_Device_Independent_Color_Spaces">
+<title>Adding Device-Independent Color Spaces</title>
+<!-- .XS -->
+<!-- (SN Adding Device-Independent Color Spaces -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To add a device-independent color space, use
+<function>XcmsAddColorSpace</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsAddColorSpace</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsaddcolorspace'>
+<funcprototype>
+  <funcdef>Status <function>XcmsAddColorSpace</function></funcdef>
+  <paramdef>XcmsColorSpace<parameter> *color_space</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_space</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the device-independent color space to add.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsAddColorSpace</function>
+function makes a device-independent color space (actually an
+<structname>XcmsColorSpace</structname>
+structure) accessible by the color management system.
+Because format values for unregistered color spaces are assigned at run time,
+they should be treated as private to the client.
+If references to an unregistered color space must be made
+outside the client (for example, storing color specifications 
+in a file using the unregistered color space), 
+then reference should be made by color space prefix
+(see
+<function>XcmsFormatOfPrefix</function>
+and
+<function>XcmsPrefixOfFormat</function>).
+</para>
+<para>
+<!-- .LP -->
+If the 
+<structname>XcmsColorSpace</structname>
+structure is already accessible in the color management system, 
+<function>XcmsAddColorSpace</function>
+returns 
+<symbol>XcmsSuccess</symbol>.
+</para>
+<para>
+<!-- .LP -->
+Note that added 
+<structname>XcmsColorSpace</structname>s
+must be retained for reference by Xlib.
+</para>
+</sect2>
+<sect2 id="Querying_Color_Space_Format_and_Prefix">
+<title>Querying Color Space Format and Prefix</title>
+<!-- .XS -->
+<!-- (SN Querying Color Space Format and Prefix -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To obtain the format associated with the color space
+associated with a specified color string prefix, use
+<function>XcmsFormatOfPrefix</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsFormatOfPrefix</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsformatofprefix'>
+<funcprototype>
+  <funcdef>XcmsColorFormat <function>XcmsFormatOfPrefix</function></funcdef>
+  <paramdef>char<parameter> *prefix</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>prefix</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the string that contains the color space prefix.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsFormatOfPrefix</function>
+function returns the format for the specified color space prefix
+(for example, the string ``CIEXYZ'').
+The prefix is case-insensitive.
+If the color space is not accessible in the color management system,
+<function>XcmsFormatOfPrefix</function>
+returns 
+<symbol>XcmsUndefinedFormat</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the color string prefix associated with the color space
+specified by a color format, use
+<function>XcmsPrefixOfFormat</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsPrefixOfFormat</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsprefixofformat'>
+<funcprototype>
+  <funcdef>char *<function>XcmsPrefixOfFormat</function></funcdef>
+  <paramdef>XcmsColorFormat<parameter> format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color specification format.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsPrefixOfFormat</function>
+function returns the string prefix associated with the color specification
+encoding specified by the format argument.
+Otherwise, if no encoding is found, it returns NULL.
+The returned string must be treated as read-only.
+</para>
+</sect2>
+<sect2 id="Creating_Additional_Color_Spaces">
+<title>Creating Additional Color Spaces</title>
+<!-- .XS -->
+<!-- (SN Creating Additional Color Spaces -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Color space specific information necessary 
+for color space conversion and color string parsing is stored in an
+<structname>XcmsColorSpace</structname>
+structure.
+Therefore, a new structure containing this information is required
+for each additional color space.
+In the case of device-independent color spaces,
+a handle to this new structure (that is, by means of a global variable)
+is usually made accessible to the client program for use with the
+<function>XcmsAddColorSpace</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+If a new 
+<structname>XcmsColorSpace</structname>
+structure specifies a color space not registered with the X Consortium,
+they should be treated as private to the client
+because format values for unregistered color spaces are assigned at run time.
+If references to an unregistered color space must be made outside the
+client (for example, storing color specifications in a file using the
+unregistered color space), then reference should be made by color space prefix
+(see
+<function>XcmsFormatOfPrefix</function>
+and
+<function>XcmsPrefixOfFormat</function>).
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef (*XcmsConversionProc)();
+typedef XcmsConversionProc *XcmsFuncListPtr;
+		/* A NULL terminated list of function pointers*/
+
+typedef struct _XcmsColorSpace {
+	char *prefix;
+	XcmsColorFormat format;
+	XcmsParseStringProc parseString;
+	XcmsFuncListPtr to_CIEXYZ;
+	XcmsFuncListPtr from_CIEXYZ;
+	int inverse_flag;
+} XcmsColorSpace;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The prefix member specifies the prefix that indicates a color string 
+is in this color space's string format.
+For example, the strings ``ciexyz'' or ``CIEXYZ'' for <acronym>CIE</acronym> XYZ,
+and ``rgb'' or ``<acronym>RGB</acronym>'' for <acronym>RGB</acronym>.
+The prefix is case insensitive.
+The format member specifies the color specification format.
+Formats for unregistered color spaces are assigned at run time.
+The parseString member contains a pointer to the function 
+that can parse a color string into an 
+<structname>XcmsColor</structname>
+structure.
+This function returns an integer (int): nonzero if it succeeded
+and zero otherwise.
+The to_CIEXYZ and from_CIEXYZ members contain pointers,
+each to a NULL terminated list of function pointers.
+When the list of functions is executed in series,
+it will convert the color specified in an 
+<structname>XcmsColor</structname>
+structure from/to the current color space format to/from the <acronym>CIE</acronym> XYZ format.
+Each function returns an integer (int): nonzero if it succeeded
+and zero otherwise.
+The white point to be associated with the colors is specified
+explicitly, even though white points can be found in the CCC.
+The inverse_flag member, if nonzero, specifies that for each function listed 
+in to_CIEXYZ,
+its inverse function can be found in from_CIEXYZ such that:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+Given:  n = number of functions in each list
+
+for each i, such that 0 &lt;= i &lt; n
+    from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+This allows Xlib to use the shortest conversion path,
+thus bypassing <acronym>CIE</acronym> XYZ if possible (for example, TekHVC to <acronym>CIE</acronym> L*u*v*).
+</para>
+</sect2>
+<sect2 id="Parse_String_Callback">
+<title>Parse String Callback</title>
+<!-- .XS -->
+<!-- (SN Parse String Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The callback in the
+<structname>XcmsColorSpace</structname>
+structure for parsing a color string for the particular color space must
+adhere to the following software interface specification:
+</para>
+<indexterm significance="preferred"><primary>XcmsParseStringProc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsparsestringproc'>
+<funcprototype>
+  <funcdef>Status <function>XcmsParseStringProc</function></funcdef>
+  <paramdef>char<parameter> *color_string</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *color_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the color string to parse.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>color_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the color specification in the color space's format.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Color_Specification_Conversion_Callback">
+<title>Color Specification Conversion Callback</title>
+<!-- .XS -->
+<!-- (SN Color Specification Conversion Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Callback functions in the
+<structname>XcmsColorSpace</structname>
+structure for converting a color specification between device-independent
+spaces must adhere to the
+following software interface specification:
+</para>
+<!-- .sM -->
+<funcsynopsis id='conversionproc'>
+<funcprototype>
+  <funcdef>Status <function><replaceable>ConversionProc</replaceable></function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *white_point</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *colors_in_out</parameter></paramdef>
+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>white_point</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the white point associated with color specifications.
+The pixel member should be ignored,
+and the entire structure remain unchanged upon return.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colors_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of 
+<structname>XcmsColor</structname>
+structures in the color-specification array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+Callback functions in the
+<structname>XcmsColorSpace</structname>
+structure for converting a color specification to or from a device-dependent
+space must adhere to the
+following software interface specification:
+</para>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function><replaceable>ConversionProc</replaceable></function></funcdef>
+  <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
+  <paramdef>XcmsColor<parameter> *colors_in_out</parameter></paramdef>
+  <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
+  <paramdef>Bool<parameter> compression_flags_return[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ccc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the CCC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colors_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ncolors</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of 
+<structname>XcmsColor</structname>
+structures in the color-specification array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>compression_flags_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+<symbol>True</symbol>
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Conversion functions are available globally for use by other color
+spaces.
+The conversion functions provided by Xlib are:
+</para>
+<informaltable>
+  <tgroup cols='3' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <thead>
+    <row>
+      <entry>Function</entry>
+      <entry>Converts from</entry>
+      <entry>Converts to</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry><function>XcmsCIELabToCIEXYZ</function></entry>
+      <entry><symbol>XcmsCIELabFormat</symbol></entry>
+      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIELuvToCIEuvY</function></entry>
+      <entry><symbol>XcmsCIELuvFormat</symbol></entry>
+      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIEXYZToCIELab</function></entry>
+      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
+      <entry><symbol>XcmsCIELabFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIEXYZToCIEuvY</function></entry>
+      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
+      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIEXYZToCIExyY</function></entry>
+      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
+      <entry><symbol>XcmsCIExyYFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIEXYZToRGBi</function></entry>
+      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
+      <entry><symbol>XcmsRGBiFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIEuvYToCIELuv</function></entry>
+      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
+      <entry><symbol>XcmsCIELabFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIEuvYToCIEXYZ</function></entry>
+      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
+      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIEuvYToTekHVC</function></entry>
+      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
+      <entry><symbol>XcmsTekHVCFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsCIExyYToCIEXYZ</function></entry>
+      <entry><symbol>XcmsCIExyYFormat</symbol></entry>
+      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsRGBToRGBi</function></entry>
+      <entry><symbol>XcmsRGBFormat</symbol></entry>
+      <entry><symbol>XcmsRGBiFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsRGBiToCIEXYZ</function></entry>
+      <entry><symbol>XcmsRGBiFormat</symbol></entry>
+      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsRGBiToRGB</function></entry>
+      <entry><symbol>XcmsRGBiFormat</symbol></entry>
+      <entry><symbol>XcmsRGBFormat</symbol></entry>
+    </row>
+    <row>
+      <entry><function>XcmsTekHVCToCIEuvY</function></entry>
+      <entry><symbol>XcmsTekHVCFormat</symbol></entry>
+      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+</sect2>
+<sect2 id="Function_Sets">
+<title>Function Sets</title>
+<!-- .XS -->
+<!-- (SN Function Sets -->
+<!-- .XE -->
+<indexterm><primary>Function set</primary></indexterm>
+<indexterm><primary>Function set</primary><secondary>LINEAR_RGB</secondary></indexterm>
+<para>
+<!-- .LP -->
+Functions to convert between device-dependent color spaces
+and <acronym>CIE</acronym> XYZ may differ for different classes of output devices
+(for example, color versus gray monitors).
+Therefore, the notion of a Color Characterization Function Set
+has been developed.
+A function set consists of device-dependent color spaces
+and the functions that convert color specifications 
+between these device-dependent color spaces and the <acronym>CIE</acronym> XYZ color space
+appropriate for a particular class of output devices.
+The function set also contains a function that reads
+color characterization data off root window properties.
+It is this characterization data that will differ between devices within
+a class of output devices.
+<indexterm><primary>Device Color Characterization</primary></indexterm>
+For details about how color characterization data is
+stored in root window properties,
+see the section on Device Color Characterization in the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+The LINEAR_RGB function set is provided by Xlib
+and will support most color monitors.
+Function sets may require data that differs
+from those needed for the LINEAR_RGB function set.
+In that case, 
+its corresponding data may be stored on different root window properties.
+</para>
+</sect2>
+<sect2 id="Adding_Function_Sets">
+<title>Adding Function Sets</title>
+<!-- .XS -->
+<!-- (SN Adding Function Sets -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To add a function set, use
+<function>XcmsAddFunctionSet</function>.
+</para>
+<indexterm significance="preferred"><primary>XcmsAddFunctionSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcmsaddfunctionset'>
+<funcprototype>
+  <funcdef>Status <function>XcmsAddFunctionSet</function></funcdef>
+  <paramdef>XcmsFunctionSet<parameter> *function_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>function_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the function set to add.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XcmsAddFunctionSet</function>
+function adds a function set to the color management system.
+If the function set uses device-dependent 
+<structname>XcmsColorSpace</structname>
+structures not accessible in the color management system,
+<function>XcmsAddFunctionSet</function>
+adds them.
+If an added
+<structname>XcmsColorSpace</structname>
+structure is for a device-dependent color space not registered
+with the X Consortium,
+they should be treated as private to the client
+because format values for unregistered color spaces are assigned at run time.
+If references to an unregistered color space must be made outside the
+client (for example, storing color specifications in a file
+using the unregistered color space),
+then reference should be made by color space prefix
+(see 
+<function>XcmsFormatOfPrefix</function>
+and
+<function>XcmsPrefixOfFormat</function>).
+</para>
+<para>
+<!-- .LP -->
+Additional function sets should be added before any calls to other
+Xlib routines are made.
+If not, the 
+<structname>XcmsPerScrnInfo</structname>
+member of a previously created 
+<structname>XcmsCCC</structname>
+does not have the opportunity to initialize
+with the added function set.
+</para>
+</sect2>
+<sect2 id="Creating_Additional_Function_Sets">
+<title>Creating Additional Function Sets</title>
+<!-- .XS -->
+<!-- (SN Creating Additional Function Sets -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The creation of additional function sets should be
+required only when an output device does not conform to existing 
+function sets or when additional device-dependent color spaces are necessary.
+A function set consists primarily of a collection of device-dependent
+<structname>XcmsColorSpace</structname>
+structures and a means to read and store a 
+screen's color characterization data.
+This data is stored in an
+<structname>XcmsFunctionSet</structname>
+structure.
+A handle to this structure (that is, by means of global variable)
+is usually made accessible to the client program for use with
+<function>XcmsAddFunctionSet</function>.
+</para>
+<para>
+<!-- .LP -->
+If a function set uses new device-dependent 
+<structname>XcmsColorSpace</structname>
+structures,
+they will be transparently processed into the color management system.
+Function sets can share an 
+<structname>XcmsColorSpace</structname>
+structure for a device-dependent color space.
+In addition, multiple 
+<structname>XcmsColorSpace</structname>
+structures are allowed for a device-dependent color space;
+however, a function set can reference only one of them.
+These 
+<structname>XcmsColorSpace</structname>
+structures will differ in the functions to convert to and from <acronym>CIE</acronym> XYZ,
+thus tailored for the specific function set.
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XcmsFunctionSet {
+	XcmsColorSpace **DDColorSpaces;
+	XcmsScreenInitProc screenInitProc;
+	XcmsScreenFreeProc screenFreeProc;
+} XcmsFunctionSet;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The DDColorSpaces member is a pointer to a NULL terminated list
+of pointers to 
+<structname>XcmsColorSpace</structname>
+structures for the device-dependent color spaces that are supported
+by the function set.
+The screenInitProc member is set to the callback procedure (see the following
+interface specification) that initializes the 
+<structname>XcmsPerScrnInfo</structname>
+structure for a particular screen.
+</para>
+<para>
+<!-- .LP -->
+The screen initialization callback must adhere to the following software
+interface specification:
+<indexterm significance="preferred"><primary>XcmsScreenInitProc</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+  <funcdef>typedef Status <function>(*XcmsScreenInitProc</function>)</funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> screen_number</parameter></paramdef>
+  <paramdef>ScmsPerScrnInfo<parameter> *screen_info</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the appropriate screen number on the host server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_info</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XcmsPerScrnInfo</structname>
+structure, which contains the per screen information.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The screen initialization callback in the
+<structname>XcmsFunctionSet</structname>
+structure fetches the color characterization data (device profile) for
+the specified screen,
+typically off properties on the 
+screen's root window.
+It then initializes the specified
+<structname>XcmsPerScrnInfo</structname>
+structure.
+<indexterm><primary>Device profile</primary></indexterm>
+<indexterm><primary>Color Characterization Data</primary></indexterm>
+If successful, the procedure fills in the 
+<structname>XcmsPerScrnInfo</structname>
+structure as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+It sets the screenData member to the address 
+of the created device profile data structure 
+(contents known only by the function set).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+It next sets the screenWhitePoint member.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+It next sets the functionSet member to the address of the
+<structname>XcmsFunctionSet</structname>
+structure.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+It then sets the state member to 
+<symbol>XcmsInitSuccess</symbol>
+and finally returns
+<symbol>XcmsSuccess</symbol>.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If unsuccessful, the procedure sets the state member to 
+<symbol>XcmsInitFailure</symbol>
+and returns
+<symbol>XcmsFailure</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XcmsPerScrnInfo</structname>
+structure contains:
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XcmsPerScrnInfo {
+	XcmsColor screenWhitePoint;
+	XPointer functionSet;
+	XPointer screenData;
+	unsigned char state;
+	char pad[3];
+} XcmsPerScrnInfo;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The screenWhitePoint member specifies the white point inherent to
+the screen.
+The functionSet member specifies the appropriate function set.
+The screenData member specifies the device profile.
+The state member is set to one of the following:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<symbol>XcmsInitNone</symbol>
+indicates initialization has not been previously attempted.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<symbol>XcmsInitFailure</symbol>
+indicates initialization has been previously attempted but failed.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<symbol>XcmsInitSuccess</symbol>
+indicates initialization has been previously attempted and succeeded.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The screen free callback must adhere to the following software
+interface specification:
+</para>
+<funcsynopsis>
+<funcprototype>
+  <funcdef>typedef void (*XcmsScreenFreeProc)</funcdef>
+  <paramdef>XPointer<parameter> screenData</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screenData</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the data to be freed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+This function is called to free the screenData stored in an
+<structname>XcmsPerScrnInfo</structname>
+structure.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH07.xml b/libX11/specs/libX11/CH07.xml
index 505a565a2..ff1a9d836 100644
--- a/libX11/specs/libX11/CH07.xml
+++ b/libX11/specs/libX11/CH07.xml
@@ -1,3407 +1,3407 @@
-<?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="graphics_context_functions">

-<title>Graphics Context Functions</title>

-

-<para>

-A number of resources are used when performing graphics operations in X. Most information

-about performing graphics (for example, foreground color, background color, line style, and so

-on) is stored in resources called graphics contexts (GCs). Most graphics operations (see chapter

-8) take a GC as an argument. Although in theory the X protocol permits sharing of GCs between

-applications, it is expected that applications will use their own GCs when performing operations.

-Sharing of GCs is highly discouraged because the library may cache GC state.

-</para>

-<para>

-Graphics operations can be performed to either windows or pixmaps, which collectively are

-called drawables. Each drawable exists on a single screen. A GC is created for a specific screen

-and drawable depth and can only be used with drawables of matching screen and depth.

-</para>

-<para>

-This chapter discusses how to:

-</para>

-<itemizedlist>

-  <listitem><para>Manipulate graphics context/state</para></listitem>

-  <listitem><para>Use graphics context convenience functions</para></listitem>

-</itemizedlist>

-

-<sect1 id="Manipulating_Graphics_Context_State">

-<title>Manipulating Graphics Context/State</title>

-<!-- .XS -->

-<!-- (SN Manipulating Graphics Context/State  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Most attributes of graphics operations are stored in GCs.

-These include line width, line style, plane mask, foreground, background,

-tile, stipple, clipping region, end style, join style, and so on.

-Graphics operations (for example, drawing lines) use these values

-to determine the actual drawing operation.

-Extensions to X may add additional components to GCs.

-The contents of a GC are private to Xlib.

-</para>

-<para>

-<!-- .LP -->

-Xlib implements a write-back cache for all elements of a GC that are not

-resource IDs to allow Xlib to implement the transparent coalescing of changes 

-to GCs.

-For example,

-a call to

-<function>XSetForeground</function>

-of a GC followed by a call to

-<function>XSetLineAttributes</function>

-results in only a single-change GC protocol request to the server.

-GCs are neither expected nor encouraged to be shared between client 

-applications, so this write-back caching should present no problems.

-Applications cannot share GCs without external synchronization.

-Therefore,

-sharing GCs between applications is highly discouraged. 

-</para>

-<para>

-<!-- .LP -->

-To set an attribute of a GC,

-set the appropriate member of the

-<structname>XGCValues</structname>

-structure and OR in the corresponding value bitmask in your subsequent calls to

-<function>XCreateGC</function>.

-The symbols for the value mask bits and the

-<structname>XGCValues</structname>

-structure are:

-<!-- .sM -->

-</para>

-

-

-<literallayout class="monospaced">

-/* GC attribute value mask bits */

-

-#define     GCFunction              (1L&lt;&lt;0)

-#define     GCPlaneMask             (1L&lt;&lt;1)

-#define     GCForeground            (1L&lt;&lt;2)

-#define     GCBackground            (1L&lt;&lt;3)

-#define     GCLineWidth             (1L&lt;&lt;4)

-#define     GCLineStyle             (1L&lt;&lt;5)

-#define     GCCapStyle              (1L&lt;&lt;6)

-#define     GCJoinStyle             (1L&lt;&lt;7)

-#define     GCFillStyle             (1L&lt;&lt;8)

-#define     GCFillRule              (1L&lt;&lt;9)

-#define     GCTile                  (1L&lt;&lt;10)

-#define     GCStipple               (1L&lt;&lt;11)

-#define     GCTileStipXOrigin       (1L&lt;&lt;12)

-#define     GCTileStipYOrigin       (1L&lt;&lt;13)

-#define     GCFont                  (1L&lt;&lt;14)

-#define     GCSubwindowMode         (1L&lt;&lt;15)

-#define     GCGraphicsExposures     (1L&lt;&lt;16)

-#define     GCClipXOrigin           (1L&lt;&lt;17)

-#define     GCClipYOrigin           (1L&lt;&lt;18)

-#define     GCClipMask              (1L&lt;&lt;19)

-#define     GCDashOffset            (1L&lt;&lt;20)

-#define     GCDashList              (1L&lt;&lt;21)

-#define     GCArcMode               (1L&lt;&lt;22)

-</literallayout>

-

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-/* Values */

-

-typedef struct {

-     int function;                 /* logical operation */

-     unsigned long plane_mask;     /* plane mask */

-     unsigned long foreground;     /* foreground pixel */

-     unsigned long background;     /* background pixel */

-     int line_width;               /* line width (in pixels) */

-     int line_style;               /* LineSolid, LineOnOffDash, LineDoubleDash */

-     int cap_style;                /* CapNotLast, CapButt, CapRound, CapProjecting */

-     int join_style;               /* JoinMiter, JoinRound, JoinBevel */

-     int fill_style;               /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/

-     int fill_rule;                /* EvenOddRule, WindingRule */

-     int arc_mode;                 /* ArcChord, ArcPieSlice */

-     Pixmap tile;                  /* tile pixmap for tiling operations */

-     Pixmap stipple;               /* stipple 1 plane pixmap for stippling */

-     int ts_x_origin;              /* offset for tile or stipple operations */

-     int ts_y_origin

-     Font font;                    /* default text font for text operations */

-     int subwindow_mode;           /* ClipByChildren, IncludeInferiors */

-     Bool graphics_exposures;      /* boolean, should exposures be generated */

-     int clip_x_origin;            /* origin for clipping */

-     int clip_y_origin;

-     Pixmap clip_mask;             /* bitmap clipping; other calls for rects */

-     int dash_offset;              /* patterned/dashed line information */

-     char dashes;

-} XGCValues;

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The default GC values are:

-</para>

-<informaltable>

-  <tgroup cols='3' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <thead>

-    <row>

-      <entry>Component</entry>

-      <entry>Default</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>function</entry>

-      <entry><symbol>GXcopy</symbol></entry>

-    </row>

-    <row>

-      <entry>plane_mask</entry>

-      <entry>All ones</entry>

-    </row>

-    <row>

-      <entry>foreground</entry>

-      <entry>0</entry>

-    </row>

-    <row>

-      <entry>background</entry>

-      <entry>1</entry>

-    </row>

-    <row>

-      <entry>line_width</entry>

-      <entry>0</entry>

-    </row>

-    <row>

-      <entry>line_style</entry>

-      <entry><symbol>LineSolid</symbol></entry>

-    </row>

-    <row>

-      <entry>cap_style</entry>

-      <entry><symbol>CapButt</symbol></entry>

-    </row>

-    <row>

-      <entry>join_style</entry>

-      <entry><symbol>JoinMiter</symbol></entry>

-    </row>

-    <row>

-      <entry>fill_style</entry>

-      <entry><symbol>FillSolid</symbol></entry>

-    </row>

-    <row>

-      <entry>fill_rule</entry>

-      <entry><symbol>EvenOddRule</symbol></entry>

-    </row>

-    <row>

-      <entry>arc_mode</entry>

-      <entry><symbol>ArcPieSlice</symbol></entry>

-    </row>

-    <row>

-      <entry>tile</entry>

-      <entry>Pixmap of unspecified size filled with foreground pixel</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>(that is, client specified pixel if any, else 0)</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>(subsequent changes to foreground do not affect this pixmap)</entry>

-    </row>

-    <row>

-      <entry>stipple</entry>

-      <entry>Pixmap of unspecified size filled with ones</entry>

-    </row>

-    <row>

-      <entry>ts_x_origin</entry>

-      <entry>0</entry>

-    </row>

-    <row>

-      <entry>ts_y_origin</entry>

-      <entry>0</entry>

-    </row>

-    <row>

-      <entry>font</entry>

-      <entry>&lt;implementation dependent&gt;</entry>

-    </row>

-    <row>

-      <entry>subwindow_mode</entry>

-      <entry><symbol>ClipByChildren</symbol></entry>

-    </row>

-    <row>

-      <entry>graphics_exposures</entry>

-      <entry><symbol>True</symbol></entry>

-    </row>

-    <row>

-      <entry>clip_x_origin</entry>

-      <entry>0</entry>

-    </row>

-    <row>

-      <entry>clip_y_origin</entry>

-      <entry>0</entry>

-    </row>

-    <row>

-      <entry>clip_mask</entry>

-      <entry><symbol>None</symbol></entry>

-    </row>

-    <row>

-      <entry>dash_offset</entry>

-      <entry>0</entry>

-    </row>

-    <row>

-      <entry>dashes</entry>

-      <entry>4 (that is, the list [4, 4])</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-Note that foreground and background are not set to any values likely

-to be useful in a window.

-</para>

-

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>Display Functions</primary></indexterm>

-<indexterm significance="preferred"><primary>Source</primary></indexterm>

-<indexterm significance="preferred"><primary>Destination</primary></indexterm>

-The function attributes of a GC are used when you update a section of

-a drawable (the destination) with bits from somewhere else (the source).  

-The function in a GC defines how the new destination bits are to be

-computed from the source bits and the old destination bits.

-<symbol>GXcopy</symbol>

-is typically the most useful because it will work on a color display,

-but special applications may use other functions,

-particularly in concert with particular planes of a color display.

-The 16 GC functions, defined in 

-<filename class="headerfile">&lt;X11/X.h&gt;</filename>,

-<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>

-are:

-</para>

-<!-- .\" are listed in Table 5-1 along with the  -->

-<!-- .\"the associated hexadecimal code -->

-<!-- .\" and operation. -->

-<!-- .\".CP T 1 -->

-<!-- .\"Display Functions -->

-<informaltable>

-  <tgroup cols='3' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <thead>

-    <row>

-      <entry>Function Name</entry>

-      <entry>Value</entry>

-      <entry>Operation</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry><symbol>GXclear</symbol></entry>

-      <entry>0x0</entry>

-      <entry>0</entry>

-    </row>

-    <row>

-      <entry><symbol>GXand</symbol></entry>

-      <entry>0x1</entry>

-      <entry>src AND dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXandReverse</symbol></entry>

-      <entry>0x2</entry>

-      <entry>src AND NOT dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXcopy</symbol></entry>

-      <entry>0x3</entry>

-      <entry>src</entry>

-    </row>

-    <row>

-      <entry><symbol>GXandInverted</symbol></entry>

-      <entry>0x4</entry>

-      <entry>(NOT src) AND dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXnoop</symbol></entry>

-      <entry>0x5</entry>

-      <entry>dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXxor</symbol></entry>

-      <entry>0x6</entry>

-      <entry>src XOR dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXor</symbol></entry>

-      <entry>0x7</entry>

-      <entry>src OR dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXnor</symbol></entry>

-      <entry>0x8</entry>

-      <entry>(NOT src) AND (NOT dst)</entry>

-    </row>

-    <row>

-      <entry><symbol>GXequiv</symbol></entry>

-      <entry>0x9</entry>

-      <entry>(NOT src) XOR dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXinvert</symbol></entry>

-      <entry>0xa</entry>

-      <entry>NOT dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXorReverse</symbol></entry>

-      <entry>0xb</entry>

-      <entry>src OR (NOT dst)</entry>

-    </row>

-    <row>

-      <entry><symbol>GXcopyInverted</symbol></entry>

-      <entry>0xc</entry>

-      <entry>NOT src</entry>

-    </row>

-    <row>

-      <entry><symbol>GXorInverted</symbol></entry>

-      <entry>0xd</entry>

-      <entry>(NOT src) OR dst</entry>

-    </row>

-    <row>

-      <entry><symbol>GXnand</symbol></entry>

-      <entry>0xe</entry>

-      <entry>(NOT src) OR (NOT dst)</entry>

-    </row>

-    <row>

-      <entry><symbol>GXset</symbol></entry>

-      <entry>0xf</entry>

-      <entry>1</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-Many graphics operations depend on either pixel values or planes in a GC.

-<indexterm><primary>Pixel value</primary></indexterm>

-The planes attribute is of type long, and it specifies which planes of the

-destination are to be modified, one bit per plane.

-<indexterm><primary>Plane</primary><secondary>mask</secondary></indexterm>

-A monochrome display has only one plane and

-will be the least significant bit of the word.

-As planes are added to the display hardware, they will occupy more

-significant bits in the plane mask.

-</para>

-<para>

-<!-- .LP -->

-In graphics operations, given a source and destination pixel, 

-the result is computed bitwise on corresponding bits of the pixels.

-That is, a Boolean operation is performed in each bit plane.  

-The plane_mask restricts the operation to a subset of planes.

-A macro constant

-<symbol>AllPlanes</symbol>

-can be used to refer to all planes of the screen simultaneously.

-The result is computed by the following:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Range checking is not performed on the values for foreground,

-background, or plane_mask.

-They are simply truncated to the appropriate

-number of bits.

-The line-width is measured in pixels and either can be greater than or equal to

-one (wide line) or can be the special value zero (thin line).

-</para>

-<para>

-<!-- .LP -->

-Wide lines are drawn centered on the path described by the graphics request.

-Unless otherwise specified by the join-style or cap-style,

-the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and

-width w is a rectangle with vertices at the following real coordinates:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],

-[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Here sn is the sine of the angle of the line,

-and cs is the cosine of the angle of the line.

-A pixel is part of the line and so is drawn

-if the center of the pixel is fully inside the bounding box

-(which is viewed as having infinitely thin edges).

-If the center of the pixel is exactly on the bounding box,

-it is part of the line if and only if the interior is immediately to its right

-(x increasing direction).

-Pixels with centers on a horizontal edge are a special case and are part of

-the line if and only if the interior or the boundary is immediately below 

-(y increasing direction) and the interior or the boundary is immediately

-to the right (x increasing direction).

-</para>

-<para>

-<!-- .LP -->

-Thin lines (zero line-width) are one-pixel-wide lines drawn using an

-unspecified, device-dependent algorithm.

-There are only two constraints on this algorithm. 

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If a line is drawn unclipped from [x1,y1] to [x2,y2] and

-if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],

-a point [x,y] is touched by drawing the first line 

-if and only if the point [x+dx,y+dy] is touched by drawing the second line.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The effective set of points comprising a line cannot be affected by clipping.

-That is, a point is touched in a clipped line if and only if the point 

-lies inside the clipping region and the point would be touched

-by the line when drawn unclipped.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels 

-as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style 

-and join-style.

-It is recommended that this property be true for thin lines, 

-but this is not required.

-A line-width of zero may differ from a line-width of one in which pixels are

-drawn.

-This permits the use of many manufacturers' line drawing hardware,

-which may run many times faster than the more precisely specified

-wide lines.

-</para>

-<para>

-<!-- .LP -->

-In general, 

-drawing a thin line will be faster than drawing a wide line of width one.

-However, because of their different drawing algorithms,

-thin lines may not mix well aesthetically with wide lines.

-If it is desirable to obtain precise and uniform results across all displays,

-a client should always use a line-width of one rather than a line-width of zero.

-</para>

-<para>

-<!-- .LP -->

-The line-style defines which sections of a line are drawn:

-</para>

-

-<variablelist>

-  <varlistentry>

-    <term><symbol>LineSolid</symbol></term>

-    <listitem>

-      <para>The full path of the line is drawn.</para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term><symbol>LineDoubleDash</symbol></term>

-    <listitem>

-      <para>

-The full path of the line is drawn,

-but the even dashes are filled differently

-from the odd dashes (see fill-style) with <!-- xref -->

-<symbol>CapButt</symbol>

-style used where even and odd dashes meet.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term><symbol>LineOnOffDash</symbol></term>

-    <listitem>

-      <para>

-Only the even dashes are drawn,

-and cap-style applies to 

-all internal ends of the individual dashes,

-except

-<symbol>CapNotLast</symbol>

-is treated as

-<symbol>CapButt</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-</variablelist>

-<para>

-The cap-style defines how the endpoints of a path are drawn:

-</para>

-

-<variablelist>

-  <varlistentry>

-    <term><symbol>CapNotLast</symbol></term>

-    <listitem>

-      <para>

-This is equivalent to

-<symbol>CapButt</symbol>

-except that for a line-width of zero the final endpoint is not drawn.

-     </para>

-    </listitem>

-  </varlistentry>

-

-  <varlistentry>

-    <term><symbol>CapButt</symbol></term>

-    <listitem>

-      <para>

-The line is square at the endpoint (perpendicular to the slope of the line)

-with no projection beyond.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term><symbol>CapRound</symbol></term>

-    <listitem>

-      <para>

-The line has a circular arc with the diameter equal to the line-width,

-centered on the endpoint.

-(This is equivalent to 

-<symbol>CapButt</symbol>

-for line-width of zero).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term><symbol>CapProjecting</symbol></term>

-    <listitem>

-      <para>

-The line is square at the end, but the path continues beyond the endpoint

-for a distance equal to half the line-width.

-(This is equivalent to

-<symbol>CapButt</symbol>

-for line-width of zero).

-      </para>

-    </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-The join-style defines how corners are drawn for wide lines:

-</para>

-

-<variablelist>

-  <varlistentry>

-    <term><symbol>JoinMiter</symbol></term>

-    <listitem>

-      <para>

-The outer edges of two lines extend to meet at an angle.

-However, if the angle is less than 11 degrees,

-then a

-<symbol>JoinBevel</symbol>

-join-style is used instead.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term><symbol>JoinRound</symbol></term>

-    <listitem>

-      <para>

-The corner is a circular arc with the diameter equal to the line-width,

-centered on the joinpoint.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term><symbol>JoinBevel</symbol></term>

-    <listitem>

-      <para>

-The corner has

-<symbol>CapButt</symbol>

-endpoint styles with the triangular notch filled.

-      </para>

-    </listitem>

-  </varlistentry>

-</variablelist>

-

-

-<para>

-<!-- .LP -->

-For a line with coincident endpoints (x1=x2, y1=y2), 

-when the cap-style is applied to both endpoints, 

-the semantics depends on the line-width and the cap-style:

-</para>

-

-<informaltable>

-  <tgroup cols='3' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <tbody>

-    <row>

-      <entry><symbol>CapNotLast</symbol></entry>

-      <entry>thin</entry>

-      <entry>The results are device dependent,

-      but the desired effect is that nothing is drawn.</entry>

-    </row>

-    <row>

-      <entry><symbol>CapButt</symbol></entry>

-      <entry>thin</entry>

-      <entry>The results are device dependent,

-      but the desired effect is that a single pixel is drawn.</entry>

-    </row>

-    <row>

-      <entry><symbol>CapRound</symbol></entry>

-      <entry>thin</entry>

-      <entry>The results are the same as for

-      <symbol>CapButt</symbol> /thin.</entry>

-    </row>

-    <row>

-      <entry><symbol>CapProjecting</symbol></entry>

-      <entry>thin</entry>

-      <entry>The results are the same as for

-      <symbol>CapButt</symbol> /thin.</entry>

-    </row>

-    <row>

-      <entry><symbol>CapButt</symbol></entry>

-      <entry>wide</entry>

-      <entry>Nothing is drawn.</entry>

-    </row>

-    <row>

-      <entry><symbol>CapRound</symbol></entry>

-      <entry>wide</entry>

-      <entry>The closed path is a circle, centered at the endpoint, and

-      with the diameter equal to the line-width.</entry>

-    </row>

-    <row>

-      <entry><symbol>CapProjecting</symbol></entry>

-      <entry>wide</entry>

-      <entry>The closed path is a square, aligned with the coordinate axes, centered at the

-      endpoint, and with the sides equal to the line-width.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-For a line with coincident endpoints (x1=x2, y1=y2), 

-when the join-style is applied at one or both endpoints, 

-the effect is as if the line was removed from the overall path.

-However, if the total path consists of or is reduced to a single point joined

-with itself, the effect is the same as when the cap-style is applied at both

-endpoints.

-</para>

-<para>

-<!-- .LP -->

-The tile/stipple represents an infinite two-dimensional plane,

-with the tile/stipple replicated in all dimensions.

-When that plane is superimposed on the drawable

-for use in a graphics operation, the upper-left corner

-of some instance of the tile/stipple is at the coordinates within

-the drawable specified by the tile/stipple origin.

-The tile/stipple and clip origins are interpreted relative to the

-origin of whatever destination drawable is specified in a graphics

-request.

-The tile pixmap must have the same root and depth as the GC,

-or a

-<errorname>BadMatch</errorname>

-error results.

-The stipple pixmap must have depth one and must have the same root as the

-GC, or a 

-<errorname>BadMatch</errorname>

-error results.  

-For stipple operations where the fill-style is

-<symbol>FillStippled</symbol>

-but not 

-<symbol>FillOpaqueStippled</symbol>,

-the stipple pattern is tiled in a

-single plane and acts as an additional clip mask to be ANDed with the clip-mask.

-Although some sizes may be faster to use than others,

-any size pixmap can be used for tiling or stippling.

-</para>

-

-<para>

-<!-- .LP -->

-The fill-style defines the contents of the source for line, text, and

-fill requests.  

-For all text and fill requests (for example,

-<function>XDrawText</function>,

-<function>XDrawText16</function>,

-<function>XFillRectangle</function>,

-<function>XFillPolygon</function>,

-and

-<function>XFillArc</function>);

-for line requests 

-with line-style 

-<symbol>LineSolid</symbol>

-(for example,

-<function>XDrawLine</function>,

-<function>XDrawSegments</function>,

-<function>XDrawRectangle</function>,

-<function>XDrawArc</function>);

-and for the even dashes for line requests with line-style 

-<symbol>LineOnOffDash</symbol>

-or 

-<symbol>LineDoubleDash</symbol>,

-the following apply:

-</para>

-

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>FillSolid</symbol></entry>

-      <entry>Foreground</entry>

-    </row>

-    <row>

-      <entry><symbol>FillTiled</symbol></entry>

-      <entry>Tile</entry>

-    </row>

-    <row>

-      <entry><symbol>FillOpaqueStippled</symbol></entry>

-      <entry>A tile with the same width and height as stipple,

-      but with background everywhere stipple has a zero

-      and with foreground everywhere stipple has a one</entry>

-    </row>

-    <row>

-      <entry><symbol>FillStippled</symbol></entry>

-      <entry>Foreground masked by stipple</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-When drawing lines with line-style

-<symbol>LineDoubleDash</symbol>,

-the odd dashes are controlled by the fill-style in the following manner:

-</para>

-

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>FillSolid</symbol></entry>

-      <entry>Background</entry>

-    </row>

-    <row>

-      <entry><symbol>FillTiled</symbol></entry>

-      <entry>Same as for even dashes</entry>

-    </row>

-    <row>

-      <entry><symbol>FillOpaqueStippled</symbol></entry>

-      <entry>Same as for even dashes</entry>

-    </row>

-    <row>

-      <entry><symbol>FillStippled</symbol></entry>

-      <entry>Background masked by stipple</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-Storing a pixmap in a GC might or might not result in a copy

-being made.

-If the pixmap is later used as the destination for a graphics request,

-the change might or might not be reflected in the GC.

-If the pixmap is used simultaneously in a graphics request both as

-a destination and as a tile or stipple,

-the results are undefined.

-</para>

-<para>

-<!-- .LP -->

-For optimum performance,

-you should draw as much as possible with the same GC 

-(without changing its components).

-The costs of changing GC components relative to using different GCs

-depend on the display hardware and the server implementation.

-It is quite likely that some amount of GC information will be

-cached in display hardware and that such hardware can only cache a small number

-of GCs.

-</para>

-<para>

-<!-- .LP -->

-The dashes value is actually a simplified form of the

-more general patterns that can be set with 

-<function>XSetDashes</function>.

-Specifying a

-value of N is equivalent to specifying the two-element list [N, N] in 

-<function>XSetDashes</function>.

-The value must be nonzero,

-or a

-<errorname>BadValue</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-The clip-mask restricts writes to the destination drawable.  

-If the clip-mask is set to a pixmap,

-it must have depth one and have the same root as the GC,

-or a

-<errorname>BadMatch</errorname>

-error results.

-If clip-mask is set to

-<symbol>None</symbol>,

-the pixels are always drawn regardless of the clip origin.

-The clip-mask also can be set by calling the

-<function>XSetClipRectangles</function>

-or

-<function>XSetRegion</function>

-functions.

-Only pixels where the clip-mask has a bit set to 1 are drawn.  

-Pixels are not drawn outside the area covered by the clip-mask 

-or where the clip-mask has a bit set to 0.

-The clip-mask affects all graphics requests.

-The clip-mask does not clip sources.

-The clip-mask origin is interpreted relative to the origin of whatever

-destination drawable is specified in a graphics request.

-</para>

-<para>

-<!-- .LP -->

-You can set the subwindow-mode to

-<symbol>ClipByChildren</symbol>

-or

-<symbol>IncludeInferiors</symbol>.

-For 

-<symbol>ClipByChildren</symbol>,

-both source and destination windows are

-additionally clipped by all viewable 

-<symbol>InputOutput</symbol>

-children.  

-For 

-<symbol>IncludeInferiors</symbol>,

-neither source nor destination window is clipped by inferiors. 

-This will result in including subwindow contents in the source

-and drawing through subwindow boundaries of the destination.

-The use of 

-<symbol>IncludeInferiors</symbol>

-on a window of one depth with mapped

-inferiors of differing depth is not illegal, but the semantics are

-undefined by the core protocol.

-</para>

-<para>

-<!-- .LP -->

-The fill-rule defines what pixels are inside (drawn) for

-paths given in 

-<function>XFillPolygon</function>

-requests and can be set to 

-<symbol>EvenOddRule</symbol>

-or

-<symbol>WindingRule</symbol>.

-For

-<symbol>EvenOddRule</symbol>,

-a point is inside if

-an infinite ray with the point as origin crosses the path an odd number

-of times.  

-For 

-<symbol>WindingRule</symbol>,

-a point is inside if an infinite ray with the

-point as origin crosses an unequal number of clockwise and

-counterclockwise directed path segments.

-A clockwise directed path segment is one that crosses the ray from left to

-right as observed from the point.

-A counterclockwise segment is one that crosses the ray from right to left

-as observed from the point.

-The case where a directed line segment is coincident with the ray is

-uninteresting because you can simply choose a different ray that is not

-coincident with a segment.

-</para>

-<para>

-<!-- .LP -->

-For both 

-<symbol>EvenOddRule</symbol>

-and

-<symbol>WindingRule</symbol>,

-a point is infinitely small, 

-and the path is an infinitely thin line.  

-A pixel is inside if the center point of the pixel is inside

-and the center point is not on the boundary.  

-If the center point is on the boundary,

-the pixel is inside if and only if the polygon interior is immediately to

-its right (x increasing direction).  

-Pixels with centers on a horizontal edge are a special case 

-and are inside if and only if the polygon interior is immediately below 

-(y increasing direction).

-</para>

-<para>

-<!-- .LP -->

-The arc-mode controls filling in the 

-<function>XFillArcs</function>

-function and can be set to

-<symbol>ArcPieSlice</symbol>

-or

-<symbol>ArcChord</symbol>.

-For

-<symbol>ArcPieSlice</symbol>,

-the arcs are pie-slice filled.

-For

-<symbol>ArcChord</symbol>,

-the arcs are chord filled.

-</para>

-<para>

-<!-- .LP -->

-The graphics-exposure flag controls 

-<symbol>GraphicsExpose</symbol>

-event generation

-for 

-<function>XCopyArea</function>

-and 

-<function>XCopyPlane</function>

-requests (and any similar requests defined by extensions).

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a new GC that is usable on a given screen with a 

-depth of drawable, use

-<function>XCreateGC</function>.

-<indexterm><primary>Graphics context</primary><secondary>initializing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XCreateGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>GC <function>XCreateGC</function></funcdef>

-  <paramdef>Display <parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

-  <paramdef>XGCValues *<parameter>values</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-<!-- .ds Vm set using the information in the specified values structure -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>valuemask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which components in the GC are to be (Vm. 

-This argument is the bitwise inclusive OR of zero or more of the valid

-GC component mask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>values</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies any values as specified by the valuemask.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateGC</function>

-function creates a graphics context and returns a GC.

-The GC can be used with any destination drawable having the same root

-and depth as the specified drawable.

-Use with other drawables results in a

-<errorname>BadMatch</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateGC</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadDrawable</errorname>,

-<errorname>BadFont</errorname>,

-<errorname>BadMatch</errorname>,

-<errorname>BadPixmap</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To copy components from a source GC to a destination GC, use

-<function>XCopyGC</function>.

-<indexterm significance="preferred"><primary>XCopyGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XCopyGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GCsrc,<parameter> dest</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the components of the source GC.

-<!-- .ds Vm copied to the destination GC -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>valuemask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which components in the GC are to be (Vm. 

-This argument is the bitwise inclusive OR of zero or more of the valid

-GC component mask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the destination GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XCopyGC</function>

-function copies the specified components from the source GC

-to the destination GC.

-The source and destination GCs must have the same root and depth,

-or a

-<errorname>BadMatch</errorname>

-error results.

-The valuemask specifies which component to copy, as for

-<function>XCreateGC</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XCopyGC</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change the components in a given GC, use

-<function>XChangeGC</function>.

-<indexterm significance="preferred"><primary>XChangeGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XChangeGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

-  <paramdef>XGCValues<parameter> *values</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Vm changed using information in the specified values structure -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>valuemask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which components in the GC are to be (Vm. 

-This argument is the bitwise inclusive OR of zero or more of the valid

-GC component mask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>values</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies any values as specified by the valuemask.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XChangeGC</function>

-function changes the components specified by valuemask for

-the specified GC.

-The values argument contains the values to be set.

-The values and restrictions are the same as for 

-<function>XCreateGC</function>.

-Changing the clip-mask overrides any previous 

-<function>XSetClipRectangles</function>

-request on the context. 

-Changing the dash-offset or dash-list

-overrides any previous 

-<function>XSetDashes</function>

-request on the context.

-The order in which components are verified and altered is server dependent.

-If an error is generated, a subset of the components may have been altered.

-</para>

-<para>

-<!-- .LP -->

-<function>XChangeGC</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadFont</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-<errorname>BadPixmap</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain components of a given GC, use

-<function>XGetGCValues</function>.

-<indexterm significance="preferred"><primary>XGetGCValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetGCValues</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>

-  <paramdef>XGCValues<parameter> *values_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Vm returned in the values_return argument -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>valuemask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which components in the GC are to be (Vm. 

-This argument is the bitwise inclusive OR of zero or more of the valid

-GC component mask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>values_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the GC values in the specified

-<structname>XGCValues</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetGCValues</function>

-function returns the components specified by valuemask for the specified GC.

-If the valuemask contains a valid set of GC mask bits

-(<symbol>GCFunction</symbol>,

-<symbol>GCPlaneMask</symbol>,

-<symbol>GCForeground</symbol>,

-<symbol>GCBackground</symbol>,

-<symbol>GCLineWidth</symbol>,

-<symbol>GCLineStyle</symbol>,

-<symbol>GCCapStyle</symbol>,

-<symbol>GCJoinStyle</symbol>,

-<symbol>GCFillStyle</symbol>,

-<symbol>GCFillRule</symbol>,

-<symbol>GCTile</symbol>,

-<symbol>GCStipple</symbol>,

-<symbol>GCTileStipXOrigin</symbol>,

-<symbol>GCTileStipYOrigin</symbol>,

-<symbol>GCFont</symbol>,

-<symbol>GCSubwindowMode</symbol>,

-<symbol>GCGraphicsExposures</symbol>,

-<symbol>GCClipXOrigin</symbol>,

-<symbol>GCClipYOrigin</symbol>,

-<symbol>GCDashOffset</symbol>,

-or

-<symbol>GCArcMode</symbol>)

-and no error occurs,

-<function>XGetGCValues</function>

-sets the requested components in values_return and returns a nonzero status.

-Otherwise, it returns a zero status.

-Note that the clip-mask and dash-list (represented by the

-<symbol>GCClipMask</symbol>

-and 

-<symbol>GCDashList</symbol>

-bits, respectively, in the valuemask)

-cannot be requested.

-Also note that an invalid resource ID (with one or more of the three

-most significant bits set to 1) will be returned for

-<symbol>GCFont</symbol>,

-<symbol>GCTile</symbol>,

-and

-<symbol>GCStipple</symbol>

-if the component has never been explicitly set by the client.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To free a given GC, use

-<function>XFreeGC</function>.

-<indexterm significance="preferred"><primary>XFreeGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeGC</function>

-function destroys the specified GC as well as all the associated storage.

-</para>

-<para>

-<!-- .LP -->

-<function>XFreeGC</function>

-can generate a

-<errorname>BadGC</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the 

-<type>GContext</type>

-resource ID for a given GC, use 

-<function>XGContextFromGC</function>.

-<indexterm significance="preferred"><primary>XGContextFromGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>GContext <function>XGContextFromGC</function></funcdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<!-- .ds Gc for which you want the resource ID -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC (Gc.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-Xlib usually defers sending changes to the components of a GC to the server

-until a graphics function is actually called with that GC.

-This permits batching of component changes into a single server request.

-In some circumstances, however, it may be necessary for the client

-to explicitly force sending the changes to the server.

-An example might be when a protocol extension uses the GC indirectly,

-in such a way that the extension interface cannot know what GC will be used.

-To force sending GC component changes, use

-<function>XFlushGC</function>.

-<indexterm significance="preferred"><primary>XFlushGC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XFlushGC</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-</sect1>

-<sect1 id="Using_Graphics_Context_Convenience_Routines">

-<title>Using Graphics Context Convenience Routines</title>

-<!-- .XS -->

-<!-- (SN Using Graphics Context Convenience Routines  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section discusses how to set the:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Foreground, background, plane mask, or function components

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Line attributes and dashes components

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Fill style and fill rule components

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Fill tile and stipple components

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Font component

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Clip region component

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Arc mode, subwindow mode, and graphics exposure components

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Setting_the_Foreground_Background_Function_or_Plane_Mask">

-<title>Setting the Foreground, Background, Function, or Plane Mask</title>

-<!-- .XS -->

-<!-- (SN Setting the Foreground, Background, Function, or Plane Mask -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To set the foreground, background, plane mask, and function components

-for a given GC, use

-<function>XSetState</function>.

-<indexterm significance="preferred"><primary>XSetState</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetState</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>unsignedlongforeground,<parameter> background</parameter></paramdef>

-  <paramdef>int<parameter> function</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>foreground</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the foreground you want to set for the specified GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>background</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the background you want to set for the specified GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>function</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the function you want to set for the specified GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>plane_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the plane mask.

-<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetState</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the foreground of a given GC, use

-<function>XSetForeground</function>.

-<indexterm significance="preferred"><primary>XSetForeground</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetForeground</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> foreground</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>foreground</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the foreground you want to set for the specified GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetForeground</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadGC</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the background of a given GC, use

-<function>XSetBackground</function>.

-<indexterm significance="preferred"><primary>XSetBackground</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetBackground</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> background</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>background</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the background you want to set for the specified GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetBackground</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadGC</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the display function in a given GC, use

-<function>XSetFunction</function>.

-<indexterm significance="preferred"><primary>XSetFunction</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetFunction</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>int<parameter> function</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>function</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the function you want to set for the specified GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetFunction</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the plane mask of a given GC, use

-<function>XSetPlaneMask</function>.

-<indexterm significance="preferred"><primary>XSetPlaneMask</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetPlaneMask</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>plane_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the plane mask.

-<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetPlaneMask</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadGC</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Setting_the_Line_Attributes_and_Dashes">

-<title>Setting the Line Attributes and Dashes</title>

-<!-- .XS -->

-<!-- (SN Setting the Line Attributes and Dashes  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To set the line drawing components of a given GC, use

-<function>XSetLineAttributes</function>.

-<indexterm significance="preferred"><primary>XSetLineAttributes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetLineAttributes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>unsignedint<parameter> line_width</parameter></paramdef>

-  <paramdef>int<parameter> line_style</parameter></paramdef>

-  <paramdef>int<parameter> cap_style</parameter></paramdef>

-  <paramdef>int<parameter> join_style</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>line_width</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the line-width you want to set for the specified GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>line_style</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the line-style you want to set for the specified GC.

-You can pass

-<symbol>LineSolid</symbol>,

-<symbol>LineOnOffDash</symbol>,

-or

-<symbol>LineDoubleDash</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>cap_style</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the line-style and cap-style you want to set for the specified GC.

-You can pass

-<symbol>CapNotLast</symbol>,

-<symbol>CapButt</symbol>,

-<symbol>CapRound</symbol>,

-or

-<symbol>CapProjecting</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>join_style</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the line join-style you want to set for the specified GC.

-You can pass

-<symbol>JoinMiter</symbol>,

-<symbol>JoinRound</symbol>,

-or

-<symbol>JoinBevel</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetLineAttributes</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the dash-offset and dash-list for dashed line styles of a given GC, use

-<function>XSetDashes</function>.

-<indexterm significance="preferred"><primary>XSetDashes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetDashes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>int<parameter> dash_offset</parameter></paramdef>

-  <paramdef>char<parameter> dash_list[]</parameter></paramdef>

-  <paramdef>int<parameter> n</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dash_offset</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the phase of the pattern for the dashed line-style you want to set

-for the specified GC. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dash_list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the dash-list for the dashed line-style

-you want to set for the specified GC. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>n</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of elements in dash_list. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XSetDashes</function>

-function sets the dash-offset and dash-list attributes for dashed line styles

-in the specified GC.

-There must be at least one element in the specified dash_list,

-or a

-<errorname>BadValue</errorname>

-error results. 

-The initial and alternating elements (second, fourth, and so on) 

-of the dash_list are the even dashes, and

-the others are the odd dashes.

-Each element specifies a dash length in pixels.

-All of the elements must be nonzero,

-or a

-<errorname>BadValue</errorname>

-error results.

-Specifying an odd-length list is equivalent to specifying the same list

-concatenated with itself to produce an even-length list.

-</para>

-<para>

-<!-- .LP -->

-The dash-offset defines the phase of the pattern,

-specifying how many pixels into the dash-list the pattern

-should actually begin in any single graphics request.

-Dashing is continuous through path elements combined with a join-style

-but is reset to the dash-offset between each sequence of joined lines.

-</para>

-<para>

-<!-- .LP -->

-The unit of measure for dashes is the same for the ordinary coordinate system.

-Ideally, a dash length is measured along the slope of the line, but implementations

-are only required to match this ideal for horizontal and vertical lines.

-Failing the ideal semantics, it is suggested that the length be measured along the

-major axis of the line.

-The major axis is defined as the x axis for lines drawn at an angle of between

-&minus;45 and +45 degrees or between 135 and 225 degrees from the x axis.

-For all other lines, the major axis is the y axis.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetDashes</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Setting_the_Fill_Style_and_Fill_Rule_">

-<title>Setting the Fill Style and Fill Rule </title>

-<!-- .XS -->

-<!-- (SN Setting the Fill Style and Fill Rule  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To set the fill-style of a given GC, use

-<function>XSetFillStyle</function>.

-<indexterm significance="preferred"><primary>XSetFillStyle</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetFillStyle</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>int<parameter> fill_style</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>fill_style</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the fill-style you want to set for the specified GC.

-You can pass

-<symbol>FillSolid</symbol>,

-<symbol>FillTiled</symbol>,

-<symbol>FillStippled</symbol>,

-or

-<symbol>FillOpaqueStippled</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetFillStyle</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the fill-rule of a given GC, use

-<function>XSetFillRule</function>.

-<indexterm significance="preferred"><primary>XSetFillRule</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetFillRule</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>int<parameter> fill_rule</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>fill_rule</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the fill-rule you want to set for the specified GC.

-You can pass 

-<symbol>EvenOddRule</symbol>

-or

-<symbol>WindingRule</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetFillRule</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Setting_the_Fill_Tile_and_Stipple_">

-<title>Setting the Fill Tile and Stipple </title>

-<!-- .XS -->

-<!-- (SN Setting the Fill Tile and Stipple  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Some displays have hardware support for tiling or

-stippling with patterns of specific sizes.

-Tiling and stippling operations that restrict themselves to those specific

-sizes run much faster than such operations with arbitrary size patterns.

-Xlib provides functions that you can use to determine the best size, 

-tile, or stipple for the display

-as well as to set the tile or stipple shape and the tile or stipple origin.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the best size of a tile, stipple, or cursor, use

-<function>XQueryBestSize</function>.

-<indexterm significance="preferred"><primary>XQueryBestSize</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XQueryBestSize</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> class</parameter></paramdef>

-  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the class that you are interested in.

-You can pass 

-<symbol>TileShape</symbol>,

-<symbol>CursorShape</symbol>,

-or 

-<symbol>StippleShape</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>which_screen</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies any drawable on the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the width and height of the object best supported 

-by the display hardware.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryBestSize</function>

-function returns the best or closest size to the specified size.

-For 

-<symbol>CursorShape</symbol>,

-this is the largest size that can be fully displayed on the screen specified by

-which_screen.

-For 

-<symbol>TileShape</symbol>,

-this is the size that can be tiled fastest.

-For 

-<symbol>StippleShape</symbol>,

-this is the size that can be stippled fastest.

-For 

-<symbol>CursorShape</symbol>,

-the drawable indicates the desired screen.

-For 

-<symbol>TileShape</symbol>

-and 

-<symbol>StippleShape</symbol>,

-the drawable indicates the screen and possibly the window class and depth.

-An 

-<symbol>InputOnly</symbol>

-window cannot be used as the drawable for 

-<symbol>TileShape</symbol>

-or 

-<symbol>StippleShape</symbol>,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryBestSize</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadMatch</errorname>,

-and 

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the best fill tile shape, use

-<function>XQueryBestTile</function>.

-<indexterm significance="preferred"><primary>XQueryBestTile</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XQueryBestTile</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>which_screen</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies any drawable on the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the width and height of the object best supported 

-by the display hardware.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryBestTile</function>

-function returns the best or closest size, that is, the size that can be

-tiled fastest on the screen specified by which_screen.

-The drawable indicates the screen and possibly the window class and depth.

-If an 

-<symbol>InputOnly</symbol>

-window is used as the drawable, a 

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryBestTile</function>

-can generate

-<errorname>BadDrawable</errorname>

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the best stipple shape, use

-<function>XQueryBestStipple</function>.

-<indexterm significance="preferred"><primary>XQueryBestStipple</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XQueryBestStipple</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>which_screen</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies any drawable on the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the width and height of the object best supported 

-by the display hardware.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryBestStipple</function>

-function returns the best or closest size, that is, the size that can be

-stippled fastest on the screen specified by which_screen.

-The drawable indicates the screen and possibly the window class and depth.

-If an

-<symbol>InputOnly</symbol>

-window is used as the drawable, a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryBestStipple</function>

-can generate

-<errorname>BadDrawable</errorname>

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the fill tile of a given GC, use

-<function>XSetTile</function>.

-<indexterm significance="preferred"><primary>XSetTile</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetTile</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>Pixmap<parameter> tile</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>tile</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the fill tile you want to set for the specified GC. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The tile and GC must have the same depth,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetTile</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadPixmap</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the stipple of a given GC, use

-<function>XSetStipple</function>.

-<indexterm significance="preferred"><primary>XSetStipple</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetStipple</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>Pixmap<parameter> stipple</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>stipple</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the stipple you want to set for the specified GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The stipple must have a depth of one,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetStipple</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadPixmap</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the tile or stipple origin of a given GC, use

-<function>XSetTSOrigin</function>.

-<indexterm significance="preferred"><primary>XSetTSOrigin</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetTSOrigin</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intts_x_origin,<parameter> ts_y_origin</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ts_x_origin</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ts_y_origin</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates of the tile and stipple origin.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-When graphics requests call for tiling or stippling,

-the parent's origin will be interpreted relative to whatever destination 

-drawable is specified in the graphics request.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetTSOrigin</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadGC</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Setting_the_Current_Font_">

-<title>Setting the Current Font </title>

-<!-- .XS -->

-<!-- (SN Setting the Current Font  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To set the current font of a given GC, use

-<function>XSetFont</function>.

-<indexterm significance="preferred"><primary>XSetFont</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetFont</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>Font<parameter> font</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetFont</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadFont</errorname>,

-and 

-<errorname>BadGC</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Setting_the_Clip_Region">

-<title>Setting the Clip Region</title>

-<!-- .XS -->

-<!-- (SN Setting the Clip Region  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set the clip-origin 

-and the clip-mask or set the clip-mask to a list of rectangles.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the clip-origin of a given GC, use

-<function>XSetClipOrigin</function>.

-<indexterm significance="preferred"><primary>XSetClipOrigin</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetClipOrigin</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>clip_x_origin</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>clip_y_origin</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates of the clip-mask origin.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The clip-mask origin is interpreted relative to the origin of whatever 

-destination drawable is specified in the graphics request.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetClipOrigin</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadGC</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the clip-mask of a given GC to the specified pixmap, use

-<function>XSetClipMask</function>.

-<indexterm significance="preferred"><primary>XSetClipMask</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetClipMask</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pixmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the pixmap or

-<symbol>None</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If the clip-mask is set to

-<symbol>None</symbol>,

-the pixels are always drawn (regardless of the clip-origin).

-</para>

-<para>

-<!-- .LP -->

-<function>XSetClipMask</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadPixmap</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the clip-mask of a given GC to the specified list of rectangles, use

-<function>XSetClipRectangles</function>.

-<indexterm significance="preferred"><primary>XSetClipRectangles</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetClipRectangles</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>

-  <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>

-  <paramdef>int<parameter> n</parameter></paramdef>

-  <paramdef>int<parameter> ordering</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>clip_x_origin</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>clip_y_origin</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates of the clip-mask origin.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rectangles</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of rectangles that define the clip-mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>n</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of rectangles. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ordering</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the ordering relations on the rectangles.

-You can pass

-<symbol>Unsorted</symbol>,

-<symbol>YSorted</symbol>,

-<symbol>YXSorted</symbol>,

-or

-<symbol>YXBanded</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetClipRectangles</function>

-function changes the clip-mask in the specified GC 

-to the specified list of rectangles and sets the clip origin.

-The output is clipped to remain contained within the

-rectangles.

-The clip-origin is interpreted relative to the origin of

-whatever destination drawable is specified in a graphics request.  

-The rectangle coordinates are interpreted relative to the clip-origin.  

-The rectangles should be nonintersecting, or the graphics results will be

-undefined.

-Note that the list of rectangles can be empty, 

-which effectively disables output.

-This is the opposite of passing

-<symbol>None</symbol>

-as the clip-mask in

-<function>XCreateGC</function>,

-<function>XChangeGC</function>,

-and

-<function>XSetClipMask</function>.

-</para>

-<para>

-<!-- .LP -->

-If known by the client, ordering relations on the rectangles can be

-specified with the ordering argument. 

-This may provide faster operation

-by the server. 

-If an incorrect ordering is specified, the X server may generate a

-<errorname>BadMatch</errorname>

-error, but it is not required to do so.

-If no error is generated, the graphics

-results are undefined.

-<symbol>Unsorted</symbol>

-means the rectangles are in arbitrary order.

-<symbol>YSorted</symbol>

-means that the rectangles are nondecreasing in their Y origin.

-<symbol>YXSorted</symbol>

-additionally constrains 

-<symbol>YSorted</symbol>

-order in that all

-rectangles with an equal Y origin are nondecreasing in their X

-origin.  

-<symbol>YXBanded</symbol>

-additionally constrains 

-<symbol>YXSorted</symbol>

-by requiring that,

-for every possible Y scanline, all rectangles that include that

-scanline have an identical Y origins and Y extents.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetClipRectangles</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-Xlib provides a set of basic functions for performing

-region arithmetic.

-For information about these functions,

-see section 16.5.

-</para>

-</sect2>

-<sect2 id="Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure_">

-<title>Setting the Arc Mode, Subwindow Mode, and Graphics Exposure </title>

-<!-- .XS -->

-<!-- (SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To set the arc mode of a given GC, use

-<function>XSetArcMode</function>.

-<indexterm significance="preferred"><primary>XSetArcMode</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetArcMode</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>int<parameter> arc_mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arc_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the arc mode.

-You can pass

-<symbol>ArcChord</symbol>

-or

-<symbol>ArcPieSlice</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetArcMode</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the subwindow mode of a given GC, use

-<function>XSetSubwindowMode</function>.

-<indexterm significance="preferred"><primary>XSetSubwindowMode</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetSubwindowMode</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>int<parameter> subwindow_mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>subwindow_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the subwindow mode.

-You can pass

-<symbol>ClipByChildren</symbol>

-or

-<symbol>IncludeInferiors</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetSubwindowMode</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the graphics-exposures flag of a given GC, use

-<function>XSetGraphicsExposures</function>.

-<indexterm significance="preferred"><primary>XSetGraphicsExposures</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetGraphicsExposures</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>Bool<parameter> graphics_exposures</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>graphics_exposures</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether you want

-<symbol>GraphicsExpose</symbol>

-and

-<symbol>NoExpose</symbol>

-events to be reported when calling

-<function>XCopyArea</function>

-and

-<function>XCopyPlane</function>

-with this GC.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XSetGraphicsExposures</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-<!-- .bp -->

-

-</para>

-</sect2>

-</sect1>

-</chapter>

+<?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="graphics_context_functions">
+<title>Graphics Context Functions</title>
+
+<para>
+A number of resources are used when performing graphics operations in X. Most information
+about performing graphics (for example, foreground color, background color, line style, and so
+on) is stored in resources called graphics contexts (GCs). Most graphics operations (see chapter
+8) take a GC as an argument. Although in theory the X protocol permits sharing of GCs between
+applications, it is expected that applications will use their own GCs when performing operations.
+Sharing of GCs is highly discouraged because the library may cache GC state.
+</para>
+<para>
+Graphics operations can be performed to either windows or pixmaps, which collectively are
+called drawables. Each drawable exists on a single screen. A GC is created for a specific screen
+and drawable depth and can only be used with drawables of matching screen and depth.
+</para>
+<para>
+This chapter discusses how to:
+</para>
+<itemizedlist>
+  <listitem><para>Manipulate graphics context/state</para></listitem>
+  <listitem><para>Use graphics context convenience functions</para></listitem>
+</itemizedlist>
+
+<sect1 id="Manipulating_Graphics_Context_State">
+<title>Manipulating Graphics Context/State</title>
+<!-- .XS -->
+<!-- (SN Manipulating Graphics Context/State  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Most attributes of graphics operations are stored in GCs.
+These include line width, line style, plane mask, foreground, background,
+tile, stipple, clipping region, end style, join style, and so on.
+Graphics operations (for example, drawing lines) use these values
+to determine the actual drawing operation.
+Extensions to X may add additional components to GCs.
+The contents of a GC are private to Xlib.
+</para>
+<para>
+<!-- .LP -->
+Xlib implements a write-back cache for all elements of a GC that are not
+resource IDs to allow Xlib to implement the transparent coalescing of changes 
+to GCs.
+For example,
+a call to
+<function>XSetForeground</function>
+of a GC followed by a call to
+<function>XSetLineAttributes</function>
+results in only a single-change GC protocol request to the server.
+GCs are neither expected nor encouraged to be shared between client 
+applications, so this write-back caching should present no problems.
+Applications cannot share GCs without external synchronization.
+Therefore,
+sharing GCs between applications is highly discouraged. 
+</para>
+<para>
+<!-- .LP -->
+To set an attribute of a GC,
+set the appropriate member of the
+<structname>XGCValues</structname>
+structure and OR in the corresponding value bitmask in your subsequent calls to
+<function>XCreateGC</function>.
+The symbols for the value mask bits and the
+<structname>XGCValues</structname>
+structure are:
+<!-- .sM -->
+</para>
+
+
+<literallayout class="monospaced">
+/* GC attribute value mask bits */
+
+#define     GCFunction              (1L&lt;&lt;0)
+#define     GCPlaneMask             (1L&lt;&lt;1)
+#define     GCForeground            (1L&lt;&lt;2)
+#define     GCBackground            (1L&lt;&lt;3)
+#define     GCLineWidth             (1L&lt;&lt;4)
+#define     GCLineStyle             (1L&lt;&lt;5)
+#define     GCCapStyle              (1L&lt;&lt;6)
+#define     GCJoinStyle             (1L&lt;&lt;7)
+#define     GCFillStyle             (1L&lt;&lt;8)
+#define     GCFillRule              (1L&lt;&lt;9)
+#define     GCTile                  (1L&lt;&lt;10)
+#define     GCStipple               (1L&lt;&lt;11)
+#define     GCTileStipXOrigin       (1L&lt;&lt;12)
+#define     GCTileStipYOrigin       (1L&lt;&lt;13)
+#define     GCFont                  (1L&lt;&lt;14)
+#define     GCSubwindowMode         (1L&lt;&lt;15)
+#define     GCGraphicsExposures     (1L&lt;&lt;16)
+#define     GCClipXOrigin           (1L&lt;&lt;17)
+#define     GCClipYOrigin           (1L&lt;&lt;18)
+#define     GCClipMask              (1L&lt;&lt;19)
+#define     GCDashOffset            (1L&lt;&lt;20)
+#define     GCDashList              (1L&lt;&lt;21)
+#define     GCArcMode               (1L&lt;&lt;22)
+</literallayout>
+
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+/* Values */
+
+typedef struct {
+     int function;                 /* logical operation */
+     unsigned long plane_mask;     /* plane mask */
+     unsigned long foreground;     /* foreground pixel */
+     unsigned long background;     /* background pixel */
+     int line_width;               /* line width (in pixels) */
+     int line_style;               /* LineSolid, LineOnOffDash, LineDoubleDash */
+     int cap_style;                /* CapNotLast, CapButt, CapRound, CapProjecting */
+     int join_style;               /* JoinMiter, JoinRound, JoinBevel */
+     int fill_style;               /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
+     int fill_rule;                /* EvenOddRule, WindingRule */
+     int arc_mode;                 /* ArcChord, ArcPieSlice */
+     Pixmap tile;                  /* tile pixmap for tiling operations */
+     Pixmap stipple;               /* stipple 1 plane pixmap for stippling */
+     int ts_x_origin;              /* offset for tile or stipple operations */
+     int ts_y_origin
+     Font font;                    /* default text font for text operations */
+     int subwindow_mode;           /* ClipByChildren, IncludeInferiors */
+     Bool graphics_exposures;      /* boolean, should exposures be generated */
+     int clip_x_origin;            /* origin for clipping */
+     int clip_y_origin;
+     Pixmap clip_mask;             /* bitmap clipping; other calls for rects */
+     int dash_offset;              /* patterned/dashed line information */
+     char dashes;
+} XGCValues;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The default GC values are:
+</para>
+<informaltable>
+  <tgroup cols='3' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <thead>
+    <row>
+      <entry>Component</entry>
+      <entry>Default</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>function</entry>
+      <entry><symbol>GXcopy</symbol></entry>
+    </row>
+    <row>
+      <entry>plane_mask</entry>
+      <entry>All ones</entry>
+    </row>
+    <row>
+      <entry>foreground</entry>
+      <entry>0</entry>
+    </row>
+    <row>
+      <entry>background</entry>
+      <entry>1</entry>
+    </row>
+    <row>
+      <entry>line_width</entry>
+      <entry>0</entry>
+    </row>
+    <row>
+      <entry>line_style</entry>
+      <entry><symbol>LineSolid</symbol></entry>
+    </row>
+    <row>
+      <entry>cap_style</entry>
+      <entry><symbol>CapButt</symbol></entry>
+    </row>
+    <row>
+      <entry>join_style</entry>
+      <entry><symbol>JoinMiter</symbol></entry>
+    </row>
+    <row>
+      <entry>fill_style</entry>
+      <entry><symbol>FillSolid</symbol></entry>
+    </row>
+    <row>
+      <entry>fill_rule</entry>
+      <entry><symbol>EvenOddRule</symbol></entry>
+    </row>
+    <row>
+      <entry>arc_mode</entry>
+      <entry><symbol>ArcPieSlice</symbol></entry>
+    </row>
+    <row>
+      <entry>tile</entry>
+      <entry>Pixmap of unspecified size filled with foreground pixel</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>(that is, client specified pixel if any, else 0)</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>(subsequent changes to foreground do not affect this pixmap)</entry>
+    </row>
+    <row>
+      <entry>stipple</entry>
+      <entry>Pixmap of unspecified size filled with ones</entry>
+    </row>
+    <row>
+      <entry>ts_x_origin</entry>
+      <entry>0</entry>
+    </row>
+    <row>
+      <entry>ts_y_origin</entry>
+      <entry>0</entry>
+    </row>
+    <row>
+      <entry>font</entry>
+      <entry>&lt;implementation dependent&gt;</entry>
+    </row>
+    <row>
+      <entry>subwindow_mode</entry>
+      <entry><symbol>ClipByChildren</symbol></entry>
+    </row>
+    <row>
+      <entry>graphics_exposures</entry>
+      <entry><symbol>True</symbol></entry>
+    </row>
+    <row>
+      <entry>clip_x_origin</entry>
+      <entry>0</entry>
+    </row>
+    <row>
+      <entry>clip_y_origin</entry>
+      <entry>0</entry>
+    </row>
+    <row>
+      <entry>clip_mask</entry>
+      <entry><symbol>None</symbol></entry>
+    </row>
+    <row>
+      <entry>dash_offset</entry>
+      <entry>0</entry>
+    </row>
+    <row>
+      <entry>dashes</entry>
+      <entry>4 (that is, the list [4, 4])</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Note that foreground and background are not set to any values likely
+to be useful in a window.
+</para>
+
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Display Functions</primary></indexterm>
+<indexterm significance="preferred"><primary>Source</primary></indexterm>
+<indexterm significance="preferred"><primary>Destination</primary></indexterm>
+The function attributes of a GC are used when you update a section of
+a drawable (the destination) with bits from somewhere else (the source).  
+The function in a GC defines how the new destination bits are to be
+computed from the source bits and the old destination bits.
+<symbol>GXcopy</symbol>
+is typically the most useful because it will work on a color display,
+but special applications may use other functions,
+particularly in concert with particular planes of a color display.
+The 16 GC functions, defined in 
+<filename class="headerfile">&lt;X11/X.h&gt;</filename>,
+<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>
+are:
+</para>
+<!-- .\" are listed in Table 5-1 along with the  -->
+<!-- .\"the associated hexadecimal code -->
+<!-- .\" and operation. -->
+<!-- .\".CP T 1 -->
+<!-- .\"Display Functions -->
+<informaltable>
+  <tgroup cols='3' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <thead>
+    <row>
+      <entry>Function Name</entry>
+      <entry>Value</entry>
+      <entry>Operation</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry><symbol>GXclear</symbol></entry>
+      <entry>0x0</entry>
+      <entry>0</entry>
+    </row>
+    <row>
+      <entry><symbol>GXand</symbol></entry>
+      <entry>0x1</entry>
+      <entry>src AND dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXandReverse</symbol></entry>
+      <entry>0x2</entry>
+      <entry>src AND NOT dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXcopy</symbol></entry>
+      <entry>0x3</entry>
+      <entry>src</entry>
+    </row>
+    <row>
+      <entry><symbol>GXandInverted</symbol></entry>
+      <entry>0x4</entry>
+      <entry>(NOT src) AND dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXnoop</symbol></entry>
+      <entry>0x5</entry>
+      <entry>dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXxor</symbol></entry>
+      <entry>0x6</entry>
+      <entry>src XOR dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXor</symbol></entry>
+      <entry>0x7</entry>
+      <entry>src OR dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXnor</symbol></entry>
+      <entry>0x8</entry>
+      <entry>(NOT src) AND (NOT dst)</entry>
+    </row>
+    <row>
+      <entry><symbol>GXequiv</symbol></entry>
+      <entry>0x9</entry>
+      <entry>(NOT src) XOR dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXinvert</symbol></entry>
+      <entry>0xa</entry>
+      <entry>NOT dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXorReverse</symbol></entry>
+      <entry>0xb</entry>
+      <entry>src OR (NOT dst)</entry>
+    </row>
+    <row>
+      <entry><symbol>GXcopyInverted</symbol></entry>
+      <entry>0xc</entry>
+      <entry>NOT src</entry>
+    </row>
+    <row>
+      <entry><symbol>GXorInverted</symbol></entry>
+      <entry>0xd</entry>
+      <entry>(NOT src) OR dst</entry>
+    </row>
+    <row>
+      <entry><symbol>GXnand</symbol></entry>
+      <entry>0xe</entry>
+      <entry>(NOT src) OR (NOT dst)</entry>
+    </row>
+    <row>
+      <entry><symbol>GXset</symbol></entry>
+      <entry>0xf</entry>
+      <entry>1</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Many graphics operations depend on either pixel values or planes in a GC.
+<indexterm><primary>Pixel value</primary></indexterm>
+The planes attribute is of type long, and it specifies which planes of the
+destination are to be modified, one bit per plane.
+<indexterm><primary>Plane</primary><secondary>mask</secondary></indexterm>
+A monochrome display has only one plane and
+will be the least significant bit of the word.
+As planes are added to the display hardware, they will occupy more
+significant bits in the plane mask.
+</para>
+<para>
+<!-- .LP -->
+In graphics operations, given a source and destination pixel, 
+the result is computed bitwise on corresponding bits of the pixels.
+That is, a Boolean operation is performed in each bit plane.  
+The plane_mask restricts the operation to a subset of planes.
+A macro constant
+<symbol>AllPlanes</symbol>
+can be used to refer to all planes of the screen simultaneously.
+The result is computed by the following:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Range checking is not performed on the values for foreground,
+background, or plane_mask.
+They are simply truncated to the appropriate
+number of bits.
+The line-width is measured in pixels and either can be greater than or equal to
+one (wide line) or can be the special value zero (thin line).
+</para>
+<para>
+<!-- .LP -->
+Wide lines are drawn centered on the path described by the graphics request.
+Unless otherwise specified by the join-style or cap-style,
+the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
+width w is a rectangle with vertices at the following real coordinates:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
+[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Here sn is the sine of the angle of the line,
+and cs is the cosine of the angle of the line.
+A pixel is part of the line and so is drawn
+if the center of the pixel is fully inside the bounding box
+(which is viewed as having infinitely thin edges).
+If the center of the pixel is exactly on the bounding box,
+it is part of the line if and only if the interior is immediately to its right
+(x increasing direction).
+Pixels with centers on a horizontal edge are a special case and are part of
+the line if and only if the interior or the boundary is immediately below 
+(y increasing direction) and the interior or the boundary is immediately
+to the right (x increasing direction).
+</para>
+<para>
+<!-- .LP -->
+Thin lines (zero line-width) are one-pixel-wide lines drawn using an
+unspecified, device-dependent algorithm.
+There are only two constraints on this algorithm. 
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If a line is drawn unclipped from [x1,y1] to [x2,y2] and
+if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
+a point [x,y] is touched by drawing the first line 
+if and only if the point [x+dx,y+dy] is touched by drawing the second line.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The effective set of points comprising a line cannot be affected by clipping.
+That is, a point is touched in a clipped line if and only if the point 
+lies inside the clipping region and the point would be touched
+by the line when drawn unclipped.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels 
+as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style 
+and join-style.
+It is recommended that this property be true for thin lines, 
+but this is not required.
+A line-width of zero may differ from a line-width of one in which pixels are
+drawn.
+This permits the use of many manufacturers' line drawing hardware,
+which may run many times faster than the more precisely specified
+wide lines.
+</para>
+<para>
+<!-- .LP -->
+In general, 
+drawing a thin line will be faster than drawing a wide line of width one.
+However, because of their different drawing algorithms,
+thin lines may not mix well aesthetically with wide lines.
+If it is desirable to obtain precise and uniform results across all displays,
+a client should always use a line-width of one rather than a line-width of zero.
+</para>
+<para>
+<!-- .LP -->
+The line-style defines which sections of a line are drawn:
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term><symbol>LineSolid</symbol></term>
+    <listitem>
+      <para>The full path of the line is drawn.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><symbol>LineDoubleDash</symbol></term>
+    <listitem>
+      <para>
+The full path of the line is drawn,
+but the even dashes are filled differently
+from the odd dashes (see fill-style) with <!-- xref -->
+<symbol>CapButt</symbol>
+style used where even and odd dashes meet.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><symbol>LineOnOffDash</symbol></term>
+    <listitem>
+      <para>
+Only the even dashes are drawn,
+and cap-style applies to 
+all internal ends of the individual dashes,
+except
+<symbol>CapNotLast</symbol>
+is treated as
+<symbol>CapButt</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+<para>
+The cap-style defines how the endpoints of a path are drawn:
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term><symbol>CapNotLast</symbol></term>
+    <listitem>
+      <para>
+This is equivalent to
+<symbol>CapButt</symbol>
+except that for a line-width of zero the final endpoint is not drawn.
+     </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><symbol>CapButt</symbol></term>
+    <listitem>
+      <para>
+The line is square at the endpoint (perpendicular to the slope of the line)
+with no projection beyond.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><symbol>CapRound</symbol></term>
+    <listitem>
+      <para>
+The line has a circular arc with the diameter equal to the line-width,
+centered on the endpoint.
+(This is equivalent to 
+<symbol>CapButt</symbol>
+for line-width of zero).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><symbol>CapProjecting</symbol></term>
+    <listitem>
+      <para>
+The line is square at the end, but the path continues beyond the endpoint
+for a distance equal to half the line-width.
+(This is equivalent to
+<symbol>CapButt</symbol>
+for line-width of zero).
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The join-style defines how corners are drawn for wide lines:
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term><symbol>JoinMiter</symbol></term>
+    <listitem>
+      <para>
+The outer edges of two lines extend to meet at an angle.
+However, if the angle is less than 11 degrees,
+then a
+<symbol>JoinBevel</symbol>
+join-style is used instead.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><symbol>JoinRound</symbol></term>
+    <listitem>
+      <para>
+The corner is a circular arc with the diameter equal to the line-width,
+centered on the joinpoint.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><symbol>JoinBevel</symbol></term>
+    <listitem>
+      <para>
+The corner has
+<symbol>CapButt</symbol>
+endpoint styles with the triangular notch filled.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+<!-- .LP -->
+For a line with coincident endpoints (x1=x2, y1=y2), 
+when the cap-style is applied to both endpoints, 
+the semantics depends on the line-width and the cap-style:
+</para>
+
+<informaltable>
+  <tgroup cols='3' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <tbody>
+    <row>
+      <entry><symbol>CapNotLast</symbol></entry>
+      <entry>thin</entry>
+      <entry>The results are device dependent,
+      but the desired effect is that nothing is drawn.</entry>
+    </row>
+    <row>
+      <entry><symbol>CapButt</symbol></entry>
+      <entry>thin</entry>
+      <entry>The results are device dependent,
+      but the desired effect is that a single pixel is drawn.</entry>
+    </row>
+    <row>
+      <entry><symbol>CapRound</symbol></entry>
+      <entry>thin</entry>
+      <entry>The results are the same as for
+      <symbol>CapButt</symbol> /thin.</entry>
+    </row>
+    <row>
+      <entry><symbol>CapProjecting</symbol></entry>
+      <entry>thin</entry>
+      <entry>The results are the same as for
+      <symbol>CapButt</symbol> /thin.</entry>
+    </row>
+    <row>
+      <entry><symbol>CapButt</symbol></entry>
+      <entry>wide</entry>
+      <entry>Nothing is drawn.</entry>
+    </row>
+    <row>
+      <entry><symbol>CapRound</symbol></entry>
+      <entry>wide</entry>
+      <entry>The closed path is a circle, centered at the endpoint, and
+      with the diameter equal to the line-width.</entry>
+    </row>
+    <row>
+      <entry><symbol>CapProjecting</symbol></entry>
+      <entry>wide</entry>
+      <entry>The closed path is a square, aligned with the coordinate axes, centered at the
+      endpoint, and with the sides equal to the line-width.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+For a line with coincident endpoints (x1=x2, y1=y2), 
+when the join-style is applied at one or both endpoints, 
+the effect is as if the line was removed from the overall path.
+However, if the total path consists of or is reduced to a single point joined
+with itself, the effect is the same as when the cap-style is applied at both
+endpoints.
+</para>
+<para>
+<!-- .LP -->
+The tile/stipple represents an infinite two-dimensional plane,
+with the tile/stipple replicated in all dimensions.
+When that plane is superimposed on the drawable
+for use in a graphics operation, the upper-left corner
+of some instance of the tile/stipple is at the coordinates within
+the drawable specified by the tile/stipple origin.
+The tile/stipple and clip origins are interpreted relative to the
+origin of whatever destination drawable is specified in a graphics
+request.
+The tile pixmap must have the same root and depth as the GC,
+or a
+<errorname>BadMatch</errorname>
+error results.
+The stipple pixmap must have depth one and must have the same root as the
+GC, or a 
+<errorname>BadMatch</errorname>
+error results.  
+For stipple operations where the fill-style is
+<symbol>FillStippled</symbol>
+but not 
+<symbol>FillOpaqueStippled</symbol>,
+the stipple pattern is tiled in a
+single plane and acts as an additional clip mask to be ANDed with the clip-mask.
+Although some sizes may be faster to use than others,
+any size pixmap can be used for tiling or stippling.
+</para>
+
+<para>
+<!-- .LP -->
+The fill-style defines the contents of the source for line, text, and
+fill requests.  
+For all text and fill requests (for example,
+<function>XDrawText</function>,
+<function>XDrawText16</function>,
+<function>XFillRectangle</function>,
+<function>XFillPolygon</function>,
+and
+<function>XFillArc</function>);
+for line requests 
+with line-style 
+<symbol>LineSolid</symbol>
+(for example,
+<function>XDrawLine</function>,
+<function>XDrawSegments</function>,
+<function>XDrawRectangle</function>,
+<function>XDrawArc</function>);
+and for the even dashes for line requests with line-style 
+<symbol>LineOnOffDash</symbol>
+or 
+<symbol>LineDoubleDash</symbol>,
+the following apply:
+</para>
+
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>FillSolid</symbol></entry>
+      <entry>Foreground</entry>
+    </row>
+    <row>
+      <entry><symbol>FillTiled</symbol></entry>
+      <entry>Tile</entry>
+    </row>
+    <row>
+      <entry><symbol>FillOpaqueStippled</symbol></entry>
+      <entry>A tile with the same width and height as stipple,
+      but with background everywhere stipple has a zero
+      and with foreground everywhere stipple has a one</entry>
+    </row>
+    <row>
+      <entry><symbol>FillStippled</symbol></entry>
+      <entry>Foreground masked by stipple</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+When drawing lines with line-style
+<symbol>LineDoubleDash</symbol>,
+the odd dashes are controlled by the fill-style in the following manner:
+</para>
+
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>FillSolid</symbol></entry>
+      <entry>Background</entry>
+    </row>
+    <row>
+      <entry><symbol>FillTiled</symbol></entry>
+      <entry>Same as for even dashes</entry>
+    </row>
+    <row>
+      <entry><symbol>FillOpaqueStippled</symbol></entry>
+      <entry>Same as for even dashes</entry>
+    </row>
+    <row>
+      <entry><symbol>FillStippled</symbol></entry>
+      <entry>Background masked by stipple</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Storing a pixmap in a GC might or might not result in a copy
+being made.
+If the pixmap is later used as the destination for a graphics request,
+the change might or might not be reflected in the GC.
+If the pixmap is used simultaneously in a graphics request both as
+a destination and as a tile or stipple,
+the results are undefined.
+</para>
+<para>
+<!-- .LP -->
+For optimum performance,
+you should draw as much as possible with the same GC 
+(without changing its components).
+The costs of changing GC components relative to using different GCs
+depend on the display hardware and the server implementation.
+It is quite likely that some amount of GC information will be
+cached in display hardware and that such hardware can only cache a small number
+of GCs.
+</para>
+<para>
+<!-- .LP -->
+The dashes value is actually a simplified form of the
+more general patterns that can be set with 
+<function>XSetDashes</function>.
+Specifying a
+value of N is equivalent to specifying the two-element list [N, N] in 
+<function>XSetDashes</function>.
+The value must be nonzero,
+or a
+<errorname>BadValue</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The clip-mask restricts writes to the destination drawable.  
+If the clip-mask is set to a pixmap,
+it must have depth one and have the same root as the GC,
+or a
+<errorname>BadMatch</errorname>
+error results.
+If clip-mask is set to
+<symbol>None</symbol>,
+the pixels are always drawn regardless of the clip origin.
+The clip-mask also can be set by calling the
+<function>XSetClipRectangles</function>
+or
+<function>XSetRegion</function>
+functions.
+Only pixels where the clip-mask has a bit set to 1 are drawn.  
+Pixels are not drawn outside the area covered by the clip-mask 
+or where the clip-mask has a bit set to 0.
+The clip-mask affects all graphics requests.
+The clip-mask does not clip sources.
+The clip-mask origin is interpreted relative to the origin of whatever
+destination drawable is specified in a graphics request.
+</para>
+<para>
+<!-- .LP -->
+You can set the subwindow-mode to
+<symbol>ClipByChildren</symbol>
+or
+<symbol>IncludeInferiors</symbol>.
+For 
+<symbol>ClipByChildren</symbol>,
+both source and destination windows are
+additionally clipped by all viewable 
+<symbol>InputOutput</symbol>
+children.  
+For 
+<symbol>IncludeInferiors</symbol>,
+neither source nor destination window is clipped by inferiors. 
+This will result in including subwindow contents in the source
+and drawing through subwindow boundaries of the destination.
+The use of 
+<symbol>IncludeInferiors</symbol>
+on a window of one depth with mapped
+inferiors of differing depth is not illegal, but the semantics are
+undefined by the core protocol.
+</para>
+<para>
+<!-- .LP -->
+The fill-rule defines what pixels are inside (drawn) for
+paths given in 
+<function>XFillPolygon</function>
+requests and can be set to 
+<symbol>EvenOddRule</symbol>
+or
+<symbol>WindingRule</symbol>.
+For
+<symbol>EvenOddRule</symbol>,
+a point is inside if
+an infinite ray with the point as origin crosses the path an odd number
+of times.  
+For 
+<symbol>WindingRule</symbol>,
+a point is inside if an infinite ray with the
+point as origin crosses an unequal number of clockwise and
+counterclockwise directed path segments.
+A clockwise directed path segment is one that crosses the ray from left to
+right as observed from the point.
+A counterclockwise segment is one that crosses the ray from right to left
+as observed from the point.
+The case where a directed line segment is coincident with the ray is
+uninteresting because you can simply choose a different ray that is not
+coincident with a segment.
+</para>
+<para>
+<!-- .LP -->
+For both 
+<symbol>EvenOddRule</symbol>
+and
+<symbol>WindingRule</symbol>,
+a point is infinitely small, 
+and the path is an infinitely thin line.  
+A pixel is inside if the center point of the pixel is inside
+and the center point is not on the boundary.  
+If the center point is on the boundary,
+the pixel is inside if and only if the polygon interior is immediately to
+its right (x increasing direction).  
+Pixels with centers on a horizontal edge are a special case 
+and are inside if and only if the polygon interior is immediately below 
+(y increasing direction).
+</para>
+<para>
+<!-- .LP -->
+The arc-mode controls filling in the 
+<function>XFillArcs</function>
+function and can be set to
+<symbol>ArcPieSlice</symbol>
+or
+<symbol>ArcChord</symbol>.
+For
+<symbol>ArcPieSlice</symbol>,
+the arcs are pie-slice filled.
+For
+<symbol>ArcChord</symbol>,
+the arcs are chord filled.
+</para>
+<para>
+<!-- .LP -->
+The graphics-exposure flag controls 
+<symbol>GraphicsExpose</symbol>
+event generation
+for 
+<function>XCopyArea</function>
+and 
+<function>XCopyPlane</function>
+requests (and any similar requests defined by extensions).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a new GC that is usable on a given screen with a 
+depth of drawable, use
+<function>XCreateGC</function>.
+<indexterm><primary>Graphics context</primary><secondary>initializing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XCreateGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreategc'>
+<funcprototype>
+  <funcdef>GC <function>XCreateGC</function></funcdef>
+  <paramdef>Display <parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+  <paramdef>XGCValues *<parameter>values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+<!-- .ds Vm set using the information in the specified values structure -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>valuemask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which components in the GC are to be (Vm. 
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>values</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies any values as specified by the valuemask.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateGC</function>
+function creates a graphics context and returns a GC.
+The GC can be used with any destination drawable having the same root
+and depth as the specified drawable.
+Use with other drawables results in a
+<errorname>BadMatch</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateGC</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadDrawable</errorname>,
+<errorname>BadFont</errorname>,
+<errorname>BadMatch</errorname>,
+<errorname>BadPixmap</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To copy components from a source GC to a destination GC, use
+<function>XCopyGC</function>.
+<indexterm significance="preferred"><primary>XCopyGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcopygc'>
+<funcprototype>
+  <funcdef><function>XCopyGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GCsrc,<parameter> dest</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the components of the source GC.
+<!-- .ds Vm copied to the destination GC -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>valuemask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which components in the GC are to be (Vm. 
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the destination GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XCopyGC</function>
+function copies the specified components from the source GC
+to the destination GC.
+The source and destination GCs must have the same root and depth,
+or a
+<errorname>BadMatch</errorname>
+error results.
+The valuemask specifies which component to copy, as for
+<function>XCreateGC</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XCopyGC</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the components in a given GC, use
+<function>XChangeGC</function>.
+<indexterm significance="preferred"><primary>XChangeGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchangegc'>
+<funcprototype>
+  <funcdef><function>XChangeGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+  <paramdef>XGCValues<parameter> *values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Vm changed using information in the specified values structure -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>valuemask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which components in the GC are to be (Vm. 
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>values</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies any values as specified by the valuemask.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeGC</function>
+function changes the components specified by valuemask for
+the specified GC.
+The values argument contains the values to be set.
+The values and restrictions are the same as for 
+<function>XCreateGC</function>.
+Changing the clip-mask overrides any previous 
+<function>XSetClipRectangles</function>
+request on the context. 
+Changing the dash-offset or dash-list
+overrides any previous 
+<function>XSetDashes</function>
+request on the context.
+The order in which components are verified and altered is server dependent.
+If an error is generated, a subset of the components may have been altered.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeGC</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadFont</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+<errorname>BadPixmap</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain components of a given GC, use
+<function>XGetGCValues</function>.
+<indexterm significance="preferred"><primary>XGetGCValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetgcvalues'>
+<funcprototype>
+  <funcdef>Status <function>XGetGCValues</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
+  <paramdef>XGCValues<parameter> *values_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Vm returned in the values_return argument -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>valuemask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which components in the GC are to be (Vm. 
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>values_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the GC values in the specified
+<structname>XGCValues</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetGCValues</function>
+function returns the components specified by valuemask for the specified GC.
+If the valuemask contains a valid set of GC mask bits
+(<symbol>GCFunction</symbol>,
+<symbol>GCPlaneMask</symbol>,
+<symbol>GCForeground</symbol>,
+<symbol>GCBackground</symbol>,
+<symbol>GCLineWidth</symbol>,
+<symbol>GCLineStyle</symbol>,
+<symbol>GCCapStyle</symbol>,
+<symbol>GCJoinStyle</symbol>,
+<symbol>GCFillStyle</symbol>,
+<symbol>GCFillRule</symbol>,
+<symbol>GCTile</symbol>,
+<symbol>GCStipple</symbol>,
+<symbol>GCTileStipXOrigin</symbol>,
+<symbol>GCTileStipYOrigin</symbol>,
+<symbol>GCFont</symbol>,
+<symbol>GCSubwindowMode</symbol>,
+<symbol>GCGraphicsExposures</symbol>,
+<symbol>GCClipXOrigin</symbol>,
+<symbol>GCClipYOrigin</symbol>,
+<symbol>GCDashOffset</symbol>,
+or
+<symbol>GCArcMode</symbol>)
+and no error occurs,
+<function>XGetGCValues</function>
+sets the requested components in values_return and returns a nonzero status.
+Otherwise, it returns a zero status.
+Note that the clip-mask and dash-list (represented by the
+<symbol>GCClipMask</symbol>
+and 
+<symbol>GCDashList</symbol>
+bits, respectively, in the valuemask)
+cannot be requested.
+Also note that an invalid resource ID (with one or more of the three
+most significant bits set to 1) will be returned for
+<symbol>GCFont</symbol>,
+<symbol>GCTile</symbol>,
+and
+<symbol>GCStipple</symbol>
+if the component has never been explicitly set by the client.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free a given GC, use
+<function>XFreeGC</function>.
+<indexterm significance="preferred"><primary>XFreeGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreegc'>
+<funcprototype>
+  <funcdef><function>XFreeGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeGC</function>
+function destroys the specified GC as well as all the associated storage.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeGC</function>
+can generate a
+<errorname>BadGC</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the 
+<type>GContext</type>
+resource ID for a given GC, use 
+<function>XGContextFromGC</function>.
+<indexterm significance="preferred"><primary>XGContextFromGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgcontextfromgc'>
+<funcprototype>
+  <funcdef>GContext <function>XGContextFromGC</function></funcdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Gc for which you want the resource ID -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC (Gc.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+Xlib usually defers sending changes to the components of a GC to the server
+until a graphics function is actually called with that GC.
+This permits batching of component changes into a single server request.
+In some circumstances, however, it may be necessary for the client
+to explicitly force sending the changes to the server.
+An example might be when a protocol extension uses the GC indirectly,
+in such a way that the extension interface cannot know what GC will be used.
+To force sending GC component changes, use
+<function>XFlushGC</function>.
+<indexterm significance="preferred"><primary>XFlushGC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xflushgc'>
+<funcprototype>
+  <funcdef>void <function>XFlushGC</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect1>
+<sect1 id="Using_Graphics_Context_Convenience_Routines">
+<title>Using Graphics Context Convenience Routines</title>
+<!-- .XS -->
+<!-- (SN Using Graphics Context Convenience Routines  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to set the:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Foreground, background, plane mask, or function components
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Line attributes and dashes components
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Fill style and fill rule components
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Fill tile and stipple components
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Font component
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Clip region component
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Arc mode, subwindow mode, and graphics exposure components
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Setting_the_Foreground_Background_Function_or_Plane_Mask">
+<title>Setting the Foreground, Background, Function, or Plane Mask</title>
+<!-- .XS -->
+<!-- (SN Setting the Foreground, Background, Function, or Plane Mask -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the foreground, background, plane mask, and function components
+for a given GC, use
+<function>XSetState</function>.
+<indexterm significance="preferred"><primary>XSetState</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetstate'>
+<funcprototype>
+  <funcdef><function>XSetState</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>unsignedlongforeground,<parameter> background</parameter></paramdef>
+  <paramdef>int<parameter> function</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>foreground</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the foreground you want to set for the specified GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>background</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the background you want to set for the specified GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>function</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the function you want to set for the specified GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>plane_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the plane mask.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetState</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the foreground of a given GC, use
+<function>XSetForeground</function>.
+<indexterm significance="preferred"><primary>XSetForeground</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetforeground'>
+<funcprototype>
+  <funcdef><function>XSetForeground</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> foreground</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>foreground</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the foreground you want to set for the specified GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetForeground</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadGC</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the background of a given GC, use
+<function>XSetBackground</function>.
+<indexterm significance="preferred"><primary>XSetBackground</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetbackground'>
+<funcprototype>
+  <funcdef><function>XSetBackground</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> background</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>background</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the background you want to set for the specified GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetBackground</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadGC</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the display function in a given GC, use
+<function>XSetFunction</function>.
+<indexterm significance="preferred"><primary>XSetFunction</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetfunction'>
+<funcprototype>
+  <funcdef><function>XSetFunction</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>int<parameter> function</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>function</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the function you want to set for the specified GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetFunction</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the plane mask of a given GC, use
+<function>XSetPlaneMask</function>.
+<indexterm significance="preferred"><primary>XSetPlaneMask</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetplanemask'>
+<funcprototype>
+  <funcdef><function>XSetPlaneMask</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>plane_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the plane mask.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetPlaneMask</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadGC</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Line_Attributes_and_Dashes">
+<title>Setting the Line Attributes and Dashes</title>
+<!-- .XS -->
+<!-- (SN Setting the Line Attributes and Dashes  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the line drawing components of a given GC, use
+<function>XSetLineAttributes</function>.
+<indexterm significance="preferred"><primary>XSetLineAttributes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetlineattributes'>
+<funcprototype>
+  <funcdef><function>XSetLineAttributes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>unsignedint<parameter> line_width</parameter></paramdef>
+  <paramdef>int<parameter> line_style</parameter></paramdef>
+  <paramdef>int<parameter> cap_style</parameter></paramdef>
+  <paramdef>int<parameter> join_style</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>line_width</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the line-width you want to set for the specified GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>line_style</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the line-style you want to set for the specified GC.
+You can pass
+<symbol>LineSolid</symbol>,
+<symbol>LineOnOffDash</symbol>,
+or
+<symbol>LineDoubleDash</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>cap_style</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the line-style and cap-style you want to set for the specified GC.
+You can pass
+<symbol>CapNotLast</symbol>,
+<symbol>CapButt</symbol>,
+<symbol>CapRound</symbol>,
+or
+<symbol>CapProjecting</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>join_style</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the line join-style you want to set for the specified GC.
+You can pass
+<symbol>JoinMiter</symbol>,
+<symbol>JoinRound</symbol>,
+or
+<symbol>JoinBevel</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetLineAttributes</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the dash-offset and dash-list for dashed line styles of a given GC, use
+<function>XSetDashes</function>.
+<indexterm significance="preferred"><primary>XSetDashes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetdashes'>
+<funcprototype>
+  <funcdef><function>XSetDashes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>int<parameter> dash_offset</parameter></paramdef>
+  <paramdef>char<parameter> dash_list[]</parameter></paramdef>
+  <paramdef>int<parameter> n</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dash_offset</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the phase of the pattern for the dashed line-style you want to set
+for the specified GC. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dash_list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the dash-list for the dashed line-style
+you want to set for the specified GC. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>n</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of elements in dash_list. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XSetDashes</function>
+function sets the dash-offset and dash-list attributes for dashed line styles
+in the specified GC.
+There must be at least one element in the specified dash_list,
+or a
+<errorname>BadValue</errorname>
+error results. 
+The initial and alternating elements (second, fourth, and so on) 
+of the dash_list are the even dashes, and
+the others are the odd dashes.
+Each element specifies a dash length in pixels.
+All of the elements must be nonzero,
+or a
+<errorname>BadValue</errorname>
+error results.
+Specifying an odd-length list is equivalent to specifying the same list
+concatenated with itself to produce an even-length list.
+</para>
+<para>
+<!-- .LP -->
+The dash-offset defines the phase of the pattern,
+specifying how many pixels into the dash-list the pattern
+should actually begin in any single graphics request.
+Dashing is continuous through path elements combined with a join-style
+but is reset to the dash-offset between each sequence of joined lines.
+</para>
+<para>
+<!-- .LP -->
+The unit of measure for dashes is the same for the ordinary coordinate system.
+Ideally, a dash length is measured along the slope of the line, but implementations
+are only required to match this ideal for horizontal and vertical lines.
+Failing the ideal semantics, it is suggested that the length be measured along the
+major axis of the line.
+The major axis is defined as the x axis for lines drawn at an angle of between
+&minus;45 and +45 degrees or between 135 and 225 degrees from the x axis.
+For all other lines, the major axis is the y axis.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetDashes</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Fill_Style_and_Fill_Rule_">
+<title>Setting the Fill Style and Fill Rule </title>
+<!-- .XS -->
+<!-- (SN Setting the Fill Style and Fill Rule  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the fill-style of a given GC, use
+<function>XSetFillStyle</function>.
+<indexterm significance="preferred"><primary>XSetFillStyle</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetfillstyle'>
+<funcprototype>
+  <funcdef><function>XSetFillStyle</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>int<parameter> fill_style</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>fill_style</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the fill-style you want to set for the specified GC.
+You can pass
+<symbol>FillSolid</symbol>,
+<symbol>FillTiled</symbol>,
+<symbol>FillStippled</symbol>,
+or
+<symbol>FillOpaqueStippled</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetFillStyle</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the fill-rule of a given GC, use
+<function>XSetFillRule</function>.
+<indexterm significance="preferred"><primary>XSetFillRule</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetfillrule'>
+<funcprototype>
+  <funcdef><function>XSetFillRule</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>int<parameter> fill_rule</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>fill_rule</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the fill-rule you want to set for the specified GC.
+You can pass 
+<symbol>EvenOddRule</symbol>
+or
+<symbol>WindingRule</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetFillRule</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Fill_Tile_and_Stipple_">
+<title>Setting the Fill Tile and Stipple </title>
+<!-- .XS -->
+<!-- (SN Setting the Fill Tile and Stipple  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some displays have hardware support for tiling or
+stippling with patterns of specific sizes.
+Tiling and stippling operations that restrict themselves to those specific
+sizes run much faster than such operations with arbitrary size patterns.
+Xlib provides functions that you can use to determine the best size, 
+tile, or stipple for the display
+as well as to set the tile or stipple shape and the tile or stipple origin.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the best size of a tile, stipple, or cursor, use
+<function>XQueryBestSize</function>.
+<indexterm significance="preferred"><primary>XQueryBestSize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerybestsize'>
+<funcprototype>
+  <funcdef>Status <function>XQueryBestSize</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> class</parameter></paramdef>
+  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the class that you are interested in.
+You can pass 
+<symbol>TileShape</symbol>,
+<symbol>CursorShape</symbol>,
+or 
+<symbol>StippleShape</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>which_screen</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies any drawable on the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the width and height of the object best supported 
+by the display hardware.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryBestSize</function>
+function returns the best or closest size to the specified size.
+For 
+<symbol>CursorShape</symbol>,
+this is the largest size that can be fully displayed on the screen specified by
+which_screen.
+For 
+<symbol>TileShape</symbol>,
+this is the size that can be tiled fastest.
+For 
+<symbol>StippleShape</symbol>,
+this is the size that can be stippled fastest.
+For 
+<symbol>CursorShape</symbol>,
+the drawable indicates the desired screen.
+For 
+<symbol>TileShape</symbol>
+and 
+<symbol>StippleShape</symbol>,
+the drawable indicates the screen and possibly the window class and depth.
+An 
+<symbol>InputOnly</symbol>
+window cannot be used as the drawable for 
+<symbol>TileShape</symbol>
+or 
+<symbol>StippleShape</symbol>,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryBestSize</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadMatch</errorname>,
+and 
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the best fill tile shape, use
+<function>XQueryBestTile</function>.
+<indexterm significance="preferred"><primary>XQueryBestTile</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerybesttile'>
+<funcprototype>
+  <funcdef>Status <function>XQueryBestTile</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>which_screen</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies any drawable on the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the width and height of the object best supported 
+by the display hardware.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryBestTile</function>
+function returns the best or closest size, that is, the size that can be
+tiled fastest on the screen specified by which_screen.
+The drawable indicates the screen and possibly the window class and depth.
+If an 
+<symbol>InputOnly</symbol>
+window is used as the drawable, a 
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryBestTile</function>
+can generate
+<errorname>BadDrawable</errorname>
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the best stipple shape, use
+<function>XQueryBestStipple</function>.
+<indexterm significance="preferred"><primary>XQueryBestStipple</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerybeststipple'>
+<funcprototype>
+  <funcdef>Status <function>XQueryBestStipple</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>which_screen</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies any drawable on the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the width and height of the object best supported 
+by the display hardware.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryBestStipple</function>
+function returns the best or closest size, that is, the size that can be
+stippled fastest on the screen specified by which_screen.
+The drawable indicates the screen and possibly the window class and depth.
+If an
+<symbol>InputOnly</symbol>
+window is used as the drawable, a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryBestStipple</function>
+can generate
+<errorname>BadDrawable</errorname>
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the fill tile of a given GC, use
+<function>XSetTile</function>.
+<indexterm significance="preferred"><primary>XSetTile</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsettile'>
+<funcprototype>
+  <funcdef><function>XSetTile</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>Pixmap<parameter> tile</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>tile</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the fill tile you want to set for the specified GC. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The tile and GC must have the same depth,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTile</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadPixmap</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the stipple of a given GC, use
+<function>XSetStipple</function>.
+<indexterm significance="preferred"><primary>XSetStipple</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetstipple'>
+<funcprototype>
+  <funcdef><function>XSetStipple</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>Pixmap<parameter> stipple</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>stipple</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the stipple you want to set for the specified GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The stipple must have a depth of one,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetStipple</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadPixmap</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the tile or stipple origin of a given GC, use
+<function>XSetTSOrigin</function>.
+<indexterm significance="preferred"><primary>XSetTSOrigin</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsettsorigin'>
+<funcprototype>
+  <funcdef><function>XSetTSOrigin</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intts_x_origin,<parameter> ts_y_origin</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ts_x_origin</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ts_y_origin</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates of the tile and stipple origin.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When graphics requests call for tiling or stippling,
+the parent's origin will be interpreted relative to whatever destination 
+drawable is specified in the graphics request.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTSOrigin</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadGC</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Current_Font_">
+<title>Setting the Current Font </title>
+<!-- .XS -->
+<!-- (SN Setting the Current Font  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the current font of a given GC, use
+<function>XSetFont</function>.
+<indexterm significance="preferred"><primary>XSetFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetfont'>
+<funcprototype>
+  <funcdef><function>XSetFont</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>Font<parameter> font</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetFont</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadFont</errorname>,
+and 
+<errorname>BadGC</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_the_Clip_Region">
+<title>Setting the Clip Region</title>
+<!-- .XS -->
+<!-- (SN Setting the Clip Region  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set the clip-origin 
+and the clip-mask or set the clip-mask to a list of rectangles.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the clip-origin of a given GC, use
+<function>XSetClipOrigin</function>.
+<indexterm significance="preferred"><primary>XSetClipOrigin</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetcliporigin'>
+<funcprototype>
+  <funcdef><function>XSetClipOrigin</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>clip_x_origin</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>clip_y_origin</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates of the clip-mask origin.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The clip-mask origin is interpreted relative to the origin of whatever 
+destination drawable is specified in the graphics request.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClipOrigin</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadGC</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the clip-mask of a given GC to the specified pixmap, use
+<function>XSetClipMask</function>.
+<indexterm significance="preferred"><primary>XSetClipMask</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetclipmask'>
+<funcprototype>
+  <funcdef><function>XSetClipMask</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pixmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the pixmap or
+<symbol>None</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the clip-mask is set to
+<symbol>None</symbol>,
+the pixels are always drawn (regardless of the clip-origin).
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClipMask</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadPixmap</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the clip-mask of a given GC to the specified list of rectangles, use
+<function>XSetClipRectangles</function>.
+<indexterm significance="preferred"><primary>XSetClipRectangles</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetcliprectangles'>
+<funcprototype>
+  <funcdef><function>XSetClipRectangles</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>
+  <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>
+  <paramdef>int<parameter> n</parameter></paramdef>
+  <paramdef>int<parameter> ordering</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>clip_x_origin</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>clip_y_origin</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates of the clip-mask origin.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rectangles</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of rectangles that define the clip-mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>n</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of rectangles. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ordering</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the ordering relations on the rectangles.
+You can pass
+<symbol>Unsorted</symbol>,
+<symbol>YSorted</symbol>,
+<symbol>YXSorted</symbol>,
+or
+<symbol>YXBanded</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetClipRectangles</function>
+function changes the clip-mask in the specified GC 
+to the specified list of rectangles and sets the clip origin.
+The output is clipped to remain contained within the
+rectangles.
+The clip-origin is interpreted relative to the origin of
+whatever destination drawable is specified in a graphics request.  
+The rectangle coordinates are interpreted relative to the clip-origin.  
+The rectangles should be nonintersecting, or the graphics results will be
+undefined.
+Note that the list of rectangles can be empty, 
+which effectively disables output.
+This is the opposite of passing
+<symbol>None</symbol>
+as the clip-mask in
+<function>XCreateGC</function>,
+<function>XChangeGC</function>,
+and
+<function>XSetClipMask</function>.
+</para>
+<para>
+<!-- .LP -->
+If known by the client, ordering relations on the rectangles can be
+specified with the ordering argument. 
+This may provide faster operation
+by the server. 
+If an incorrect ordering is specified, the X server may generate a
+<errorname>BadMatch</errorname>
+error, but it is not required to do so.
+If no error is generated, the graphics
+results are undefined.
+<symbol>Unsorted</symbol>
+means the rectangles are in arbitrary order.
+<symbol>YSorted</symbol>
+means that the rectangles are nondecreasing in their Y origin.
+<symbol>YXSorted</symbol>
+additionally constrains 
+<symbol>YSorted</symbol>
+order in that all
+rectangles with an equal Y origin are nondecreasing in their X
+origin.  
+<symbol>YXBanded</symbol>
+additionally constrains 
+<symbol>YXSorted</symbol>
+by requiring that,
+for every possible Y scanline, all rectangles that include that
+scanline have an identical Y origins and Y extents.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClipRectangles</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+Xlib provides a set of basic functions for performing
+region arithmetic.
+For information about these functions,
+see section 16.5.
+</para>
+</sect2>
+<sect2 id="Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure_">
+<title>Setting the Arc Mode, Subwindow Mode, and Graphics Exposure </title>
+<!-- .XS -->
+<!-- (SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To set the arc mode of a given GC, use
+<function>XSetArcMode</function>.
+<indexterm significance="preferred"><primary>XSetArcMode</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetarcmode'>
+<funcprototype>
+  <funcdef><function>XSetArcMode</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>int<parameter> arc_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arc_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the arc mode.
+You can pass
+<symbol>ArcChord</symbol>
+or
+<symbol>ArcPieSlice</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetArcMode</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the subwindow mode of a given GC, use
+<function>XSetSubwindowMode</function>.
+<indexterm significance="preferred"><primary>XSetSubwindowMode</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetsubwindowmode'>
+<funcprototype>
+  <funcdef><function>XSetSubwindowMode</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>int<parameter> subwindow_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>subwindow_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the subwindow mode.
+You can pass
+<symbol>ClipByChildren</symbol>
+or
+<symbol>IncludeInferiors</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetSubwindowMode</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the graphics-exposures flag of a given GC, use
+<function>XSetGraphicsExposures</function>.
+<indexterm significance="preferred"><primary>XSetGraphicsExposures</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetgraphicsexposures'>
+<funcprototype>
+  <funcdef><function>XSetGraphicsExposures</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>Bool<parameter> graphics_exposures</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>graphics_exposures</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether you want
+<symbol>GraphicsExpose</symbol>
+and
+<symbol>NoExpose</symbol>
+events to be reported when calling
+<function>XCopyArea</function>
+and
+<function>XCopyPlane</function>
+with this GC.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XSetGraphicsExposures</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH08.xml b/libX11/specs/libX11/CH08.xml
index 6cd6679f2..3d69b1420 100644
--- a/libX11/specs/libX11/CH08.xml
+++ b/libX11/specs/libX11/CH08.xml
@@ -1,5966 +1,5966 @@
-<?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="graphics_functions">

-<title>Graphics Functions</title>

-<para>

-Once you have established a connection to a display, you can use the Xlib graphics functions to:

-</para>

-<itemizedlist>

-  <listitem><para>Clear and copy areas</para></listitem>

-  <listitem><para>Draw points, lines, rectangles, and arcs</para></listitem>

-  <listitem><para>Fill areas</para></listitem>

-  <listitem><para>Manipulate fonts</para></listitem>

-  <listitem><para>Draw text</para></listitem>

-  <listitem><para>Transfer images between clients and the server</para></listitem>

-</itemizedlist>

-<para>

-If the same drawable and GC is used for each call, Xlib batches back-to-back

-calls to XDrawPoint, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle.

-Note that this reduces the total number of requests sent to the server.

-</para>

-<sect1 id="Clearing_Areas">

-<title>Clearing Areas</title>

-<!-- .XS -->

-<!-- (SN Clearing Areas  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to clear an area or the entire window.

-Because pixmaps do not have defined backgrounds, 

-they cannot be filled by using the functions described in this section.

-Instead, to accomplish an analogous operation on a pixmap,

-you should use 

-<function>XFillRectangle</function>,

-which sets the pixmap to a known value.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To clear a rectangular area of a given window, use

-<function>XClearArea</function>.

-<indexterm><primary>Areas</primary><secondary>clearing</secondary></indexterm>

-<indexterm><primary>Clearing</primary><secondary>areas</secondary></indexterm>

-<indexterm significance="preferred"><primary>XClearArea</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XClearArea</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>Bool<parameter> exposures</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-<!-- .ds Xy , which are relative to the origin of the window \ -->

-and specify the upper-left corner of the rectangle

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which are the dimensions of the rectangle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>exposures</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates if

-<symbol>Expose</symbol>

-events are to be generated.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XClearArea</function>

-function paints a rectangular area in the specified window according to the

-specified dimensions with the window's background pixel or pixmap.

-The subwindow-mode effectively is

-<symbol>ClipByChildren</symbol>.

-If width is zero, it

-is replaced with the current width of the window minus x.

-If height is

-zero, it is replaced with the current height of the window minus y.

-If the window has a defined background tile, 

-the rectangle clipped by any children is filled with this tile.

-If the window has

-background 

-<symbol>None</symbol>,

-the contents of the window are not changed.  

-In either

-case, if exposures is 

-<symbol>True</symbol>,

-one or more 

-<symbol>Expose</symbol>

-events are generated for regions of the rectangle that are either visible or are

-being retained in a backing store.

-If you specify a window whose class is

-<symbol>InputOnly</symbol>,

-a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XClearArea</function>

-can generate

-<errorname>BadMatch</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To clear the entire area in a given window, use

-<function>XClearWindow</function>.

-<indexterm><primary>Window</primary><secondary>clearing</secondary></indexterm>

-<indexterm><primary>Clearing</primary><secondary>windows</secondary></indexterm>

-<indexterm significance="preferred"><primary>XClearWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XClearWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XClearWindow</function>

-function clears the entire area in the specified window and is

-equivalent to

-<function>XClearArea</function>

-(display, w, 0, 0, 0, 0, 

-<symbol>False</symbol>).

-If the window has a defined background tile, the rectangle is tiled with a

-plane-mask of all ones and 

-<symbol>GXcopy</symbol>

-function.

-If the window has

-background 

-<symbol>None</symbol>,

-the contents of the window are not changed.  

-If you specify a window whose class is

-<symbol>InputOnly</symbol>,

-a

-<errorname>BadMatch</errorname>

-error results. 

-</para>

-<para>

-<!-- .LP -->

-<function>XClearWindow</function>

-can generate

-<errorname>BadMatch</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Copying_Areas">

-<title>Copying Areas</title>

-<!-- .XS -->

-<!-- (SN Copying Areas  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to copy an area or a bit plane.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To copy an area between drawables of the same

-root and depth, use

-<function>XCopyArea</function>.

-<indexterm><primary>Areas</primary><secondary>copying</secondary></indexterm>

-<indexterm><primary>Copying</primary><secondary>areas</secondary></indexterm>

-<indexterm significance="preferred"><primary>XCopyArea</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XCopyArea</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the source and destination rectangles to be combined. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates, 

-which are relative to the origin of the source rectangle

-and specify its upper-left corner.

-<!-- .ds Wh , which are the dimensions of both the source \ -->

-and destination rectangles

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->

-and specify its upper-left corner

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Dx. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCopyArea</function>

-function combines the specified rectangle of src with the specified rectangle 

-of dest.

-The drawables must have the same root and depth,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-If regions of the source rectangle are obscured and have not been

-retained in backing store 

-or if regions outside the boundaries of the source drawable are specified, 

-those regions are not copied. 

-Instead, the 

-following occurs on all corresponding destination regions that are either

-visible or are retained in backing store.  

-If the destination is a window with a background other than 

-<symbol>None</symbol>,

-corresponding regions

-of the destination are tiled with that background

-(with plane-mask of all ones and

-<symbol>GXcopy</symbol>

-function).

-Regardless of tiling or whether the destination is a window or a pixmap,

-if graphics-exposures is 

-<symbol>True</symbol>,

-then

-<symbol>GraphicsExpose</symbol>

-events for all corresponding destination regions are generated.

-If graphics-exposures is 

-<symbol>True</symbol>

-but no

-<symbol>GraphicsExpose</symbol>

-events are generated, a

-<symbol>NoExpose</symbol>

-event is generated.

-Note that by default graphics-exposures is

-<symbol>True</symbol>

-in new GCs.

-</para>

-<para>

-<!-- .LP -->

-This function uses these GC components: function, plane-mask, 

-subwindow-mode, graphics-exposures, clip-x-origin,

-clip-y-origin, and clip-mask.

-</para>

-<para>

-<!-- .LP -->

-<function>XCopyArea</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To copy a single bit plane of a given drawable, use

-<function>XCopyPlane</function>.

-<indexterm><primary>Plane</primary><secondary>copying</secondary></indexterm>

-<indexterm><primary>Copying</primary><secondary>planes</secondary></indexterm>

-<indexterm significance="preferred"><primary>XCopyPlane</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XCopyPlane</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> plane</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the source and destination rectangles to be combined. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates, 

-which are relative to the origin of the source rectangle

-and specify its upper-left corner.

-<!-- .ds Wh , which are the dimensions of both the source and destination rectangles -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->

-and specify its upper-left corner

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Dx. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>plane</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the bit plane.

-You must set exactly one bit to 1.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCopyPlane</function>

-function uses a single bit plane of the specified source rectangle

-combined with the specified GC to modify the specified rectangle of dest.

-The drawables must have the same root but need not have the same depth.

-If the drawables do not have the same root, a

-<errorname>BadMatch</errorname>

-error results.

-If plane does not have exactly one bit set to 1 and the value of plane

-is not less than %2 sup n%, where <emphasis remap='I'>n</emphasis> is the depth of src, a

-<errorname>BadValue</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-Effectively, 

-<function>XCopyPlane</function>

-forms a pixmap of the same depth as the rectangle of dest and with a

-size specified by the source region. 

-It uses the foreground/background pixels in the GC (foreground

-everywhere the bit plane in src contains a bit set to 1,

-background everywhere the bit plane in src contains a bit set to 0)

-and the equivalent of a 

-<systemitem>CopyArea</systemitem>

-protocol request is performed with all the same exposure semantics.

-This can also be thought of as using the specified region of the source 

-bit plane as a stipple with a fill-style of

-<symbol>FillOpaqueStippled</symbol>

-for filling a rectangular area of the destination.

-</para>

-<para>

-<!-- .LP -->

-This function uses these GC components: function, plane-mask, foreground,

-background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,

-and clip-mask.

-</para>

-<para>

-<!-- .LP -->

-<function>XCopyPlane</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and 

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Drawing_Points_Lines_Rectangles_and_Arcs">

-<title>Drawing Points, Lines, Rectangles, and Arcs</title>

-<!-- .XS -->

-<!-- (SN Drawing Points, Lines, Rectangles, and Arcs  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to draw:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-A single point or multiple points

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A single line or multiple lines

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A single rectangle or multiple rectangles

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A single arc or multiple arcs

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Some of the functions described in the following sections

-use these structures:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XSegment</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i -->

-<!-- .ta .5i -->

-typedef struct {

-     short x1, y1, x2, y2;

-} XSegment;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>XPoint</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i -->

-<!-- .ta .5i -->

-typedef struct {

-     short x, y;

-} XPoint;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>XRectangle</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i -->

-<!-- .ta .5i -->

-typedef struct {

-     short x, y;

-     unsigned short width, height;

-} XRectangle;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>XArc</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     short x, y;

-     unsigned short width, height;

-     short angle1, angle2;             /* Degrees * 64 */

-} XArc;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-All x and y members are signed integers.

-The width and height members are 16-bit unsigned integers.

-You should be careful not to generate coordinates and sizes

-out of the 16-bit ranges, because the protocol only has 16-bit fields

-for these values.

-</para>

-<sect2 id="Drawing_Single_and_Multiple_Points">

-<title>Drawing Single and Multiple Points</title>

-<!-- .XS -->

-<!-- (SN Drawing Single and Multiple Points  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Points</primary><secondary>drawing</secondary></indexterm>

-<indexterm><primary>Drawing</primary><secondary>points</secondary></indexterm>

-<indexterm><primary>XDrawPoints</primary></indexterm>

-<indexterm><primary>XDrawPoint</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-To draw a single point in a given drawable, use

-<function>XDrawPoint</function>.

-<indexterm significance="preferred"><primary>XDrawPoint</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawPoint</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates where you want the point drawn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw multiple points in a given drawable, use

-<function>XDrawPoints</function>.

-<indexterm significance="preferred"><primary>XDrawPoints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawPoints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XPoint<parameter> *points</parameter></paramdef>

-  <paramdef>int<parameter> npoints</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>points</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of points.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>npoints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of points in the array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the coordinate mode. 

-You can pass

-<symbol>CoordModeOrigin</symbol>

-or

-<symbol>CoordModePrevious</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDrawPoint</function>

-function uses the foreground pixel and function components of the

-GC to draw a single point into the specified drawable; 

-<function>XDrawPoints</function>

-draws multiple points this way.

-<symbol>CoordModeOrigin</symbol>

-treats all coordinates as relative to the origin,

-and

-<symbol>CoordModePrevious</symbol>

-treats all coordinates after the first as relative to the previous point.

-<function>XDrawPoints</function>

-draws the points in the order listed in the array.

-</para>

-<para>

-<!-- .LP -->

-Both functions use these GC components: function, plane-mask,

-foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

-</para>

-<para>

-<!-- .LP -->

-<function>XDrawPoint</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and 

-<errorname>BadMatch</errorname>

-errors.

-<function>XDrawPoints</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Drawing_Single_and_Multiple_Lines">

-<title>Drawing Single and Multiple Lines</title>

-<!-- .XS -->

-<!-- (SN Drawing Single and Multiple Lines -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Lines</primary><secondary>drawing</secondary></indexterm>

-<indexterm><primary>Drawing</primary><secondary>lines</secondary></indexterm>

-<indexterm><primary>XDrawLine</primary></indexterm>

-<indexterm><primary>XDrawLines</primary></indexterm>

-<indexterm><primary>Polygons</primary><secondary>drawing</secondary></indexterm>

-<indexterm><primary>Drawing</primary><secondary>polygons</secondary></indexterm>

-<indexterm><primary>XDrawSegments</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-To draw a single line between two points in a given drawable, use

-<function>XDrawLine</function>.

-<indexterm significance="preferred"><primary>XDrawLine</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawLine</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx1,y1,x2,<parameter> y2</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x1</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y1</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x2</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y2</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the points (x1, y1) and (x2, y2) to be connected.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw multiple lines in a given drawable, use

-<function>XDrawLines</function>.

-<indexterm significance="preferred"><primary>XDrawLines</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawLines</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XPoint<parameter> *points</parameter></paramdef>

-  <paramdef>int<parameter> npoints</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>points</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of points.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>npoints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of points in the array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the coordinate mode. 

-You can pass

-<symbol>CoordModeOrigin</symbol>

-or

-<symbol>CoordModePrevious</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw multiple, unconnected lines in a given drawable,

-use

-<function>XDrawSegments</function>.

-<indexterm significance="preferred"><primary>XDrawSegments</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawSegments</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XSegment<parameter> *segments</parameter></paramdef>

-  <paramdef>int<parameter> nsegments</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>segments</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of segments.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nsegments</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of segments in the array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDrawLine</function>

-function uses the components of the specified GC to

-draw a line between the specified set of points (x1, y1) and (x2, y2).

-It does not perform joining at coincident endpoints.

-For any given line, 

-<function>XDrawLine</function>

-does not draw a pixel more than once.

-If lines intersect, the intersecting pixels are drawn multiple times.  

-</para>

-<para>

-<!-- .LP -->

-The

-<function>XDrawLines</function>

-function uses the components of the specified GC to draw 

-npoints-1 lines between each pair of points (point[i], point[i+1]) 

-in the array of

-<structname>XPoint</structname>

-structures.

-It draws the lines in the order listed in the array.

-The lines join correctly at all intermediate points, and if the first and last

-points coincide, the first and last lines also join correctly.

-For any given line, 

-<function>XDrawLines</function>

-does not draw a pixel more than once.

-If thin (zero line-width) lines intersect, 

-the intersecting pixels are drawn multiple times.

-If wide lines intersect, the intersecting pixels are drawn only once, as though

-the entire 

-<systemitem>PolyLine</systemitem>

-protocol request were a single, filled shape.

-<symbol>CoordModeOrigin</symbol>

-treats all coordinates as relative to the origin,

-and

-<symbol>CoordModePrevious</symbol>

-treats all coordinates after the first as relative to the previous point.

-</para>

-<para>

-<!-- .LP -->

-The

-<function>XDrawSegments</function>

-function draws multiple, unconnected lines. 

-For each segment, 

-<function>XDrawSegments</function>

-draws a

-line between (x1, y1) and (x2, y2).

-It draws the lines in the order listed in the array of

-<structname>XSegment</structname>

-structures and does not perform joining at coincident endpoints.

-For any given line, 

-<function>XDrawSegments</function>

-does not draw a pixel more than once.  

-If lines intersect, the intersecting pixels are drawn multiple times.  

-</para>

-<para>

-<!-- .LP -->

-All three functions use these GC components:

-function, plane-mask, line-width,

-line-style, cap-style, fill-style, subwindow-mode,

-clip-x-origin, clip-y-origin, and clip-mask.

-The

-<function>XDrawLines</function>

-function also uses the join-style GC component.

-All three functions also use these GC mode-dependent components:

-foreground, background, tile, stipple, tile-stipple-x-origin, 

-tile-stipple-y-origin, dash-offset, and dash-list.

-</para>

-<para>

-<!-- .LP -->

-<function>XDrawLine</function>,

-<function>XDrawLines</function>,

-and

-<function>XDrawSegments</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-<function>XDrawLines</function>

-also can generate

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Drawing_Single_and_Multiple_Rectangles_">

-<title>Drawing Single and Multiple Rectangles </title>

-<!-- .XS -->

-<!-- (SN Drawing Single and Multiple Rectangles  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Rectangles</primary><secondary>drawing</secondary></indexterm>

-<indexterm><primary>Drawing</primary><secondary>rectangles</secondary></indexterm>

-<indexterm><primary>XDrawRectangle</primary></indexterm>

-<indexterm><primary>XDrawRectangles</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-To draw the outline of a single rectangle in a given drawable, use

-<function>XDrawRectangle</function>.

-<indexterm significance="preferred"><primary>XDrawRectangle</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawRectangle</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which specify the upper-left corner of the rectangle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which specify the dimensions of the rectangle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw the outline of multiple rectangles

-in a given drawable, use

-<function>XDrawRectangles</function>.

-<indexterm significance="preferred"><primary>XDrawRectangles</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawRectangles</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>

-  <paramdef>int<parameter> nrectangles</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rectangles</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of rectangles.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nrectangles</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of rectangles in the array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDrawRectangle</function>

-and

-<function>XDrawRectangles</function>

-functions draw the outlines of the specified rectangle or rectangles as

-if a five-point 

-<systemitem>PolyLine</systemitem>

-protocol request were specified for each rectangle:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP  -->

-For the specified rectangle or rectangles, 

-these functions do not draw a pixel more than once.

-<function>XDrawRectangles</function>

-draws the rectangles in the order listed in the array.

-If rectangles intersect,

-the intersecting pixels are drawn multiple times.

-</para>

-<para>

-<!-- .LP -->

-Both functions use these GC components: 

-function, plane-mask, line-width,

-line-style, cap-style, join-style, fill-style, 

-subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

-They also use these GC mode-dependent components: 

-foreground, background, tile, stipple, tile-stipple-x-origin, 

-tile-stipple-y-origin, dash-offset, and dash-list.

-</para>

-<para>

-<!-- .LP -->

-<function>XDrawRectangle</function>

-and

-<function>XDrawRectangles</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Drawing_Single_and_Multiple_Arcs">

-<title>Drawing Single and Multiple Arcs</title>

-<!-- .XS -->

-<!-- (SN Drawing Single and Multiple Arcs  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Drawing</primary><secondary>arcs</secondary></indexterm>

-<indexterm><primary>XDrawArc</primary></indexterm>

-<indexterm><primary>Arcs</primary><secondary>drawing</secondary></indexterm>

-<indexterm><primary>XDrawArcs</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To draw a single arc in a given drawable, use

-<function>XDrawArc</function>.

-<indexterm significance="preferred"><primary>XDrawArc</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawArc</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>intangle1,<parameter> angle2</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the drawable \ -->

-and specify the upper-left corner of the bounding rectangle

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which are the major and minor axes of the arc -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>angle1</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the start of the arc relative to the three-o'clock position

-from the center, in units of degrees * 64.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>angle2</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the path and extent of the arc relative to the start of the

-arc, in units of degrees * 64.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw multiple arcs in a given drawable, use

-<function>XDrawArcs</function>.

-<indexterm significance="preferred"><primary>XDrawArcs</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawArcs</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XArc<parameter> *arcs</parameter></paramdef>

-  <paramdef>int<parameter> narcs</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arcs</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of arcs.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>narcs</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of arcs in the array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .EQ -->

-delim %%

-<!-- .EN -->

-<function>XDrawArc</function>

-draws a single circular or elliptical arc, and 

-<function>XDrawArcs</function>

-draws multiple circular or elliptical arcs.

-Each arc is specified by a rectangle and two angles.  

-The center of the circle or ellipse is the center of the

-rectangle, and the major and minor axes are specified by the width and height.

-Positive angles indicate counterclockwise motion, 

-and negative angles indicate clockwise motion.  

-If the magnitude of angle2 is greater than 360 degrees, 

-<function>XDrawArc</function>

-or 

-<function>XDrawArcs</function>

-truncates it to 360 degrees.

-</para>

-<para>

-<!-- .LP -->

-For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, 

-the origin of the major and minor axes is at 

-% [ x +^ {width over 2} , ~y +^ {height over 2}  ]%, 

-and the infinitely thin path describing the entire circle or ellipse 

-intersects the horizontal axis at % [ x, ~y +^ {height over 2}  ]% and 

-% [ x +^ width , ~y +^ { height over 2 }] %

-and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and 

-% [ x +^ { width over 2 }, ~y +^ height ]%.

-These coordinates can be fractional

-and so are not truncated to discrete coordinates.

-The path should be defined by the ideal mathematical path.  

-For a wide line with line-width lw, 

-the bounding outlines for filling are given        

-by the two infinitely thin paths consisting of all points whose perpendicular

-distance from the path of the circle/ellipse is equal to lw/2

-(which may be a fractional value).

-The cap-style and join-style are applied the same as for a line

-corresponding to the tangent of the circle/ellipse at the endpoint.

-</para>

-<para>

-<!-- .LP -->

-For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2  ]%,

-the angles must be specified

-in the effectively skewed coordinate system of the ellipse (for a

-circle, the angles and coordinate systems are identical).  The

-relationship between these angles and angles expressed in the normal

-coordinate system of the screen (as measured with a protractor) is as

-follows:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )

- * width over height right ) +^ adjust%

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The skewed-angle and normal-angle are expressed in radians (rather

-than in degrees scaled by 64) in the range % [ 0 , ~2 pi  ]% and where atan

-returns a value in the range % [ - pi over 2 , ~pi over 2  ] %

-and adjust is:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA 1i 2i -->

-<!-- .ta 1i 2i -->

-%0%     for normal-angle in the range % [ 0 , ~pi over 2  ]%

-%pi%     for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2  ]%

-%2 pi%     for normal-angle in the range % [ {3 pi} over 2 , ~2 pi  ]%

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-For any given arc, 

-<function>XDrawArc</function>

-and

-<function>XDrawArcs</function>

-do not draw a pixel more than once.  

-If two arcs join correctly and if the line-width is greater than zero 

-and the arcs intersect, 

-<function>XDrawArc</function>

-and

-<function>XDrawArcs</function>

-do not draw a pixel more than once.

-Otherwise, 

-the intersecting pixels of intersecting arcs are drawn multiple times.

-Specifying an arc with one endpoint and a clockwise extent draws the same pixels

-as specifying the other endpoint and an equivalent counterclockwise extent,

-except as it affects joins.

-</para>

-<para>

-<!-- .LP -->

-If the last point in one arc coincides with the first point in the following 

-arc, the two arcs will join correctly.  

-If the first point in the first arc coincides with the last point in the last 

-arc, the two arcs will join correctly.

-By specifying one axis to be zero, a horizontal or vertical line can be

-drawn.

-Angles are computed based solely on the coordinate system and ignore the

-aspect ratio.

-</para>

-<para>

-<!-- .LP -->

-Both functions use these GC components: 

-function, plane-mask, line-width, line-style, cap-style, join-style, 

-fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

-They also use these GC mode-dependent components: 

-foreground, background, tile, stipple, tile-stipple-x-origin, 

-tile-stipple-y-origin, dash-offset, and dash-list.

-</para>

-<para>

-<!-- .LP -->

-<function>XDrawArc</function>

-and

-<function>XDrawArcs</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Filling_Areas">

-<title>Filling Areas</title>

-<!-- .XS -->

-<!-- (SN Filling Areas  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to fill:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-A single rectangle or multiple rectangles

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A single polygon

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A single arc or multiple arcs

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Filling_Single_and_Multiple_Rectangles">

-<title>Filling Single and Multiple Rectangles</title>

-<!-- .XS -->

-<!-- (SN Filling Single and Multiple Rectangles  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Filling</primary><secondary>rectangles</secondary></indexterm>

-<indexterm><primary>XFillRectangle</primary></indexterm>

-<indexterm><primary>Rectangle</primary><secondary>filling</secondary></indexterm>

-<indexterm><primary>XFillRectangles</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To fill a single rectangular area in a given drawable, use

-<function>XFillRectangle</function>.

-<indexterm significance="preferred"><primary>XFillRectangle</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFillRectangle</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the drawable \ -->

-and specify the upper-left corner of the rectangle

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which are the dimensions of the rectangle to be filled -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To fill multiple rectangular areas in a given drawable, use

-<function>XFillRectangles</function>.

-<indexterm significance="preferred"><primary>XFillRectangles</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFillRectangles</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *rectangles</parameter></paramdef>

-  <paramdef>int<parameter> nrectangles</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rectangles</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of rectangles.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nrectangles</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of rectangles in the array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFillRectangle</function>

-and

-<function>XFillRectangles</function>

-functions fill the specified rectangle or rectangles

-as if a four-point 

-<systemitem>FillPolygon</systemitem>

-protocol request were specified for each rectangle:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-[x,y] [x+width,y] [x+width,y+height] [x,y+height]

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Each function uses the x and y coordinates,

-width and height dimensions, and GC you specify.

-</para>

-<para>

-<!-- .LP -->

-<function>XFillRectangles</function>

-fills the rectangles in the order listed in the array.  

-For any given rectangle,

-<function>XFillRectangle</function>

-and

-<function>XFillRectangles</function>

-do not draw a pixel more than once.  

-If rectangles intersect, the intersecting pixels are

-drawn multiple times.

-</para>

-<para>

-<!-- .LP -->

-Both functions use these GC components: 

-function, plane-mask, fill-style, subwindow-mode, 

-clip-x-origin, clip-y-origin, and clip-mask.

-They also use these GC mode-dependent components: 

-foreground, background, tile, stipple, tile-stipple-x-origin, 

-and tile-stipple-y-origin.

-</para>

-<para>

-<!-- .LP -->

-<function>XFillRectangle</function>

-and

-<function>XFillRectangles</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Filling_a_Single_Polygon">

-<title>Filling a Single Polygon</title>

-<!-- .XS -->

-<!-- (SN Filling a Single Polygon  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To fill a polygon area in a given drawable, use

-<function>XFillPolygon</function>.

-<indexterm><primary>Polygons</primary><secondary>filling</secondary></indexterm>

-<indexterm><primary>Filling</primary><secondary>polygon</secondary></indexterm>

-<indexterm significance="preferred"><primary>XFillPolygon</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFillPolygon</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XPoint<parameter> *points</parameter></paramdef>

-  <paramdef>int<parameter> npoints</parameter></paramdef>

-  <paramdef>int<parameter> shape</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>points</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of points.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>npoints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of points in the array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>shape</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a shape that helps the server to improve performance.

-You can pass 

-<symbol>Complex</symbol>,

-<symbol>Convex</symbol>,

-or 

-<symbol>Nonconvex</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the coordinate mode. 

-You can pass

-<symbol>CoordModeOrigin</symbol>

-or

-<symbol>CoordModePrevious</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XFillPolygon</function>

-fills the region closed by the specified path.

-The path is closed

-automatically if the last point in the list does not coincide with the

-first point.

-<function>XFillPolygon</function>

-does not draw a pixel of the region more than once.

-<symbol>CoordModeOrigin</symbol>

-treats all coordinates as relative to the origin,

-and

-<symbol>CoordModePrevious</symbol>

-treats all coordinates after the first as relative to the previous point.

-</para>

-<para>

-<!-- .LP -->

-Depending on the specified shape, the following occurs: 

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If shape is

-<symbol>Complex</symbol>,

-the path may self-intersect. 

-Note that contiguous coincident points in the path are not treated 

-as self-intersection.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If shape is

-<symbol>Convex</symbol>,

-for every pair of points inside the polygon,

-the line segment connecting them does not intersect the path.

-If known by the client,

-specifying 

-<symbol>Convex</symbol>

-can improve performance.  

-If you specify

-<symbol>Convex</symbol>

-for a path that is not convex, 

-the graphics results are undefined.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If shape is

-<symbol>Nonconvex</symbol>,

-the path does not self-intersect, but the shape is not

-wholly convex. 

-If known by the client, 

-specifying 

-<symbol>Nonconvex</symbol>

-instead of

-<symbol>Complex</symbol>

-may improve performance.  

-If you specify

-<symbol>Nonconvex</symbol>

-for a self-intersecting path, the graphics results are undefined.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The fill-rule of the GC controls the filling behavior of 

-self-intersecting polygons.

-</para>

-<para>

-<!-- .LP -->

-This function uses these GC components: 

-function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, 

-clip-y-origin, and clip-mask.

-It also uses these GC mode-dependent components: 

-foreground, background, tile, stipple, tile-stipple-x-origin, 

-and tile-stipple-y-origin.

-</para>

-<para>

-<!-- .LP -->

-<function>XFillPolygon</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Filling_Single_and_Multiple_Arcs">

-<title>Filling Single and Multiple Arcs</title>

-<!-- .XS -->

-<!-- (SN Filling Single and Multiple Arcs  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>XFillArc</primary></indexterm>

-<indexterm><primary>Arcs</primary><secondary>filling</secondary></indexterm>

-<indexterm><primary>Filling</primary><secondary>arcs</secondary></indexterm>

-To fill a single arc in a given drawable, use

-<function>XFillArc</function>.

-<indexterm significance="preferred"><primary>XFillArc</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFillArc</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>intangle1,<parameter> angle2</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the drawable \ -->

-and specify the upper-left corner of the bounding rectangle

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which are the major and minor axes of the arc -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>angle1</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the start of the arc relative to the three-o'clock position

-from the center, in units of degrees * 64.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>angle2</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the path and extent of the arc relative to the start of the

-arc, in units of degrees * 64.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To fill multiple arcs in a given drawable, use

-<function>XFillArcs</function>.

-<indexterm significance="preferred"><primary>XFillArcs</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFillArcs</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XArc<parameter> *arcs</parameter></paramdef>

-  <paramdef>int<parameter> narcs</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arcs</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of arcs.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>narcs</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of arcs in the array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-For each arc, 

-<function>XFillArc</function>

-or

-<function>XFillArcs</function>

-fills the region closed by the infinitely thin path

-described by the specified arc and, depending on the 

-arc-mode specified in the GC, one or two line segments. 

-For 

-<symbol>ArcChord</symbol>,

-the single line segment joining the endpoints of the arc is used.  

-For 

-<symbol>ArcPieSlice</symbol>,

-the two line segments joining the endpoints of the arc with the center

-point are used.  

-<function>XFillArcs</function>

-fills the arcs in the order listed in the array.  

-For any given arc,  

-<function>XFillArc</function>

-and

-<function>XFillArcs</function>

-do not draw a pixel more than once.  

-If regions intersect, 

-the intersecting pixels are drawn multiple times.

-</para>

-<para>

-<!-- .LP -->

-Both functions use these GC components: 

-function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, 

-clip-y-origin, and clip-mask.

-They also use these GC mode-dependent components: 

-foreground, background, tile, stipple, tile-stipple-x-origin, 

-and tile-stipple-y-origin.

-</para>

-<para>

-<!-- .LP -->

-<function>XFillArc</function>

-and

-<function>XFillArcs</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Font_Metrics">

-<title>Font Metrics</title>

-<!-- .XS -->

-<!-- (SN Font Metrics  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Font</primary></indexterm>

-A font is a graphical description of a set of characters that are used to 

-increase efficiency whenever a set of small, similar sized patterns are 

-repeatedly used.

-</para>

-<para>

-<!-- .LP -->

-This section discusses how to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Load and free fonts

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Obtain and free font names

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Compute character string sizes

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Compute logical extents

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Query character string sizes

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The X server loads fonts whenever a program requests a new font.

-The server can cache fonts for quick lookup.

-Fonts are global across all screens in a server.

-Several levels are possible when dealing with fonts.

-Most applications simply use 

-<function>XLoadQueryFont</function>

-to load a font and query the font metrics.

-</para>

-<para>

-<!-- .LP -->

-Characters in fonts are regarded as masks.

-Except for image text requests,

-the only pixels modified are those in which bits are set to 1 in the character.

-This means that it makes sense to draw text using stipples or tiles

-(for example, many menus gray-out unusable entries).

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-The

-<structname>XFontStruct</structname>

-structure contains all of the information for the font

-and consists of the font-specific information as well as

-a pointer to an array of

-<structname>XCharStruct</structname>

-structures for the

-characters contained in the font.

-The

-<structname>XFontStruct</structname>,

-<structname>XFontProp</structname>,

-and

-<structname>XCharStruct</structname>

-structures contain:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XCharStruct</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     short lbearing;               /* origin to left edge of raster */

-     short rbearing;               /* origin to right edge of raster */

-     short width;                  /* advance to next char's origin */

-     short ascent;                 /* baseline to top edge of raster */

-     short descent;                /* baseline to bottom edge of raster */

-     unsigned short attributes;    /* per char flags (not predefined) */

-} XCharStruct;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XFontProp</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 1i 3i -->

-<!-- .ta .5i 1i 3i -->

-typedef struct {

-     Atom     name;

-     unsigned long card32;

-} XFontProp;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XChar2b</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {     /* normal 16 bit characters are two bytes */

-    unsigned char byte1;

-    unsigned char byte2;

-} XChar2b;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XFontStruct</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     XExtData *ext_data;               /* hook for extension to hang data */

-     Font fid;                         /* Font id for this font */

-     unsigned direction;               /* hint about the direction font is painted */

-     unsigned min_char_or_byte2;       /* first character */

-     unsigned max_char_or_byte2;       /* last character */

-     unsigned min_byte1;               /* first row that exists */

-     unsigned max_byte1;               /* last row that exists */

-     Bool all_chars_exist;             /* flag if all characters have nonzero size */

-     unsigned default_char;            /* char to print for undefined character */

-     int n_properties;                 /* how many properties there are */

-     XFontProp *properties;            /* pointer to array of additional properties */

-     XCharStruct min_bounds;           /* minimum bounds over all existing char */

-     XCharStruct max_bounds;           /* maximum bounds over all existing char */

-     XCharStruct *per_char;            /* first_char to last_char information */

-     int ascent;                       /* logical extent above baseline for spacing */

-     int descent;                      /* logical descent below baseline for spacing */

-} XFontStruct;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-X supports single byte/character, two bytes/character matrix,

-and 16-bit character text operations.

-Note that any of these forms can be used with a font, but a

-single byte/character text request can only specify a single byte

-(that is, the first row of a 2-byte font).

-You should view 2-byte fonts as a two-dimensional matrix of defined

-characters: byte1 specifies the range of defined rows and

-byte2 defines the range of defined columns of the font.

-Single byte/character fonts have one row defined, and the byte2 range

-specified in the structure defines a range of characters.

-</para>

-<para>

-<!-- .LP -->

-The bounding box of a character is defined by the 

-<structname>XCharStruct</structname>

-of that character.

-When characters are absent from a font,

-the default_char is used.

-When fonts have all characters of the same size,

-only the information in the

-<structname>XFontStruct</structname>

-min and max bounds are used.

-</para>

-<para>

-<!-- .LP -->

-The members of the 

-<structname>XFontStruct</structname>

-have the following semantics:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The direction member can be either 

-<symbol>FontLeftToRight</symbol>

-or 

-<symbol>FontRightToLeft</symbol>.

-It is just a hint as to whether most 

-<structname>XCharStruct</structname>

-elements 

-have a positive 

-(<symbol>FontLeftToRight</symbol>)

-or a negative 

-(<symbol>FontRightToLeft</symbol>)

-character width 

-metric.

-The core protocol defines no support for vertical text.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2

-specifies the linear character index corresponding to the first element

-of the per_char array, and max_char_or_byte2 specifies the linear character

-index of the last element.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If either min_byte1 or max_byte1 are nonzero, both

-min_char_or_byte2 and max_char_or_byte2 are less than 256, 

-and the 2-byte character index values corresponding to the

-per_char array element N (counting from 0) are:

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<!-- .nf -->

-     byte1 = N/D + min_byte1

-<!-- .br -->

-     byte2 = N\\D + min_char_or_byte2

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<!-- .fi -->

-where:

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<!-- .nf -->

-        D = max_char_or_byte2 - min_char_or_byte2 + 1

-        / = integer division

-        \\ = integer modulus

-<!-- .fi -->

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the per_char pointer is NULL, 

-all glyphs between the first and last character indexes

-inclusive have the same information,

-as given by both min_bounds and max_bounds.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If all_chars_exist is 

-<symbol>True</symbol>,

-all characters in the per_char array have nonzero bounding boxes.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The default_char member specifies the character that will be used when an

-undefined or nonexistent character is printed.  

-The default_char is a 16-bit character (not a 2-byte character).

-For a font using 2-byte matrix format, 

-the default_char has byte1 in the most-significant byte

-and byte2 in the least significant byte.

-If the default_char itself specifies an undefined or nonexistent character, 

-no printing is performed for an undefined or nonexistent character.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The min_bounds and max_bounds members contain the most extreme values of

-each individual 

-<structname>XCharStruct</structname>

-component over all elements of this array

-(and ignore nonexistent characters).

-The bounding box of the font (the smallest

-rectangle enclosing the shape obtained by superimposing all of the

-characters at the same origin [x,y]) has its upper-left coordinate at:

-<literallayout class="monospaced">

-     [x + min_bounds.lbearing, y - max_bounds.ascent]

-</literallayout>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Its width is:

-<literallayout class="monospaced">

-     max_bounds.rbearing - min_bounds.lbearing

-</literallayout>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Its height is:

-<literallayout class="monospaced">

-     max_bounds.ascent + max_bounds.descent

-</literallayout>

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The ascent member is the logical extent of the font above the baseline that is

-used for determining line spacing.

-Specific characters may extend beyond

-this.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The descent member is the logical extent of the font at or below the

-baseline that is used for determining line spacing.

-Specific characters may extend beyond this.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the baseline is at Y-coordinate y,

-the logical extent of the font is inclusive between the Y-coordinate 

-values (y - font.ascent) and (y + font.descent - 1).

-Typically,

-the minimum interline spacing between rows of text is given

-by ascent + descent.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-For a character origin at [x,y],

-the bounding box of a character (that is, 

-the smallest rectangle that encloses the character's shape)

-described in terms of 

-<structname>XCharStruct</structname>

-components is a rectangle with its upper-left corner at:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-[x + lbearing, y - ascent]

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Its width is:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-rbearing - lbearing

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Its height is:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-ascent + descent

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The origin for the next character is defined to be:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-[x + width, y]

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The lbearing member defines the extent of the left edge of the character ink

-from the origin.

-The rbearing member defines the extent of the right edge of the character ink

-from the origin.

-The ascent member defines the extent of the top edge of the character ink

-from the origin.

-The descent member defines the extent of the bottom edge of the character ink

-from the origin.

-The width member defines the logical width of the character.

-</para>

-<para>

-<!-- .LP -->

-Note that the baseline (the y position of the character origin) 

-is logically viewed as being the scanline just below nondescending characters. 

-When descent is zero,

-only pixels with Y-coordinates less than y are drawn,

-and the origin is logically viewed as being coincident with the left edge of

-a nonkerned character. 

-When lbearing is zero,

-no pixels with X-coordinate less than x are drawn.

-Any of the

-<structname>XCharStruct</structname>

-metric members could be negative.

-If the width is negative,

-the next character will be placed to the left of the current origin.

-</para>

-<para>

-<!-- .LP -->

-The X protocol does not define the interpretation of the attributes member 

-in the

-<structname>XCharStruct</structname>

-structure.

-A nonexistent character is represented with all members of its

-<structname>XCharStruct</structname>

-set to zero.

-</para>

-<para>

-<!-- .LP -->

-A font is not guaranteed to have any properties.

-The interpretation of the property value (for example, long or unsigned long)

-must be derived from <emphasis remap='I'>a priori</emphasis> knowledge of the property. 

-A basic set of font properties is specified in the X Consortium standard

-<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.

-</para>

-<sect2 id="Loading_and_Freeing_Fonts">

-<title>Loading and Freeing Fonts</title>

-<!-- .XS -->

-<!-- (SN Loading and Freeing Fonts  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to load fonts, get font information,

-unload fonts, and free font information.

-<indexterm><primary>Fonts</primary><secondary>getting information</secondary></indexterm>

-<indexterm><primary>Fonts</primary><secondary>unloading</secondary></indexterm>

-<indexterm><primary>Fonts</primary><secondary>freeing font information</secondary></indexterm>

-A few font functions use a 

-<type>GContext</type>

-resource ID or a font ID interchangeably.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To load a given font, use

-<function>XLoadFont</function>.

-<indexterm significance="preferred"><primary>XLoadFont</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Font <function>XLoadFont</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *name</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the name of the font,

-which is a null-terminated string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLoadFont</function>

-function loads the specified font and returns its associated font ID.

-If the font name is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-When the characters ``?'' and ``*'' are used in a font name, a

-pattern match is performed and any matching font is used.

-In the pattern, 

-the ``?'' character will match any single character, 

-and the ``*'' character will match any number of characters.

-A structured format for font names is specified in the X Consortium standard 

-<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.

-If 

-<function>XLoadFont</function>

-was unsuccessful at loading the specified font, 

-a 

-<errorname>BadName</errorname>

-error results.

-Fonts are not associated with a particular screen 

-and can be stored as a component

-of any GC.

-When the font is no longer needed, call 

-<function>XUnloadFont</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XLoadFont</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadName</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return information about an available font, use

-<function>XQueryFont</function>.

-<indexterm significance="preferred"><primary>XQueryFont</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XFontStruct *<function>XQueryFont</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XID<parameter> font_ID</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_ID</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font ID or the 

-<type>GContext</type>

-ID.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryFont</function>

-function returns a pointer to the

-<structname>XFontStruct</structname>

-structure, which contains information associated with the font.

-You can query a font or the font stored in a GC.

-The font ID stored in the 

-<structname>XFontStruct</structname>

-structure will be the 

-<type>GContext</type>

-ID, and you need to be careful when using this ID in other functions

-(see

-<function>XGContextFromGC</function>).

-If the font does not exist,

-<function>XQueryFont</function>

-returns NULL.

-To free this data, use

-<function>XFreeFontInfo</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To perform a

-<function>XLoadFont</function>

-and

-<function>XQueryFont</function>

-in a single operation, use

-<function>XLoadQueryFont</function>.

-<indexterm significance="preferred"><primary>XLoadQueryFont</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XFontStruct *<function>XLoadQueryFont</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *name</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the name of the font,

-which is a null-terminated string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLoadQueryFont</function>

-function provides the most common way for accessing a font.

-<function>XLoadQueryFont</function>

-both opens (loads) the specified font and returns a pointer to the

-appropriate

-<structname>XFontStruct</structname>

-structure.

-If the font name is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-If the font does not exist,

-<function>XLoadQueryFont</function>

-returns NULL.

-</para>

-<para>

-<!-- .LP -->

-<function>XLoadQueryFont</function>

-can generate a

-<errorname>BadAlloc</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To unload the font and free the storage used by the font structure

-that was allocated by

-<function>XQueryFont</function>

-or

-<function>XLoadQueryFont</function>,

-use

-<function>XFreeFont</function>.

-<indexterm significance="preferred"><primary>XFreeFont</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeFont</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_struct</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the storage associated with the font.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XFreeFont</function>

-function deletes the association between the font resource ID and the specified 

-font and frees the

-<structname>XFontStruct</structname>

-structure.

-The font itself will be freed when no other resource references it.

-The data and the font should not be referenced again.

-</para>

-<para>

-<!-- .LP -->

-<function>XFreeFont</function>

-can generate a

-<errorname>BadFont</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return a given font property, use

-<function>XGetFontProperty</function>.

-<indexterm significance="preferred"><primary>XGetFontProperty</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XGetFontProperty</function></funcdef>

-  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

-  <paramdef>Atom<parameter> atom</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> *value_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_struct</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the storage associated with the font.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>atom</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the atom for the property name you want returned.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the value of the font property.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Given the atom for that property,

-the

-<function>XGetFontProperty</function>

-function returns the value of the specified font property. 

-<function>XGetFontProperty</function>

-also returns 

-<symbol>False</symbol>

-if the property was not defined or 

-<symbol>True</symbol>

-if it was defined.

-A set of predefined atoms exists for font properties,

-which can be found in

-<filename class="headerfile">&lt;X11/Xatom.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>

-This set contains the standard properties associated with

-a font.

-Although it is not guaranteed,

-it is likely that the predefined font properties will be present.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To unload a font that was loaded by

-<function>XLoadFont</function>,

-use

-<function>XUnloadFont</function>.

-<indexterm significance="preferred"><primary>XUnloadFont</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUnloadFont</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Font<parameter> font</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUnloadFont</function>

-function deletes the association between the font resource ID and the specified font.

-The font itself will be freed when no other resource references it.

-The font should not be referenced again.

-</para>

-<para>

-<!-- .LP -->

-<function>XUnloadFont</function>

-can generate a

-<errorname>BadFont</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Obtaining_and_Freeing_Font_Names_and_Information">

-<title>Obtaining and Freeing Font Names and Information</title>

-<!-- .XS -->

-<!-- (SN Obtaining and Freeing Font Names and Information -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-You obtain font names and information by matching a wildcard specification

-when querying a font type for a list of available sizes and so on.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return a list of the available font names, use

-<function>XListFonts</function>.

-<indexterm significance="preferred"><primary>XListFonts</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char **<function>XListFonts</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *pattern</parameter></paramdef>

-  <paramdef>int<parameter> maxnames</parameter></paramdef>

-  <paramdef>int<parameter> *actual_count_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pattern</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the null-terminated pattern string that can contain wildcard 

-characters.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>maxnames</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the maximum number of names to be returned.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>actual_count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the actual number of font names.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XListFonts</function>

-function returns an array of available font names 

-(as controlled by the font search path; see

-<function>XSetFontPath</function>)

-that match the string you passed to the pattern argument.

-The pattern string can contain any characters,

-but each asterisk (*) is a wildcard for any number of characters,

-and each question mark (?) is a wildcard for a single character.

-If the pattern string is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-Each returned string is null-terminated.

-If the data returned by the server is in the Latin Portable Character Encoding,

-then the returned strings are in the Host Portable Character Encoding.

-Otherwise, the result is implementation-dependent.

-If there are no matching font names,

-<function>XListFonts</function>

-returns NULL.

-The client should call

-<function>XFreeFontNames</function>

-when finished with the result to free the memory.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To free a font name array, use

-<function>XFreeFontNames</function>.

-<indexterm significance="preferred"><primary>XFreeFontNames</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeFontNames</function></funcdef>

-  <paramdef>char<parameter> *list[]</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the array of strings you want to free.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeFontNames</function>

-function frees the array and strings returned by

-<function>XListFonts</function>

-or

-<function>XListFontsWithInfo</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the names and information about available fonts, use

-<function>XListFontsWithInfo</function>.

-<indexterm significance="preferred"><primary>XListFontsWithInfo</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char **<function>XListFontsWithInfo</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *pattern</parameter></paramdef>

-  <paramdef>int<parameter> maxnames</parameter></paramdef>

-  <paramdef>int<parameter> *count_return</parameter></paramdef>

-  <paramdef>XFontStruct<parameter> **info_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pattern</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the null-terminated pattern string that can contain wildcard 

-characters.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>maxnames</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the maximum number of names to be returned.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the actual number of matched font names.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>info_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font information.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XListFontsWithInfo</function>

-function returns a list of font names that match the specified pattern and their

-associated font information.

-The list of names is limited to size specified by maxnames.

-The information returned for each font is identical to what

-<function>XLoadQueryFont</function>

-would return except that the per-character metrics are not returned.

-The pattern string can contain any characters,

-but each asterisk (*) is a wildcard for any number of characters,

-and each question mark (?) is a wildcard for a single character.

-If the pattern string is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-Use of uppercase or lowercase does not matter.

-Each returned string is null-terminated.

-If the data returned by the server is in the Latin Portable Character Encoding,

-then the returned strings are in the Host Portable Character Encoding.

-Otherwise, the result is implementation-dependent.

-If there are no matching font names,

-<function>XListFontsWithInfo</function>

-returns NULL.

-</para>

-<para>

-<!-- .LP -->

-To free only the allocated name array,

-the client should call

-<function>XFreeFontNames</function>.

-To free both the name array and the font information array

-or to free just the font information array,

-the client should call

-<function>XFreeFontInfo</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To free font structures and font names, use

-<function>XFreeFontInfo</function>.

-<indexterm significance="preferred"><primary>XFreeFontInfo</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeFontInfo</function></funcdef>

-  <paramdef>char<parameter> **names</parameter></paramdef>

-  <paramdef>XFontStruct<parameter> *free_info</parameter></paramdef>

-  <paramdef>int<parameter> actual_count</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>names</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the list of font names.

-

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>free_info</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font information.

-

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>actual_count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the actual number of font names.

-

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeFontInfo</function>

-function frees a font structure or an array of font structures

-and optionally an array of font names.

-If NULL is passed for names, no font names are freed.

-If a font structure for an open font (returned by

-<function>XLoadQueryFont</function>)

-is passed, the structure is freed,

-but the font is not closed; use

-<function>XUnloadFont</function>

-to close the font.

-</para>

-</sect2>

-<sect2 id="Computing_Character_String_Sizes">

-<title>Computing Character String Sizes</title>

-<!-- .XS -->

-<!-- (SN Computing Character String Sizes  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to compute the width,

-the logical extents, 

-and the server information about 8-bit and 2-byte text strings.

-<indexterm><primary>XTextWidth</primary></indexterm>

-<indexterm><primary>XTextWidth16</primary></indexterm>

-The width is computed by adding the character widths of all the characters.

-It does not matter if the font is an 8-bit or 2-byte font.

-These functions return the sum of the character metrics in pixels.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To determine the width of an 8-bit character string, use

-<function>XTextWidth</function>.

-<indexterm significance="preferred"><primary>XTextWidth</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XTextWidth</function></funcdef>

-  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_struct</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font used for the width computation.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character count in the specified string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To determine the width of a 2-byte character string, use

-<function>XTextWidth16</function>.

-<indexterm significance="preferred"><primary>XTextWidth16</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XTextWidth16</function></funcdef>

-  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

-  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_struct</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font used for the width computation.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character count in the specified string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-</sect2>

-<sect2 id="Computing_Logical_Extents">

-<title>Computing Logical Extents</title>

-<!-- .XS -->

-<!-- (SN Computing Logical Extents  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To compute the bounding box of an 8-bit character string in a given font, use

-<function>XTextExtents</function>.

-<indexterm significance="preferred"><primary>XTextExtents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XTextExtents</function></funcdef>

-  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> nchars</parameter></paramdef>

-  <paramdef>int<parameter> *direction_return</parameter></paramdef>

-  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>

-  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_struct</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XFontStruct</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>direction_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the value of the direction hint

-(<symbol>FontLeftToRight</symbol>

-or

-<symbol>FontRightToLeft</symbol>).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_ascent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font ascent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_descent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font descent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>overall_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the overall size in the specified

-<structname>XCharStruct</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To compute the bounding box of a 2-byte character string in a given font, use

-<function>XTextExtents16</function>.

-<indexterm significance="preferred"><primary>XTextExtents16</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XTextExtents16</function></funcdef>

-  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>

-  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> nchars</parameter></paramdef>

-  <paramdef>int<parameter> *direction_return</parameter></paramdef>

-  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>

-  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_struct</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XFontStruct</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>direction_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the value of the direction hint

-(<symbol>FontLeftToRight</symbol>

-or

-<symbol>FontRightToLeft</symbol>).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_ascent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font ascent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_descent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font descent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>overall_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the overall size in the specified

-<structname>XCharStruct</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XTextExtents</function>

-and

-<function>XTextExtents16</function>

-functions 

-perform the size computation locally and, thereby,

-avoid the round-trip overhead of

-<function>XQueryTextExtents</function>

-and

-<function>XQueryTextExtents16</function>.

-Both functions return an

-<structname>XCharStruct</structname>

-structure, whose members are set to the values as follows.

-</para>

-<para>

-<!-- .LP -->

-The ascent member is set to the maximum of the ascent metrics of all

-characters in the string.

-The descent member is set to the maximum of the descent metrics.

-The width member is set to the sum of the character-width metrics of all

-characters in the string.

-For each character in the string,

-let W be the sum of the character-width metrics of all characters preceding 

-it in the string.

-Let L be the left-side-bearing metric of the character plus W.

-Let R be the right-side-bearing metric of the character plus W.

-The lbearing member is set to the minimum L of all characters in the string.

-The rbearing member is set to the maximum R.

-</para>

-<para>

-<!-- .LP -->

-For fonts defined with linear indexing rather than 2-byte matrix indexing,

-each 

-<structname>XChar2b</structname>

-structure is interpreted as a 16-bit number with byte1 as the 

-most significant byte.

-If the font has no defined default character,

-undefined characters in the string are taken to have all zero metrics.

-</para>

-</sect2>

-<sect2 id="Querying_Character_String_Sizes">

-<title>Querying Character String Sizes</title>

-<!-- .XS -->

-<!-- (SN Querying Character String Sizes  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To query the server for the bounding box of an 8-bit character string in a 

-given font, use 

-<function>XQueryTextExtents</function>.

-<indexterm significance="preferred"><primary>XQueryTextExtents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XQueryTextExtents</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XID<parameter> font_ID</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> nchars</parameter></paramdef>

-  <paramdef>int<parameter> *direction_return</parameter></paramdef>

-  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>

-  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_ID</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies either the font ID or the 

-<type>GContext</type>

-ID that contains the font.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>direction_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the value of the direction hint

-(<symbol>FontLeftToRight</symbol>

-or

-<symbol>FontRightToLeft</symbol>).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_ascent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font ascent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_descent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font descent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>overall_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the overall size in the specified

-<structname>XCharStruct</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To query the server for the bounding box of a 2-byte character string

-in a given font, use

-<function>XQueryTextExtents16</function>.

-<indexterm significance="preferred"><primary>XQueryTextExtents16</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XQueryTextExtents16</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XID<parameter> font_ID</parameter></paramdef>

-  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> nchars</parameter></paramdef>

-  <paramdef>int<parameter> *direction_return</parameter></paramdef>

-  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>

-  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_ID</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies either the font ID or the 

-<type>GContext</type>

-ID that contains the font.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>direction_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the value of the direction hint

-(<symbol>FontLeftToRight</symbol>

-or

-<symbol>FontRightToLeft</symbol>).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_ascent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font ascent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_descent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the font descent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>overall_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the overall size in the specified

-<structname>XCharStruct</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryTextExtents</function>

-and

-<function>XQueryTextExtents16</function>

-functions return the bounding box of the specified 8-bit and 16-bit

-character string in the specified font or the font contained in the

-specified GC.

-These functions query the X server and, therefore, suffer the round-trip

-overhead that is avoided by

-<function>XTextExtents</function>

-and 

-<function>XTextExtents16</function>.

-Both functions return a

-<structname>XCharStruct</structname>

-structure, whose members are set to the values as follows.

-</para>

-<para>

-<!-- .LP -->

-The ascent member is set to the maximum of the ascent metrics 

-of all characters in the string.

-The descent member is set to the maximum of the descent metrics.

-The width member is set to the sum of the character-width metrics 

-of all characters in the string.

-For each character in the string,

-let W be the sum of the character-width metrics of all characters preceding

-it in the string.

-Let L be the left-side-bearing metric of the character plus W.

-Let R be the right-side-bearing metric of the character plus W.

-The lbearing member is set to the minimum L of all characters in the string.

-The rbearing member is set to the maximum R.

-</para>

-<para>

-<!-- .LP -->

-For fonts defined with linear indexing rather than 2-byte matrix indexing,

-each 

-<structname>XChar2b</structname>

-structure is interpreted as a 16-bit number with byte1 as the 

-most significant byte.

-If the font has no defined default character,

-undefined characters in the string are taken to have all zero metrics.

-</para>

-<para>

-<!-- .LP -->

-Characters with all zero metrics are ignored.

-If the font has no defined default_char,

-the undefined characters in the string are also ignored.

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryTextExtents</function>

-and

-<function>XQueryTextExtents16</function>

-can generate

-<errorname>BadFont</errorname>

-and

-<errorname>BadGC</errorname>

-errors.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Drawing_Text">

-<title>Drawing Text</title>

-<!-- .XS -->

-<!-- (SN Drawing Text -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section discusses how to draw:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Complex text 

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Text characters

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Image text characters

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The fundamental text functions

-<function>XDrawText</function>

-and

-<function>XDrawText16</function>

-use the following structures:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XTextItem</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     char *chars;     /* pointer to string */

-     int nchars;      /* number of characters */

-     int delta;       /* delta between strings */

-     Font font;       /* Font to print it in, None don't change */

-} XTextItem;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XTextItem16</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     XChar2b *chars;     /* pointer to two-byte characters */

-     int nchars;         /* number of characters */

-     int delta;         /* delta between strings */

-     Font font;         /* font to print it in, None don't change */

-} XTextItem16;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If the font member is not

-<symbol>None</symbol>,

-the font is changed before printing and also is stored in the GC.

-If an error was generated during text drawing,

-the previous items may have been drawn.

-The baseline of the characters are drawn starting at the x and y

-coordinates that you pass in the text drawing functions.

-</para>

-<para>

-<!-- .LP -->

-For example, consider the background rectangle drawn by

-<function>XDrawImageString</function>.

-If you want the upper-left corner of the background rectangle

-to be at pixel coordinate (x,y), pass the (x,y + ascent)

-as the baseline origin coordinates to the text functions.

-The ascent is the font ascent, as given in the

-<structname>XFontStruct</structname>

-structure.

-If you want the lower-left corner of the background rectangle

-to be at pixel coordinate (x,y), pass the (x,y - descent + 1)

-as the baseline origin coordinates to the text functions.

-The descent is the font descent, as given in the

-<structname>XFontStruct</structname>

-structure.

-</para>

-<sect2 id="Drawing_Complex_Text">

-<title>Drawing Complex Text</title>

-<!-- .XS -->

-<!-- (SN Drawing Complex Text  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Text</primary><secondary>drawing</secondary></indexterm>

-<indexterm><primary>Drawing</primary><secondary>text items</secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-To draw 8-bit characters in a given drawable, use

-<function>XDrawText</function>.

-<indexterm significance="preferred"><primary>XDrawText</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawText</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>XTextItem<parameter> *items</parameter></paramdef>

-  <paramdef>int<parameter> nitems</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

-and define the origin of the first character

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>items</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of text items.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nitems</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of text items in the array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw 2-byte characters in a given drawable, use

-<function>XDrawText16</function>.

-<indexterm significance="preferred"><primary>XDrawText16</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawText16</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>XTextItem16<parameter> *items</parameter></paramdef>

-  <paramdef>int<parameter> nitems</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

-and define the origin of the first character

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>items</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of text items.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nitems</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of text items in the array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDrawText16</function>

-function is similar to

-<function>XDrawText</function>

-except that it uses 2-byte or 16-bit characters.

-Both functions allow complex spacing and font shifts between counted strings.

-</para>

-<para>

-<!-- .LP -->

-Each text item is processed in turn.

-A font member other than 

-<symbol>None</symbol>

-in an item causes the font to be stored in the GC

-and used for subsequent text.  

-A text element delta specifies an additional change

-in the position along the x axis before the string is drawn. 

-The delta is always added to the character origin

-and is not dependent on any characteristics of the font.

-Each character image, as defined by the font in the GC, is treated as an

-additional mask for a fill operation on the drawable.

-The drawable is modified only where the font character has a bit set to 1.

-If a text item generates a

-<errorname>BadFont</errorname>

-error, the previous text items may have been drawn.

-</para>

-<para>

-<!-- .LP -->

-For fonts defined with linear indexing rather than 2-byte matrix indexing,

-each 

-<structname>XChar2b</structname>

-structure is interpreted as a 16-bit number with byte1 as the 

-most significant byte.

-</para>

-<para>

-<!-- .LP -->

-Both functions use these GC components:

-function, plane-mask, fill-style, font, subwindow-mode, 

-clip-x-origin, clip-y-origin, and clip-mask.

-They also use these GC mode-dependent components: 

-foreground, background, tile, stipple, tile-stipple-x-origin, 

-and tile-stipple-y-origin.

-</para>

-<para>

-<!-- .LP -->

-<function>XDrawText</function>

-and

-<function>XDrawText16</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadFont</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Drawing_Text_Characters">

-<title>Drawing Text Characters</title>

-<!-- .XS -->

-<!-- (SN Drawing Text Characters  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Strings</primary><secondary>drawing</secondary></indexterm>

-<indexterm><primary>Drawing</primary><secondary>strings</secondary></indexterm>

-To draw 8-bit characters in a given drawable, use

-<function>XDrawString</function>.

-<indexterm significance="preferred"><primary>XDrawString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawString</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

-and define the origin of the first character

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw 2-byte characters in a given drawable, use

-<function>XDrawString16</function>.

-<indexterm significance="preferred"><primary>XDrawString16</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawString16</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

-and define the origin of the first character

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Each character image, as defined by the font in the GC, is treated as an

-additional mask for a fill operation on the drawable.

-The drawable is modified only where the font character has a bit set to 1.

-For fonts defined with 2-byte matrix indexing

-and used with

-<function>XDrawString16</function>,

-each byte is used as a byte2 with a byte1 of zero.

-</para>

-<para>

-<!-- .LP -->

-Both functions use these GC components: 

-function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, 

-clip-y-origin, and clip-mask.

-They also use these GC mode-dependent components: 

-foreground, background, tile, stipple, tile-stipple-x-origin, 

-and tile-stipple-y-origin.

-</para>

-<para>

-<!-- .LP -->

-<function>XDrawString</function>

-and

-<function>XDrawString16</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Drawing_Image_Text_Characters">

-<title>Drawing Image Text Characters</title>

-<!-- .XS -->

-<!-- (SN Drawing Image Text Characters  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Image text</primary><secondary>drawing</secondary></indexterm>

-<indexterm><primary>Drawing</primary><secondary>image text</secondary></indexterm>

-Some applications, in particular terminal emulators, need to

-print image text in which both the foreground and background bits of

-each character are painted.

-This prevents annoying flicker on many displays.

-<indexterm><primary>XDrawImageString</primary></indexterm>

-<indexterm><primary>XDrawImageString16</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To draw 8-bit image text characters in a given drawable, use

-<function>XDrawImageString</function>.

-<indexterm significance="preferred"><primary>XDrawImageString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawImageString</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

-and define the origin of the first character

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw 2-byte image text characters in a given drawable, use

-<function>XDrawImageString16</function>.

-<indexterm significance="preferred"><primary>XDrawImageString16</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDrawImageString16</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>XChar2b<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->

-and define the origin of the first character

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDrawImageString16</function>

-function is similar to

-<function>XDrawImageString</function>

-except that it uses 2-byte or 16-bit characters.

-Both functions also use both the foreground and background pixels 

-of the GC in the destination.

-</para>

-<para>

-<!-- .LP -->

-The effect is first to fill a

-destination rectangle with the background pixel defined in the GC and then

-to paint the text with the foreground pixel.

-The upper-left corner of the filled rectangle is at:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-[x, y - font-ascent]

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The width is:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-overall-width

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The height is:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-font-ascent + font-descent

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The overall-width, font-ascent, and font-descent

-are as would be returned by 

-<function>XQueryTextExtents</function>

-using gc and string.

-The function and fill-style defined in the GC are ignored for these functions. 

-The effective function is 

-<symbol>GXcopy</symbol>,

-and the effective fill-style is

-<symbol>FillSolid</symbol>.

-</para>

-<para>

-<!-- .LP -->

-For fonts defined with 2-byte matrix indexing

-and used with

-<function>XDrawImageString</function>,

-each byte is used as a byte2 with a byte1 of zero.

-</para>

-<para>

-<!-- .LP -->

-Both functions use these GC components: 

-plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, 

-clip-y-origin, and clip-mask.

-</para>

-<para>

-<!-- .LP -->

-<function>XDrawImageString</function>

-and

-<function>XDrawImageString16</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect2>

-</sect1>

-<sect1 id="Transferring_Images_between_Client_and_Server">

-<title>Transferring Images between Client and Server</title>

-<!-- .XS -->

-<!-- (SN Transferring Images between Client and Server  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to transfer images between a client 

-and the server.

-Because the server may require diverse data formats, 

-Xlib provides an image object that fully describes the data in memory 

-and that provides for basic operations on that data.  

-You should reference the data 

-through the image object rather than referencing the data directly.

-However, some implementations of the Xlib library may efficiently deal with 

-frequently used data formats by replacing

-functions in the procedure vector with special case functions.

-Supported operations include destroying the image, getting a pixel,

-storing a pixel, extracting a subimage of an image, and adding a constant

-to an image (see section 16.8).

-</para>

-<para>

-<!-- .LP -->

-All the image manipulation functions discussed in this section make use of 

-the 

-<structname>XImage</structname>

-structure,

-which describes an image as it exists in the client's memory.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XImage</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 1i 3i -->

-<!-- .ta .5i 1i 3i -->

-typedef struct _XImage {

-     int width, height;         /* size of image */

-     int xoffset;               /* number of pixels offset in X direction */

-     int format;                /* XYBitmap, XYPixmap, ZPixmap */

-     char *data;                /* pointer to image data */

-     int byte_order;            /* data byte order, LSBFirst, MSBFirst */

-     int bitmap_unit;           /* quant. of scanline 8, 16, 32 */

-     int bitmap_bit_order;      /* LSBFirst, MSBFirst */

-     int bitmap_pad;            /* 8, 16, 32 either XY or ZPixmap */

-     int depth;                 /* depth of image */

-     int bytes_per_line;        /* accelerator to next scanline */

-     int bits_per_pixel;        /* bits per pixel (ZPixmap) */

-     unsigned long red_mask;    /* bits in z arrangement */

-     unsigned long green_mask;

-     unsigned long blue_mask;

-     XPointer obdata;           /* hook for the object routines to hang on */

-     struct funcs {             /* image manipulation routines */

-          struct _XImage *(*create_image)();

-          int             (*destroy_image)();

-          unsigned long   (*get_pixel)();

-          int             (*put_pixel)();

-          struct _XImage  *(*sub_image)();

-          int            (*add_pixel)();

-     } f;

-} XImage;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To initialize the image manipulation routines of an image structure, use

-<function>XInitImage</function>.

-<indexterm significance="preferred"><primary>XInitImage</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XInitImage</function></funcdef>

-  <paramdef>XImage<parameter> *image</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ximage</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the image.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XInitImage</function>

-function initializes the internal image manipulation routines of an

-image structure, based on the values of the various structure members.

-All fields other than the manipulation routines must already be initialized.

-If the bytes_per_line member is zero,

-<function>XInitImage</function>

-will assume the image data is contiguous in memory and set the

-bytes_per_line member to an appropriate value based on the other

-members; otherwise, the value of bytes_per_line is not changed.

-All of the manipulation routines are initialized to functions

-that other Xlib image manipulation functions need to operate on the

-type of image specified by the rest of the structure.

-</para>

-<para>

-<!-- .LP -->

-This function must be called for any image constructed by the client

-before passing it to any other Xlib function.

-Image structures created or returned by Xlib do not need to be

-initialized in this fashion.

-</para>

-<para>

-<!-- .LP -->

-This function returns a nonzero status if initialization of the

-structure is successful.  It returns zero if it detected some error

-or inconsistency in the structure, in which case the image is not changed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To combine an image with a rectangle of a drawable on the display,

-use

-<function>XPutImage</function>.

-<indexterm significance="preferred"><primary>XPutImage</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XPutImage</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>XImage<parameter> *image</parameter></paramdef>

-  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

-  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>image</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the image you want combined with the rectangle. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the offset in X from the left edge of the image defined

-by the 

-<structname>XImage</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the offset in Y from the top edge of the image defined

-by the 

-<structname>XImage</structname>

-structure.

-<!-- .ds Dx , which are relative to the origin of the drawable \ -->

-and are the coordinates of the subimage

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Dx. 

-<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPutImage</function>

-function

-combines an image with a rectangle of the specified drawable.

-The section of the image defined by the src_x, src_y, width, and height 

-arguments is drawn on the specified part of the drawable.

-If 

-<symbol>XYBitmap</symbol>

-format is used, the depth of the image must be one,

-or a

-<errorname>BadMatch</errorname>

-error results.

-The foreground pixel in the GC defines the source for the one bits in the image,

-and the background pixel defines the source for the zero bits.

-For 

-<symbol>XYPixmap</symbol>

-and 

-<symbol>ZPixmap</symbol>,

-the depth of the image must match the depth of the drawable,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-If the characteristics of the image (for example, byte_order and bitmap_unit)

-differ from what the server requires,

-<function>XPutImage</function>

-automatically makes the appropriate

-conversions.

-</para>

-<para>

-<!-- .LP -->

-This function uses these GC components: 

-function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, 

-and clip-mask.

-It also uses these GC mode-dependent components:

-foreground and background.

-</para>

-<para>

-<!-- .LP -->

-<function>XPutImage</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return the contents of a rectangle in a given drawable on the display,

-use

-<function>XGetImage</function>.

-This function specifically supports rudimentary screen dumps.

-<indexterm significance="preferred"><primary>XGetImage</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XImage *<function>XGetImage</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>

-  <paramdef>int<parameter> format</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-<!-- .ds Xy , which are relative to the origin of the drawable \ -->

-and define the upper-left corner of the rectangle

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>plane_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the plane mask.

-<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the format for the image.

-You can pass

-<symbol>XYPixmap</symbol>

-or 

-<symbol>ZPixmap</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetImage</function>

-function returns a pointer to an

-<structname>XImage</structname>

-structure.

-This structure provides you with the contents of the specified rectangle of

-the drawable in the format you specify.

-If the format argument is 

-<symbol>XYPixmap</symbol>,

-the image contains only the bit planes you passed to the plane_mask argument.

-If the plane_mask argument only requests a subset of the planes of the

-display, the depth of the returned image will be the number of planes

-requested.

-If the format argument is 

-<symbol>ZPixmap</symbol>,

-<function>XGetImage</function>

-returns as zero the bits in all planes not 

-specified in the plane_mask argument.

-The function performs no range checking on the values in plane_mask and ignores

-extraneous bits.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetImage</function>

-returns the depth of the image to the depth member of the

-<structname>XImage</structname>

-structure.

-The depth of the image is as specified when the drawable was created,

-except when getting a subset of the planes in 

-<symbol>XYPixmap</symbol>

-format, when the depth is given by the number of bits set to 1 in plane_mask.

-</para>

-<para>

-<!-- .LP -->

-If the drawable is a pixmap, 

-the given rectangle must be wholly contained within the pixmap, 

-or a

-<errorname>BadMatch</errorname>

-error results.

-If the drawable is a window, 

-the window must be viewable, 

-and it must be the case that if there were no inferiors or overlapping windows,

-the specified rectangle of the window would be fully visible on the screen

-and wholly contained within the outside edges of the window,

-or a

-<errorname>BadMatch</errorname>

-error results.

-Note that the borders of the window can be included and read with

-this request.

-If the window has backing-store, the backing-store contents are

-returned for regions of the window that are obscured by noninferior

-windows. 

-If the window does not have backing-store,

-the returned contents of such obscured regions are undefined.

-The returned contents of visible regions of inferiors

-of a different depth than the specified window's depth are also undefined.

-The pointer cursor image is not included in the returned contents.

-If a problem occurs,

-<function>XGetImage</function>

-returns NULL.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetImage</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To copy the contents of a rectangle on the display

-to a location within a preexisting image structure, use

-<function>XGetSubImage</function>.

-<indexterm significance="preferred"><primary>XGetSubImage</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XImage *<function>XGetSubImage</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>

-  <paramdef>int<parameter> format</parameter></paramdef>

-  <paramdef>XImage<parameter> *dest_image</parameter></paramdef>

-  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-<!-- .ds Xy , which are relative to the origin of the drawable \ -->

-and define the upper-left corner of the rectangle

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>plane_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the plane mask.

-<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the format for the image.

-You can pass

-<symbol>XYPixmap</symbol>

-or 

-<symbol>ZPixmap</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_image</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the destination image.

-<!-- .ds Dx , which are relative to the origin of the destination rectangle, \ -->

-specify its upper-left corner, and determine where the subimage \

-is placed in the destination image

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Dx. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetSubImage</function>

-function updates dest_image with the specified subimage in the same manner as 

-<function>XGetImage</function>.

-If the format argument is 

-<symbol>XYPixmap</symbol>,

-the image contains only the bit planes you passed to the plane_mask argument.

-If the format argument is 

-<symbol>ZPixmap</symbol>,

-<function>XGetSubImage</function>

-returns as zero the bits in all planes not 

-specified in the plane_mask argument.

-The function performs no range checking on the values in plane_mask and ignores

-extraneous bits.

-As a convenience,

-<function>XGetSubImage</function>

-returns a pointer to the same

-<structname>XImage</structname>

-structure specified by dest_image.

-</para>

-<para>

-<!-- .LP -->

-The depth of the destination

-<structname>XImage</structname>

-structure must be the same as that of the drawable.

-If the specified subimage does not fit at the specified location

-on the destination image, the right and bottom edges are clipped.

-If the drawable is a pixmap,

-the given rectangle must be wholly contained within the pixmap,

-or a

-<errorname>BadMatch</errorname>

-error results.

-If the drawable is a window, 

-the window must be viewable, 

-and it must be the case that if there were no inferiors or overlapping windows,

-the specified rectangle of the window would be fully visible on the screen

-and wholly contained within the outside edges of the window,

-or a

-<errorname>BadMatch</errorname>

-error results.

-If the window has backing-store, 

-then the backing-store contents are returned for regions of the window 

-that are obscured by noninferior windows. 

-If the window does not have backing-store, 

-the returned contents of such obscured regions are undefined.

-The returned contents of visible regions of inferiors

-of a different depth than the specified window's depth are also undefined.

-If a problem occurs,

-<function>XGetSubImage</function>

-returns NULL.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetSubImage</function>

-can generate

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-<!-- .bp -->

-

-

-</para>

-</sect1>

-</chapter>

+<?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="graphics_functions">
+<title>Graphics Functions</title>
+<para>
+Once you have established a connection to a display, you can use the Xlib graphics functions to:
+</para>
+<itemizedlist>
+  <listitem><para>Clear and copy areas</para></listitem>
+  <listitem><para>Draw points, lines, rectangles, and arcs</para></listitem>
+  <listitem><para>Fill areas</para></listitem>
+  <listitem><para>Manipulate fonts</para></listitem>
+  <listitem><para>Draw text</para></listitem>
+  <listitem><para>Transfer images between clients and the server</para></listitem>
+</itemizedlist>
+<para>
+If the same drawable and GC is used for each call, Xlib batches back-to-back
+calls to XDrawPoint, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle.
+Note that this reduces the total number of requests sent to the server.
+</para>
+<sect1 id="Clearing_Areas">
+<title>Clearing Areas</title>
+<!-- .XS -->
+<!-- (SN Clearing Areas  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to clear an area or the entire window.
+Because pixmaps do not have defined backgrounds, 
+they cannot be filled by using the functions described in this section.
+Instead, to accomplish an analogous operation on a pixmap,
+you should use 
+<function>XFillRectangle</function>,
+which sets the pixmap to a known value.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To clear a rectangular area of a given window, use
+<function>XClearArea</function>.
+<indexterm><primary>Areas</primary><secondary>clearing</secondary></indexterm>
+<indexterm><primary>Clearing</primary><secondary>areas</secondary></indexterm>
+<indexterm significance="preferred"><primary>XClearArea</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcleararea'>
+<funcprototype>
+  <funcdef><function>XClearArea</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>Bool<parameter> exposures</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+<!-- .ds Xy , which are relative to the origin of the window \ -->
+and specify the upper-left corner of the rectangle
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the dimensions of the rectangle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>exposures</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates if
+<symbol>Expose</symbol>
+events are to be generated.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XClearArea</function>
+function paints a rectangular area in the specified window according to the
+specified dimensions with the window's background pixel or pixmap.
+The subwindow-mode effectively is
+<symbol>ClipByChildren</symbol>.
+If width is zero, it
+is replaced with the current width of the window minus x.
+If height is
+zero, it is replaced with the current height of the window minus y.
+If the window has a defined background tile, 
+the rectangle clipped by any children is filled with this tile.
+If the window has
+background 
+<symbol>None</symbol>,
+the contents of the window are not changed.  
+In either
+case, if exposures is 
+<symbol>True</symbol>,
+one or more 
+<symbol>Expose</symbol>
+events are generated for regions of the rectangle that are either visible or are
+being retained in a backing store.
+If you specify a window whose class is
+<symbol>InputOnly</symbol>,
+a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XClearArea</function>
+can generate
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To clear the entire area in a given window, use
+<function>XClearWindow</function>.
+<indexterm><primary>Window</primary><secondary>clearing</secondary></indexterm>
+<indexterm><primary>Clearing</primary><secondary>windows</secondary></indexterm>
+<indexterm significance="preferred"><primary>XClearWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xclearwindow'>
+<funcprototype>
+  <funcdef><function>XClearWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XClearWindow</function>
+function clears the entire area in the specified window and is
+equivalent to
+<function>XClearArea</function>
+(display, w, 0, 0, 0, 0, 
+<symbol>False</symbol>).
+If the window has a defined background tile, the rectangle is tiled with a
+plane-mask of all ones and 
+<symbol>GXcopy</symbol>
+function.
+If the window has
+background 
+<symbol>None</symbol>,
+the contents of the window are not changed.  
+If you specify a window whose class is
+<symbol>InputOnly</symbol>,
+a
+<errorname>BadMatch</errorname>
+error results. 
+</para>
+<para>
+<!-- .LP -->
+<function>XClearWindow</function>
+can generate
+<errorname>BadMatch</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Copying_Areas">
+<title>Copying Areas</title>
+<!-- .XS -->
+<!-- (SN Copying Areas  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to copy an area or a bit plane.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To copy an area between drawables of the same
+root and depth, use
+<function>XCopyArea</function>.
+<indexterm><primary>Areas</primary><secondary>copying</secondary></indexterm>
+<indexterm><primary>Copying</primary><secondary>areas</secondary></indexterm>
+<indexterm significance="preferred"><primary>XCopyArea</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcopyarea'>
+<funcprototype>
+  <funcdef><function>XCopyArea</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the source and destination rectangles to be combined. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates, 
+which are relative to the origin of the source rectangle
+and specify its upper-left corner.
+<!-- .ds Wh , which are the dimensions of both the source \ -->
+and destination rectangles
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->
+and specify its upper-left corner
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Dx. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCopyArea</function>
+function combines the specified rectangle of src with the specified rectangle 
+of dest.
+The drawables must have the same root and depth,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If regions of the source rectangle are obscured and have not been
+retained in backing store 
+or if regions outside the boundaries of the source drawable are specified, 
+those regions are not copied. 
+Instead, the 
+following occurs on all corresponding destination regions that are either
+visible or are retained in backing store.  
+If the destination is a window with a background other than 
+<symbol>None</symbol>,
+corresponding regions
+of the destination are tiled with that background
+(with plane-mask of all ones and
+<symbol>GXcopy</symbol>
+function).
+Regardless of tiling or whether the destination is a window or a pixmap,
+if graphics-exposures is 
+<symbol>True</symbol>,
+then
+<symbol>GraphicsExpose</symbol>
+events for all corresponding destination regions are generated.
+If graphics-exposures is 
+<symbol>True</symbol>
+but no
+<symbol>GraphicsExpose</symbol>
+events are generated, a
+<symbol>NoExpose</symbol>
+event is generated.
+Note that by default graphics-exposures is
+<symbol>True</symbol>
+in new GCs.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components: function, plane-mask, 
+subwindow-mode, graphics-exposures, clip-x-origin,
+clip-y-origin, and clip-mask.
+</para>
+<para>
+<!-- .LP -->
+<function>XCopyArea</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To copy a single bit plane of a given drawable, use
+<function>XCopyPlane</function>.
+<indexterm><primary>Plane</primary><secondary>copying</secondary></indexterm>
+<indexterm><primary>Copying</primary><secondary>planes</secondary></indexterm>
+<indexterm significance="preferred"><primary>XCopyPlane</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcopyplane'>
+<funcprototype>
+  <funcdef><function>XCopyPlane</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> plane</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the source and destination rectangles to be combined. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates, 
+which are relative to the origin of the source rectangle
+and specify its upper-left corner.
+<!-- .ds Wh , which are the dimensions of both the source and destination rectangles -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->
+and specify its upper-left corner
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Dx. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>plane</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the bit plane.
+You must set exactly one bit to 1.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCopyPlane</function>
+function uses a single bit plane of the specified source rectangle
+combined with the specified GC to modify the specified rectangle of dest.
+The drawables must have the same root but need not have the same depth.
+If the drawables do not have the same root, a
+<errorname>BadMatch</errorname>
+error results.
+If plane does not have exactly one bit set to 1 and the value of plane
+is not less than %2 sup n%, where <emphasis remap='I'>n</emphasis> is the depth of src, a
+<errorname>BadValue</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+Effectively, 
+<function>XCopyPlane</function>
+forms a pixmap of the same depth as the rectangle of dest and with a
+size specified by the source region. 
+It uses the foreground/background pixels in the GC (foreground
+everywhere the bit plane in src contains a bit set to 1,
+background everywhere the bit plane in src contains a bit set to 0)
+and the equivalent of a 
+<systemitem>CopyArea</systemitem>
+protocol request is performed with all the same exposure semantics.
+This can also be thought of as using the specified region of the source 
+bit plane as a stipple with a fill-style of
+<symbol>FillOpaqueStippled</symbol>
+for filling a rectangular area of the destination.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components: function, plane-mask, foreground,
+background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,
+and clip-mask.
+</para>
+<para>
+<!-- .LP -->
+<function>XCopyPlane</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and 
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Drawing_Points_Lines_Rectangles_and_Arcs">
+<title>Drawing Points, Lines, Rectangles, and Arcs</title>
+<!-- .XS -->
+<!-- (SN Drawing Points, Lines, Rectangles, and Arcs  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to draw:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+A single point or multiple points
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A single line or multiple lines
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A single rectangle or multiple rectangles
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A single arc or multiple arcs
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Some of the functions described in the following sections
+use these structures:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XSegment</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+     short x1, y1, x2, y2;
+} XSegment;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XPoint</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+     short x, y;
+} XPoint;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XRectangle</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+     short x, y;
+     unsigned short width, height;
+} XRectangle;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XArc</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     short x, y;
+     unsigned short width, height;
+     short angle1, angle2;             /* Degrees * 64 */
+} XArc;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+All x and y members are signed integers.
+The width and height members are 16-bit unsigned integers.
+You should be careful not to generate coordinates and sizes
+out of the 16-bit ranges, because the protocol only has 16-bit fields
+for these values.
+</para>
+<sect2 id="Drawing_Single_and_Multiple_Points">
+<title>Drawing Single and Multiple Points</title>
+<!-- .XS -->
+<!-- (SN Drawing Single and Multiple Points  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Points</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>points</secondary></indexterm>
+<indexterm><primary>XDrawPoints</primary></indexterm>
+<indexterm><primary>XDrawPoint</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+To draw a single point in a given drawable, use
+<function>XDrawPoint</function>.
+<indexterm significance="preferred"><primary>XDrawPoint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawpoint'>
+<funcprototype>
+  <funcdef><function>XDrawPoint</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates where you want the point drawn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple points in a given drawable, use
+<function>XDrawPoints</function>.
+<indexterm significance="preferred"><primary>XDrawPoints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawpoints'>
+<funcprototype>
+  <funcdef><function>XDrawPoints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XPoint<parameter> *points</parameter></paramdef>
+  <paramdef>int<parameter> npoints</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>points</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of points.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>npoints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of points in the array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the coordinate mode. 
+You can pass
+<symbol>CoordModeOrigin</symbol>
+or
+<symbol>CoordModePrevious</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawPoint</function>
+function uses the foreground pixel and function components of the
+GC to draw a single point into the specified drawable; 
+<function>XDrawPoints</function>
+draws multiple points this way.
+<symbol>CoordModeOrigin</symbol>
+treats all coordinates as relative to the origin,
+and
+<symbol>CoordModePrevious</symbol>
+treats all coordinates after the first as relative to the previous point.
+<function>XDrawPoints</function>
+draws the points in the order listed in the array.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components: function, plane-mask,
+foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawPoint</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and 
+<errorname>BadMatch</errorname>
+errors.
+<function>XDrawPoints</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Single_and_Multiple_Lines">
+<title>Drawing Single and Multiple Lines</title>
+<!-- .XS -->
+<!-- (SN Drawing Single and Multiple Lines -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Lines</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>lines</secondary></indexterm>
+<indexterm><primary>XDrawLine</primary></indexterm>
+<indexterm><primary>XDrawLines</primary></indexterm>
+<indexterm><primary>Polygons</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>polygons</secondary></indexterm>
+<indexterm><primary>XDrawSegments</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+To draw a single line between two points in a given drawable, use
+<function>XDrawLine</function>.
+<indexterm significance="preferred"><primary>XDrawLine</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawline'>
+<funcprototype>
+  <funcdef><function>XDrawLine</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx1,y1,x2,<parameter> y2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x1</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y1</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x2</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y2</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the points (x1, y1) and (x2, y2) to be connected.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple lines in a given drawable, use
+<function>XDrawLines</function>.
+<indexterm significance="preferred"><primary>XDrawLines</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawlines'>
+<funcprototype>
+  <funcdef><function>XDrawLines</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XPoint<parameter> *points</parameter></paramdef>
+  <paramdef>int<parameter> npoints</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>points</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of points.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>npoints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of points in the array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the coordinate mode. 
+You can pass
+<symbol>CoordModeOrigin</symbol>
+or
+<symbol>CoordModePrevious</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple, unconnected lines in a given drawable,
+use
+<function>XDrawSegments</function>.
+<indexterm significance="preferred"><primary>XDrawSegments</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawsegments'>
+<funcprototype>
+  <funcdef><function>XDrawSegments</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XSegment<parameter> *segments</parameter></paramdef>
+  <paramdef>int<parameter> nsegments</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>segments</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of segments.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nsegments</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of segments in the array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawLine</function>
+function uses the components of the specified GC to
+draw a line between the specified set of points (x1, y1) and (x2, y2).
+It does not perform joining at coincident endpoints.
+For any given line, 
+<function>XDrawLine</function>
+does not draw a pixel more than once.
+If lines intersect, the intersecting pixels are drawn multiple times.  
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XDrawLines</function>
+function uses the components of the specified GC to draw 
+npoints-1 lines between each pair of points (point[i], point[i+1]) 
+in the array of
+<structname>XPoint</structname>
+structures.
+It draws the lines in the order listed in the array.
+The lines join correctly at all intermediate points, and if the first and last
+points coincide, the first and last lines also join correctly.
+For any given line, 
+<function>XDrawLines</function>
+does not draw a pixel more than once.
+If thin (zero line-width) lines intersect, 
+the intersecting pixels are drawn multiple times.
+If wide lines intersect, the intersecting pixels are drawn only once, as though
+the entire 
+<systemitem>PolyLine</systemitem>
+protocol request were a single, filled shape.
+<symbol>CoordModeOrigin</symbol>
+treats all coordinates as relative to the origin,
+and
+<symbol>CoordModePrevious</symbol>
+treats all coordinates after the first as relative to the previous point.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XDrawSegments</function>
+function draws multiple, unconnected lines. 
+For each segment, 
+<function>XDrawSegments</function>
+draws a
+line between (x1, y1) and (x2, y2).
+It draws the lines in the order listed in the array of
+<structname>XSegment</structname>
+structures and does not perform joining at coincident endpoints.
+For any given line, 
+<function>XDrawSegments</function>
+does not draw a pixel more than once.  
+If lines intersect, the intersecting pixels are drawn multiple times.  
+</para>
+<para>
+<!-- .LP -->
+All three functions use these GC components:
+function, plane-mask, line-width,
+line-style, cap-style, fill-style, subwindow-mode,
+clip-x-origin, clip-y-origin, and clip-mask.
+The
+<function>XDrawLines</function>
+function also uses the join-style GC component.
+All three functions also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+tile-stipple-y-origin, dash-offset, and dash-list.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawLine</function>,
+<function>XDrawLines</function>,
+and
+<function>XDrawSegments</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+<function>XDrawLines</function>
+also can generate
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Single_and_Multiple_Rectangles_">
+<title>Drawing Single and Multiple Rectangles </title>
+<!-- .XS -->
+<!-- (SN Drawing Single and Multiple Rectangles  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Rectangles</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>rectangles</secondary></indexterm>
+<indexterm><primary>XDrawRectangle</primary></indexterm>
+<indexterm><primary>XDrawRectangles</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+To draw the outline of a single rectangle in a given drawable, use
+<function>XDrawRectangle</function>.
+<indexterm significance="preferred"><primary>XDrawRectangle</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawrectangle'>
+<funcprototype>
+  <funcdef><function>XDrawRectangle</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which specify the upper-left corner of the rectangle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which specify the dimensions of the rectangle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw the outline of multiple rectangles
+in a given drawable, use
+<function>XDrawRectangles</function>.
+<indexterm significance="preferred"><primary>XDrawRectangles</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawrectangles'>
+<funcprototype>
+  <funcdef><function>XDrawRectangles</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>
+  <paramdef>int<parameter> nrectangles</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rectangles</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of rectangles.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nrectangles</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of rectangles in the array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawRectangle</function>
+and
+<function>XDrawRectangles</function>
+functions draw the outlines of the specified rectangle or rectangles as
+if a five-point 
+<systemitem>PolyLine</systemitem>
+protocol request were specified for each rectangle:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP  -->
+For the specified rectangle or rectangles, 
+these functions do not draw a pixel more than once.
+<function>XDrawRectangles</function>
+draws the rectangles in the order listed in the array.
+If rectangles intersect,
+the intersecting pixels are drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components: 
+function, plane-mask, line-width,
+line-style, cap-style, join-style, fill-style, 
+subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+tile-stipple-y-origin, dash-offset, and dash-list.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawRectangle</function>
+and
+<function>XDrawRectangles</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Single_and_Multiple_Arcs">
+<title>Drawing Single and Multiple Arcs</title>
+<!-- .XS -->
+<!-- (SN Drawing Single and Multiple Arcs  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Drawing</primary><secondary>arcs</secondary></indexterm>
+<indexterm><primary>XDrawArc</primary></indexterm>
+<indexterm><primary>Arcs</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>XDrawArcs</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To draw a single arc in a given drawable, use
+<function>XDrawArc</function>.
+<indexterm significance="preferred"><primary>XDrawArc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawarc'>
+<funcprototype>
+  <funcdef><function>XDrawArc</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>intangle1,<parameter> angle2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and specify the upper-left corner of the bounding rectangle
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the major and minor axes of the arc -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>angle1</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the start of the arc relative to the three-o'clock position
+from the center, in units of degrees * 64.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>angle2</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the path and extent of the arc relative to the start of the
+arc, in units of degrees * 64.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple arcs in a given drawable, use
+<function>XDrawArcs</function>.
+<indexterm significance="preferred"><primary>XDrawArcs</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawarcs'>
+<funcprototype>
+  <funcdef><function>XDrawArcs</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XArc<parameter> *arcs</parameter></paramdef>
+  <paramdef>int<parameter> narcs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arcs</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of arcs.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>narcs</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of arcs in the array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+<function>XDrawArc</function>
+draws a single circular or elliptical arc, and 
+<function>XDrawArcs</function>
+draws multiple circular or elliptical arcs.
+Each arc is specified by a rectangle and two angles.  
+The center of the circle or ellipse is the center of the
+rectangle, and the major and minor axes are specified by the width and height.
+Positive angles indicate counterclockwise motion, 
+and negative angles indicate clockwise motion.  
+If the magnitude of angle2 is greater than 360 degrees, 
+<function>XDrawArc</function>
+or 
+<function>XDrawArcs</function>
+truncates it to 360 degrees.
+</para>
+<para>
+<!-- .LP -->
+For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, 
+the origin of the major and minor axes is at 
+% [ x +^ {width over 2} , ~y +^ {height over 2}  ]%, 
+and the infinitely thin path describing the entire circle or ellipse 
+intersects the horizontal axis at % [ x, ~y +^ {height over 2}  ]% and 
+% [ x +^ width , ~y +^ { height over 2 }] %
+and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and 
+% [ x +^ { width over 2 }, ~y +^ height ]%.
+These coordinates can be fractional
+and so are not truncated to discrete coordinates.
+The path should be defined by the ideal mathematical path.  
+For a wide line with line-width lw, 
+the bounding outlines for filling are given        
+by the two infinitely thin paths consisting of all points whose perpendicular
+distance from the path of the circle/ellipse is equal to lw/2
+(which may be a fractional value).
+The cap-style and join-style are applied the same as for a line
+corresponding to the tangent of the circle/ellipse at the endpoint.
+</para>
+<para>
+<!-- .LP -->
+For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2  ]%,
+the angles must be specified
+in the effectively skewed coordinate system of the ellipse (for a
+circle, the angles and coordinate systems are identical).  The
+relationship between these angles and angles expressed in the normal
+coordinate system of the screen (as measured with a protractor) is as
+follows:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
+ * width over height right ) +^ adjust%
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The skewed-angle and normal-angle are expressed in radians (rather
+than in degrees scaled by 64) in the range % [ 0 , ~2 pi  ]% and where atan
+returns a value in the range % [ - pi over 2 , ~pi over 2  ] %
+and adjust is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 1i 2i -->
+<!-- .ta 1i 2i -->
+%0%     for normal-angle in the range % [ 0 , ~pi over 2  ]%
+%pi%     for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2  ]%
+%2 pi%     for normal-angle in the range % [ {3 pi} over 2 , ~2 pi  ]%
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+For any given arc, 
+<function>XDrawArc</function>
+and
+<function>XDrawArcs</function>
+do not draw a pixel more than once.  
+If two arcs join correctly and if the line-width is greater than zero 
+and the arcs intersect, 
+<function>XDrawArc</function>
+and
+<function>XDrawArcs</function>
+do not draw a pixel more than once.
+Otherwise, 
+the intersecting pixels of intersecting arcs are drawn multiple times.
+Specifying an arc with one endpoint and a clockwise extent draws the same pixels
+as specifying the other endpoint and an equivalent counterclockwise extent,
+except as it affects joins.
+</para>
+<para>
+<!-- .LP -->
+If the last point in one arc coincides with the first point in the following 
+arc, the two arcs will join correctly.  
+If the first point in the first arc coincides with the last point in the last 
+arc, the two arcs will join correctly.
+By specifying one axis to be zero, a horizontal or vertical line can be
+drawn.
+Angles are computed based solely on the coordinate system and ignore the
+aspect ratio.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components: 
+function, plane-mask, line-width, line-style, cap-style, join-style, 
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+tile-stipple-y-origin, dash-offset, and dash-list.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawArc</function>
+and
+<function>XDrawArcs</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Filling_Areas">
+<title>Filling Areas</title>
+<!-- .XS -->
+<!-- (SN Filling Areas  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to fill:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+A single rectangle or multiple rectangles
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A single polygon
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A single arc or multiple arcs
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Filling_Single_and_Multiple_Rectangles">
+<title>Filling Single and Multiple Rectangles</title>
+<!-- .XS -->
+<!-- (SN Filling Single and Multiple Rectangles  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Filling</primary><secondary>rectangles</secondary></indexterm>
+<indexterm><primary>XFillRectangle</primary></indexterm>
+<indexterm><primary>Rectangle</primary><secondary>filling</secondary></indexterm>
+<indexterm><primary>XFillRectangles</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To fill a single rectangular area in a given drawable, use
+<function>XFillRectangle</function>.
+<indexterm significance="preferred"><primary>XFillRectangle</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfillrectangle'>
+<funcprototype>
+  <funcdef><function>XFillRectangle</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and specify the upper-left corner of the rectangle
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the dimensions of the rectangle to be filled -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To fill multiple rectangular areas in a given drawable, use
+<function>XFillRectangles</function>.
+<indexterm significance="preferred"><primary>XFillRectangles</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfillrectangles'>
+<funcprototype>
+  <funcdef><function>XFillRectangles</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *rectangles</parameter></paramdef>
+  <paramdef>int<parameter> nrectangles</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rectangles</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of rectangles.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nrectangles</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of rectangles in the array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFillRectangle</function>
+and
+<function>XFillRectangles</function>
+functions fill the specified rectangle or rectangles
+as if a four-point 
+<systemitem>FillPolygon</systemitem>
+protocol request were specified for each rectangle:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+[x,y] [x+width,y] [x+width,y+height] [x,y+height]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Each function uses the x and y coordinates,
+width and height dimensions, and GC you specify.
+</para>
+<para>
+<!-- .LP -->
+<function>XFillRectangles</function>
+fills the rectangles in the order listed in the array.  
+For any given rectangle,
+<function>XFillRectangle</function>
+and
+<function>XFillRectangles</function>
+do not draw a pixel more than once.  
+If rectangles intersect, the intersecting pixels are
+drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components: 
+function, plane-mask, fill-style, subwindow-mode, 
+clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XFillRectangle</function>
+and
+<function>XFillRectangles</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Filling_a_Single_Polygon">
+<title>Filling a Single Polygon</title>
+<!-- .XS -->
+<!-- (SN Filling a Single Polygon  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To fill a polygon area in a given drawable, use
+<function>XFillPolygon</function>.
+<indexterm><primary>Polygons</primary><secondary>filling</secondary></indexterm>
+<indexterm><primary>Filling</primary><secondary>polygon</secondary></indexterm>
+<indexterm significance="preferred"><primary>XFillPolygon</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfillpolygon'>
+<funcprototype>
+  <funcdef><function>XFillPolygon</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XPoint<parameter> *points</parameter></paramdef>
+  <paramdef>int<parameter> npoints</parameter></paramdef>
+  <paramdef>int<parameter> shape</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>points</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of points.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>npoints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of points in the array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>shape</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a shape that helps the server to improve performance.
+You can pass 
+<symbol>Complex</symbol>,
+<symbol>Convex</symbol>,
+or 
+<symbol>Nonconvex</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the coordinate mode. 
+You can pass
+<symbol>CoordModeOrigin</symbol>
+or
+<symbol>CoordModePrevious</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XFillPolygon</function>
+fills the region closed by the specified path.
+The path is closed
+automatically if the last point in the list does not coincide with the
+first point.
+<function>XFillPolygon</function>
+does not draw a pixel of the region more than once.
+<symbol>CoordModeOrigin</symbol>
+treats all coordinates as relative to the origin,
+and
+<symbol>CoordModePrevious</symbol>
+treats all coordinates after the first as relative to the previous point.
+</para>
+<para>
+<!-- .LP -->
+Depending on the specified shape, the following occurs: 
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If shape is
+<symbol>Complex</symbol>,
+the path may self-intersect. 
+Note that contiguous coincident points in the path are not treated 
+as self-intersection.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If shape is
+<symbol>Convex</symbol>,
+for every pair of points inside the polygon,
+the line segment connecting them does not intersect the path.
+If known by the client,
+specifying 
+<symbol>Convex</symbol>
+can improve performance.  
+If you specify
+<symbol>Convex</symbol>
+for a path that is not convex, 
+the graphics results are undefined.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If shape is
+<symbol>Nonconvex</symbol>,
+the path does not self-intersect, but the shape is not
+wholly convex. 
+If known by the client, 
+specifying 
+<symbol>Nonconvex</symbol>
+instead of
+<symbol>Complex</symbol>
+may improve performance.  
+If you specify
+<symbol>Nonconvex</symbol>
+for a self-intersecting path, the graphics results are undefined.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The fill-rule of the GC controls the filling behavior of 
+self-intersecting polygons.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components: 
+function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, 
+clip-y-origin, and clip-mask.
+It also uses these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XFillPolygon</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Filling_Single_and_Multiple_Arcs">
+<title>Filling Single and Multiple Arcs</title>
+<!-- .XS -->
+<!-- (SN Filling Single and Multiple Arcs  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>XFillArc</primary></indexterm>
+<indexterm><primary>Arcs</primary><secondary>filling</secondary></indexterm>
+<indexterm><primary>Filling</primary><secondary>arcs</secondary></indexterm>
+To fill a single arc in a given drawable, use
+<function>XFillArc</function>.
+<indexterm significance="preferred"><primary>XFillArc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfillarc'>
+<funcprototype>
+  <funcdef><function>XFillArc</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>intangle1,<parameter> angle2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and specify the upper-left corner of the bounding rectangle
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which are the major and minor axes of the arc -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>angle1</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the start of the arc relative to the three-o'clock position
+from the center, in units of degrees * 64.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>angle2</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the path and extent of the arc relative to the start of the
+arc, in units of degrees * 64.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To fill multiple arcs in a given drawable, use
+<function>XFillArcs</function>.
+<indexterm significance="preferred"><primary>XFillArcs</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfillarcs'>
+<funcprototype>
+  <funcdef><function>XFillArcs</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XArc<parameter> *arcs</parameter></paramdef>
+  <paramdef>int<parameter> narcs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arcs</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of arcs.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>narcs</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of arcs in the array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For each arc, 
+<function>XFillArc</function>
+or
+<function>XFillArcs</function>
+fills the region closed by the infinitely thin path
+described by the specified arc and, depending on the 
+arc-mode specified in the GC, one or two line segments. 
+For 
+<symbol>ArcChord</symbol>,
+the single line segment joining the endpoints of the arc is used.  
+For 
+<symbol>ArcPieSlice</symbol>,
+the two line segments joining the endpoints of the arc with the center
+point are used.  
+<function>XFillArcs</function>
+fills the arcs in the order listed in the array.  
+For any given arc,  
+<function>XFillArc</function>
+and
+<function>XFillArcs</function>
+do not draw a pixel more than once.  
+If regions intersect, 
+the intersecting pixels are drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components: 
+function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, 
+clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XFillArc</function>
+and
+<function>XFillArcs</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Font_Metrics">
+<title>Font Metrics</title>
+<!-- .XS -->
+<!-- (SN Font Metrics  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Font</primary></indexterm>
+A font is a graphical description of a set of characters that are used to 
+increase efficiency whenever a set of small, similar sized patterns are 
+repeatedly used.
+</para>
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Load and free fonts
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Obtain and free font names
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Compute character string sizes
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Compute logical extents
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Query character string sizes
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The X server loads fonts whenever a program requests a new font.
+The server can cache fonts for quick lookup.
+Fonts are global across all screens in a server.
+Several levels are possible when dealing with fonts.
+Most applications simply use 
+<function>XLoadQueryFont</function>
+to load a font and query the font metrics.
+</para>
+<para>
+<!-- .LP -->
+Characters in fonts are regarded as masks.
+Except for image text requests,
+the only pixels modified are those in which bits are set to 1 in the character.
+This means that it makes sense to draw text using stipples or tiles
+(for example, many menus gray-out unusable entries).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+The
+<structname>XFontStruct</structname>
+structure contains all of the information for the font
+and consists of the font-specific information as well as
+a pointer to an array of
+<structname>XCharStruct</structname>
+structures for the
+characters contained in the font.
+The
+<structname>XFontStruct</structname>,
+<structname>XFontProp</structname>,
+and
+<structname>XCharStruct</structname>
+structures contain:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCharStruct</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     short lbearing;               /* origin to left edge of raster */
+     short rbearing;               /* origin to right edge of raster */
+     short width;                  /* advance to next char's origin */
+     short ascent;                 /* baseline to top edge of raster */
+     short descent;                /* baseline to bottom edge of raster */
+     unsigned short attributes;    /* per char flags (not predefined) */
+} XCharStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XFontProp</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 3i -->
+<!-- .ta .5i 1i 3i -->
+typedef struct {
+     Atom     name;
+     unsigned long card32;
+} XFontProp;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XChar2b</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {     /* normal 16 bit characters are two bytes */
+    unsigned char byte1;
+    unsigned char byte2;
+} XChar2b;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XFontStruct</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     XExtData *ext_data;               /* hook for extension to hang data */
+     Font fid;                         /* Font id for this font */
+     unsigned direction;               /* hint about the direction font is painted */
+     unsigned min_char_or_byte2;       /* first character */
+     unsigned max_char_or_byte2;       /* last character */
+     unsigned min_byte1;               /* first row that exists */
+     unsigned max_byte1;               /* last row that exists */
+     Bool all_chars_exist;             /* flag if all characters have nonzero size */
+     unsigned default_char;            /* char to print for undefined character */
+     int n_properties;                 /* how many properties there are */
+     XFontProp *properties;            /* pointer to array of additional properties */
+     XCharStruct min_bounds;           /* minimum bounds over all existing char */
+     XCharStruct max_bounds;           /* maximum bounds over all existing char */
+     XCharStruct *per_char;            /* first_char to last_char information */
+     int ascent;                       /* logical extent above baseline for spacing */
+     int descent;                      /* logical descent below baseline for spacing */
+} XFontStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+X supports single byte/character, two bytes/character matrix,
+and 16-bit character text operations.
+Note that any of these forms can be used with a font, but a
+single byte/character text request can only specify a single byte
+(that is, the first row of a 2-byte font).
+You should view 2-byte fonts as a two-dimensional matrix of defined
+characters: byte1 specifies the range of defined rows and
+byte2 defines the range of defined columns of the font.
+Single byte/character fonts have one row defined, and the byte2 range
+specified in the structure defines a range of characters.
+</para>
+<para>
+<!-- .LP -->
+The bounding box of a character is defined by the 
+<structname>XCharStruct</structname>
+of that character.
+When characters are absent from a font,
+the default_char is used.
+When fonts have all characters of the same size,
+only the information in the
+<structname>XFontStruct</structname>
+min and max bounds are used.
+</para>
+<para>
+<!-- .LP -->
+The members of the 
+<structname>XFontStruct</structname>
+have the following semantics:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The direction member can be either 
+<symbol>FontLeftToRight</symbol>
+or 
+<symbol>FontRightToLeft</symbol>.
+It is just a hint as to whether most 
+<structname>XCharStruct</structname>
+elements 
+have a positive 
+(<symbol>FontLeftToRight</symbol>)
+or a negative 
+(<symbol>FontRightToLeft</symbol>)
+character width 
+metric.
+The core protocol defines no support for vertical text.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2
+specifies the linear character index corresponding to the first element
+of the per_char array, and max_char_or_byte2 specifies the linear character
+index of the last element.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If either min_byte1 or max_byte1 are nonzero, both
+min_char_or_byte2 and max_char_or_byte2 are less than 256, 
+and the 2-byte character index values corresponding to the
+per_char array element N (counting from 0) are:
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<!-- .nf -->
+     byte1 = N/D + min_byte1
+<!-- .br -->
+     byte2 = N\\D + min_char_or_byte2
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<!-- .fi -->
+where:
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<!-- .nf -->
+        D = max_char_or_byte2 - min_char_or_byte2 + 1
+        / = integer division
+        \\ = integer modulus
+<!-- .fi -->
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the per_char pointer is NULL, 
+all glyphs between the first and last character indexes
+inclusive have the same information,
+as given by both min_bounds and max_bounds.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If all_chars_exist is 
+<symbol>True</symbol>,
+all characters in the per_char array have nonzero bounding boxes.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The default_char member specifies the character that will be used when an
+undefined or nonexistent character is printed.  
+The default_char is a 16-bit character (not a 2-byte character).
+For a font using 2-byte matrix format, 
+the default_char has byte1 in the most-significant byte
+and byte2 in the least significant byte.
+If the default_char itself specifies an undefined or nonexistent character, 
+no printing is performed for an undefined or nonexistent character.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The min_bounds and max_bounds members contain the most extreme values of
+each individual 
+<structname>XCharStruct</structname>
+component over all elements of this array
+(and ignore nonexistent characters).
+The bounding box of the font (the smallest
+rectangle enclosing the shape obtained by superimposing all of the
+characters at the same origin [x,y]) has its upper-left coordinate at:
+<literallayout class="monospaced">
+     [x + min_bounds.lbearing, y - max_bounds.ascent]
+</literallayout>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Its width is:
+<literallayout class="monospaced">
+     max_bounds.rbearing - min_bounds.lbearing
+</literallayout>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Its height is:
+<literallayout class="monospaced">
+     max_bounds.ascent + max_bounds.descent
+</literallayout>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The ascent member is the logical extent of the font above the baseline that is
+used for determining line spacing.
+Specific characters may extend beyond
+this.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The descent member is the logical extent of the font at or below the
+baseline that is used for determining line spacing.
+Specific characters may extend beyond this.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the baseline is at Y-coordinate y,
+the logical extent of the font is inclusive between the Y-coordinate 
+values (y - font.ascent) and (y + font.descent - 1).
+Typically,
+the minimum interline spacing between rows of text is given
+by ascent + descent.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For a character origin at [x,y],
+the bounding box of a character (that is, 
+the smallest rectangle that encloses the character's shape)
+described in terms of 
+<structname>XCharStruct</structname>
+components is a rectangle with its upper-left corner at:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+[x + lbearing, y - ascent]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Its width is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+rbearing - lbearing
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Its height is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+ascent + descent
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The origin for the next character is defined to be:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+[x + width, y]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The lbearing member defines the extent of the left edge of the character ink
+from the origin.
+The rbearing member defines the extent of the right edge of the character ink
+from the origin.
+The ascent member defines the extent of the top edge of the character ink
+from the origin.
+The descent member defines the extent of the bottom edge of the character ink
+from the origin.
+The width member defines the logical width of the character.
+</para>
+<para>
+<!-- .LP -->
+Note that the baseline (the y position of the character origin) 
+is logically viewed as being the scanline just below nondescending characters. 
+When descent is zero,
+only pixels with Y-coordinates less than y are drawn,
+and the origin is logically viewed as being coincident with the left edge of
+a nonkerned character. 
+When lbearing is zero,
+no pixels with X-coordinate less than x are drawn.
+Any of the
+<structname>XCharStruct</structname>
+metric members could be negative.
+If the width is negative,
+the next character will be placed to the left of the current origin.
+</para>
+<para>
+<!-- .LP -->
+The X protocol does not define the interpretation of the attributes member 
+in the
+<structname>XCharStruct</structname>
+structure.
+A nonexistent character is represented with all members of its
+<structname>XCharStruct</structname>
+set to zero.
+</para>
+<para>
+<!-- .LP -->
+A font is not guaranteed to have any properties.
+The interpretation of the property value (for example, long or unsigned long)
+must be derived from <emphasis remap='I'>a priori</emphasis> knowledge of the property. 
+A basic set of font properties is specified in the X Consortium standard
+<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.
+</para>
+<sect2 id="Loading_and_Freeing_Fonts">
+<title>Loading and Freeing Fonts</title>
+<!-- .XS -->
+<!-- (SN Loading and Freeing Fonts  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to load fonts, get font information,
+unload fonts, and free font information.
+<indexterm><primary>Fonts</primary><secondary>getting information</secondary></indexterm>
+<indexterm><primary>Fonts</primary><secondary>unloading</secondary></indexterm>
+<indexterm><primary>Fonts</primary><secondary>freeing font information</secondary></indexterm>
+A few font functions use a 
+<type>GContext</type>
+resource ID or a font ID interchangeably.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To load a given font, use
+<function>XLoadFont</function>.
+<indexterm significance="preferred"><primary>XLoadFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xloadfont'>
+<funcprototype>
+  <funcdef>Font <function>XLoadFont</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the name of the font,
+which is a null-terminated string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLoadFont</function>
+function loads the specified font and returns its associated font ID.
+If the font name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+When the characters ``?'' and ``*'' are used in a font name, a
+pattern match is performed and any matching font is used.
+In the pattern, 
+the ``?'' character will match any single character, 
+and the ``*'' character will match any number of characters.
+A structured format for font names is specified in the X Consortium standard 
+<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.
+If 
+<function>XLoadFont</function>
+was unsuccessful at loading the specified font, 
+a 
+<errorname>BadName</errorname>
+error results.
+Fonts are not associated with a particular screen 
+and can be stored as a component
+of any GC.
+When the font is no longer needed, call 
+<function>XUnloadFont</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XLoadFont</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadName</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return information about an available font, use
+<function>XQueryFont</function>.
+<indexterm significance="preferred"><primary>XQueryFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xqueryfont'>
+<funcprototype>
+  <funcdef>XFontStruct *<function>XQueryFont</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XID<parameter> font_ID</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_ID</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font ID or the 
+<type>GContext</type>
+ID.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryFont</function>
+function returns a pointer to the
+<structname>XFontStruct</structname>
+structure, which contains information associated with the font.
+You can query a font or the font stored in a GC.
+The font ID stored in the 
+<structname>XFontStruct</structname>
+structure will be the 
+<type>GContext</type>
+ID, and you need to be careful when using this ID in other functions
+(see
+<function>XGContextFromGC</function>).
+If the font does not exist,
+<function>XQueryFont</function>
+returns NULL.
+To free this data, use
+<function>XFreeFontInfo</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To perform a
+<function>XLoadFont</function>
+and
+<function>XQueryFont</function>
+in a single operation, use
+<function>XLoadQueryFont</function>.
+<indexterm significance="preferred"><primary>XLoadQueryFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xloadqueryfont'>
+<funcprototype>
+  <funcdef>XFontStruct *<function>XLoadQueryFont</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the name of the font,
+which is a null-terminated string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLoadQueryFont</function>
+function provides the most common way for accessing a font.
+<function>XLoadQueryFont</function>
+both opens (loads) the specified font and returns a pointer to the
+appropriate
+<structname>XFontStruct</structname>
+structure.
+If the font name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+If the font does not exist,
+<function>XLoadQueryFont</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<function>XLoadQueryFont</function>
+can generate a
+<errorname>BadAlloc</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unload the font and free the storage used by the font structure
+that was allocated by
+<function>XQueryFont</function>
+or
+<function>XLoadQueryFont</function>,
+use
+<function>XFreeFont</function>.
+<indexterm significance="preferred"><primary>XFreeFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreefont'>
+<funcprototype>
+  <funcdef><function>XFreeFont</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_struct</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the storage associated with the font.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XFreeFont</function>
+function deletes the association between the font resource ID and the specified 
+font and frees the
+<structname>XFontStruct</structname>
+structure.
+The font itself will be freed when no other resource references it.
+The data and the font should not be referenced again.
+</para>
+<para>
+<!-- .LP -->
+<function>XFreeFont</function>
+can generate a
+<errorname>BadFont</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a given font property, use
+<function>XGetFontProperty</function>.
+<indexterm significance="preferred"><primary>XGetFontProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetfontproperty'>
+<funcprototype>
+  <funcdef>Bool <function>XGetFontProperty</function></funcdef>
+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+  <paramdef>Atom<parameter> atom</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_struct</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the storage associated with the font.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>atom</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the atom for the property name you want returned.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the value of the font property.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Given the atom for that property,
+the
+<function>XGetFontProperty</function>
+function returns the value of the specified font property. 
+<function>XGetFontProperty</function>
+also returns 
+<symbol>False</symbol>
+if the property was not defined or 
+<symbol>True</symbol>
+if it was defined.
+A set of predefined atoms exists for font properties,
+which can be found in
+<filename class="headerfile">&lt;X11/Xatom.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>
+This set contains the standard properties associated with
+a font.
+Although it is not guaranteed,
+it is likely that the predefined font properties will be present.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unload a font that was loaded by
+<function>XLoadFont</function>,
+use
+<function>XUnloadFont</function>.
+<indexterm significance="preferred"><primary>XUnloadFont</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunloadfont'>
+<funcprototype>
+  <funcdef><function>XUnloadFont</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Font<parameter> font</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnloadFont</function>
+function deletes the association between the font resource ID and the specified font.
+The font itself will be freed when no other resource references it.
+The font should not be referenced again.
+</para>
+<para>
+<!-- .LP -->
+<function>XUnloadFont</function>
+can generate a
+<errorname>BadFont</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Obtaining_and_Freeing_Font_Names_and_Information">
+<title>Obtaining and Freeing Font Names and Information</title>
+<!-- .XS -->
+<!-- (SN Obtaining and Freeing Font Names and Information -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You obtain font names and information by matching a wildcard specification
+when querying a font type for a list of available sizes and so on.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a list of the available font names, use
+<function>XListFonts</function>.
+<indexterm significance="preferred"><primary>XListFonts</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlistfonts'>
+<funcprototype>
+  <funcdef>char **<function>XListFonts</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *pattern</parameter></paramdef>
+  <paramdef>int<parameter> maxnames</parameter></paramdef>
+  <paramdef>int<parameter> *actual_count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pattern</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the null-terminated pattern string that can contain wildcard 
+characters.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>maxnames</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the maximum number of names to be returned.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>actual_count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the actual number of font names.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListFonts</function>
+function returns an array of available font names 
+(as controlled by the font search path; see
+<function>XSetFontPath</function>)
+that match the string you passed to the pattern argument.
+The pattern string can contain any characters,
+but each asterisk (*) is a wildcard for any number of characters,
+and each question mark (?) is a wildcard for a single character.
+If the pattern string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+Each returned string is null-terminated.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+If there are no matching font names,
+<function>XListFonts</function>
+returns NULL.
+The client should call
+<function>XFreeFontNames</function>
+when finished with the result to free the memory.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free a font name array, use
+<function>XFreeFontNames</function>.
+<indexterm significance="preferred"><primary>XFreeFontNames</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreefontnames'>
+<funcprototype>
+  <funcdef><function>XFreeFontNames</function></funcdef>
+  <paramdef>char<parameter> *list[]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the array of strings you want to free.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFontNames</function>
+function frees the array and strings returned by
+<function>XListFonts</function>
+or
+<function>XListFontsWithInfo</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the names and information about available fonts, use
+<function>XListFontsWithInfo</function>.
+<indexterm significance="preferred"><primary>XListFontsWithInfo</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlistfontswithinfo'>
+<funcprototype>
+  <funcdef>char **<function>XListFontsWithInfo</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *pattern</parameter></paramdef>
+  <paramdef>int<parameter> maxnames</parameter></paramdef>
+  <paramdef>int<parameter> *count_return</parameter></paramdef>
+  <paramdef>XFontStruct<parameter> **info_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pattern</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the null-terminated pattern string that can contain wildcard 
+characters.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>maxnames</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the maximum number of names to be returned.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the actual number of matched font names.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>info_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font information.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListFontsWithInfo</function>
+function returns a list of font names that match the specified pattern and their
+associated font information.
+The list of names is limited to size specified by maxnames.
+The information returned for each font is identical to what
+<function>XLoadQueryFont</function>
+would return except that the per-character metrics are not returned.
+The pattern string can contain any characters,
+but each asterisk (*) is a wildcard for any number of characters,
+and each question mark (?) is a wildcard for a single character.
+If the pattern string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+Each returned string is null-terminated.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+If there are no matching font names,
+<function>XListFontsWithInfo</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+To free only the allocated name array,
+the client should call
+<function>XFreeFontNames</function>.
+To free both the name array and the font information array
+or to free just the font information array,
+the client should call
+<function>XFreeFontInfo</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free font structures and font names, use
+<function>XFreeFontInfo</function>.
+<indexterm significance="preferred"><primary>XFreeFontInfo</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreefontinfo'>
+<funcprototype>
+  <funcdef><function>XFreeFontInfo</function></funcdef>
+  <paramdef>char<parameter> **names</parameter></paramdef>
+  <paramdef>XFontStruct<parameter> *free_info</parameter></paramdef>
+  <paramdef>int<parameter> actual_count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>names</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the list of font names.
+
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>free_info</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font information.
+
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>actual_count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the actual number of font names.
+
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFontInfo</function>
+function frees a font structure or an array of font structures
+and optionally an array of font names.
+If NULL is passed for names, no font names are freed.
+If a font structure for an open font (returned by
+<function>XLoadQueryFont</function>)
+is passed, the structure is freed,
+but the font is not closed; use
+<function>XUnloadFont</function>
+to close the font.
+</para>
+</sect2>
+<sect2 id="Computing_Character_String_Sizes">
+<title>Computing Character String Sizes</title>
+<!-- .XS -->
+<!-- (SN Computing Character String Sizes  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to compute the width,
+the logical extents, 
+and the server information about 8-bit and 2-byte text strings.
+<indexterm><primary>XTextWidth</primary></indexterm>
+<indexterm><primary>XTextWidth16</primary></indexterm>
+The width is computed by adding the character widths of all the characters.
+It does not matter if the font is an 8-bit or 2-byte font.
+These functions return the sum of the character metrics in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine the width of an 8-bit character string, use
+<function>XTextWidth</function>.
+<indexterm significance="preferred"><primary>XTextWidth</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xtextwidth'>
+<funcprototype>
+  <funcdef>int <function>XTextWidth</function></funcdef>
+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_struct</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font used for the width computation.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character count in the specified string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To determine the width of a 2-byte character string, use
+<function>XTextWidth16</function>.
+<indexterm significance="preferred"><primary>XTextWidth16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xtextwidth16'>
+<funcprototype>
+  <funcdef>int <function>XTextWidth16</function></funcdef>
+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_struct</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font used for the width computation.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character count in the specified string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Computing_Logical_Extents">
+<title>Computing Logical Extents</title>
+<!-- .XS -->
+<!-- (SN Computing Logical Extents  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To compute the bounding box of an 8-bit character string in a given font, use
+<function>XTextExtents</function>.
+<indexterm significance="preferred"><primary>XTextExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xtextextents'>
+<funcprototype>
+  <funcdef><function>XTextExtents</function></funcdef>
+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> nchars</parameter></paramdef>
+  <paramdef>int<parameter> *direction_return</parameter></paramdef>
+  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
+  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_struct</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XFontStruct</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>direction_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the value of the direction hint
+(<symbol>FontLeftToRight</symbol>
+or
+<symbol>FontRightToLeft</symbol>).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_ascent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font ascent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_descent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font descent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>overall_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the overall size in the specified
+<structname>XCharStruct</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To compute the bounding box of a 2-byte character string in a given font, use
+<function>XTextExtents16</function>.
+<indexterm significance="preferred"><primary>XTextExtents16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xtextextents16'>
+<funcprototype>
+  <funcdef><function>XTextExtents16</function></funcdef>
+  <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> nchars</parameter></paramdef>
+  <paramdef>int<parameter> *direction_return</parameter></paramdef>
+  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
+  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_struct</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XFontStruct</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>direction_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the value of the direction hint
+(<symbol>FontLeftToRight</symbol>
+or
+<symbol>FontRightToLeft</symbol>).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_ascent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font ascent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_descent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font descent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>overall_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the overall size in the specified
+<structname>XCharStruct</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XTextExtents</function>
+and
+<function>XTextExtents16</function>
+functions 
+perform the size computation locally and, thereby,
+avoid the round-trip overhead of
+<function>XQueryTextExtents</function>
+and
+<function>XQueryTextExtents16</function>.
+Both functions return an
+<structname>XCharStruct</structname>
+structure, whose members are set to the values as follows.
+</para>
+<para>
+<!-- .LP -->
+The ascent member is set to the maximum of the ascent metrics of all
+characters in the string.
+The descent member is set to the maximum of the descent metrics.
+The width member is set to the sum of the character-width metrics of all
+characters in the string.
+For each character in the string,
+let W be the sum of the character-width metrics of all characters preceding 
+it in the string.
+Let L be the left-side-bearing metric of the character plus W.
+Let R be the right-side-bearing metric of the character plus W.
+The lbearing member is set to the minimum L of all characters in the string.
+The rbearing member is set to the maximum R.
+</para>
+<para>
+<!-- .LP -->
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each 
+<structname>XChar2b</structname>
+structure is interpreted as a 16-bit number with byte1 as the 
+most significant byte.
+If the font has no defined default character,
+undefined characters in the string are taken to have all zero metrics.
+</para>
+</sect2>
+<sect2 id="Querying_Character_String_Sizes">
+<title>Querying Character String Sizes</title>
+<!-- .XS -->
+<!-- (SN Querying Character String Sizes  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To query the server for the bounding box of an 8-bit character string in a 
+given font, use 
+<function>XQueryTextExtents</function>.
+<indexterm significance="preferred"><primary>XQueryTextExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerytextextents'>
+<funcprototype>
+  <funcdef><function>XQueryTextExtents</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XID<parameter> font_ID</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> nchars</parameter></paramdef>
+  <paramdef>int<parameter> *direction_return</parameter></paramdef>
+  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
+  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_ID</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies either the font ID or the 
+<type>GContext</type>
+ID that contains the font.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>direction_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the value of the direction hint
+(<symbol>FontLeftToRight</symbol>
+or
+<symbol>FontRightToLeft</symbol>).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_ascent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font ascent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_descent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font descent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>overall_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the overall size in the specified
+<structname>XCharStruct</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To query the server for the bounding box of a 2-byte character string
+in a given font, use
+<function>XQueryTextExtents16</function>.
+<indexterm significance="preferred"><primary>XQueryTextExtents16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerytextextents16'>
+<funcprototype>
+  <funcdef><function>XQueryTextExtents16</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XID<parameter> font_ID</parameter></paramdef>
+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> nchars</parameter></paramdef>
+  <paramdef>int<parameter> *direction_return</parameter></paramdef>
+  <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
+  <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_ID</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies either the font ID or the 
+<type>GContext</type>
+ID that contains the font.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>direction_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the value of the direction hint
+(<symbol>FontLeftToRight</symbol>
+or
+<symbol>FontRightToLeft</symbol>).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_ascent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font ascent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_descent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the font descent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>overall_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the overall size in the specified
+<structname>XCharStruct</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryTextExtents</function>
+and
+<function>XQueryTextExtents16</function>
+functions return the bounding box of the specified 8-bit and 16-bit
+character string in the specified font or the font contained in the
+specified GC.
+These functions query the X server and, therefore, suffer the round-trip
+overhead that is avoided by
+<function>XTextExtents</function>
+and 
+<function>XTextExtents16</function>.
+Both functions return a
+<structname>XCharStruct</structname>
+structure, whose members are set to the values as follows.
+</para>
+<para>
+<!-- .LP -->
+The ascent member is set to the maximum of the ascent metrics 
+of all characters in the string.
+The descent member is set to the maximum of the descent metrics.
+The width member is set to the sum of the character-width metrics 
+of all characters in the string.
+For each character in the string,
+let W be the sum of the character-width metrics of all characters preceding
+it in the string.
+Let L be the left-side-bearing metric of the character plus W.
+Let R be the right-side-bearing metric of the character plus W.
+The lbearing member is set to the minimum L of all characters in the string.
+The rbearing member is set to the maximum R.
+</para>
+<para>
+<!-- .LP -->
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each 
+<structname>XChar2b</structname>
+structure is interpreted as a 16-bit number with byte1 as the 
+most significant byte.
+If the font has no defined default character,
+undefined characters in the string are taken to have all zero metrics.
+</para>
+<para>
+<!-- .LP -->
+Characters with all zero metrics are ignored.
+If the font has no defined default_char,
+the undefined characters in the string are also ignored.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryTextExtents</function>
+and
+<function>XQueryTextExtents16</function>
+can generate
+<errorname>BadFont</errorname>
+and
+<errorname>BadGC</errorname>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Drawing_Text">
+<title>Drawing Text</title>
+<!-- .XS -->
+<!-- (SN Drawing Text -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to draw:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Complex text 
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Text characters
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Image text characters
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The fundamental text functions
+<function>XDrawText</function>
+and
+<function>XDrawText16</function>
+use the following structures:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XTextItem</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     char *chars;     /* pointer to string */
+     int nchars;      /* number of characters */
+     int delta;       /* delta between strings */
+     Font font;       /* Font to print it in, None don't change */
+} XTextItem;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XTextItem16</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     XChar2b *chars;     /* pointer to two-byte characters */
+     int nchars;         /* number of characters */
+     int delta;         /* delta between strings */
+     Font font;         /* font to print it in, None don't change */
+} XTextItem16;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the font member is not
+<symbol>None</symbol>,
+the font is changed before printing and also is stored in the GC.
+If an error was generated during text drawing,
+the previous items may have been drawn.
+The baseline of the characters are drawn starting at the x and y
+coordinates that you pass in the text drawing functions.
+</para>
+<para>
+<!-- .LP -->
+For example, consider the background rectangle drawn by
+<function>XDrawImageString</function>.
+If you want the upper-left corner of the background rectangle
+to be at pixel coordinate (x,y), pass the (x,y + ascent)
+as the baseline origin coordinates to the text functions.
+The ascent is the font ascent, as given in the
+<structname>XFontStruct</structname>
+structure.
+If you want the lower-left corner of the background rectangle
+to be at pixel coordinate (x,y), pass the (x,y - descent + 1)
+as the baseline origin coordinates to the text functions.
+The descent is the font descent, as given in the
+<structname>XFontStruct</structname>
+structure.
+</para>
+<sect2 id="Drawing_Complex_Text">
+<title>Drawing Complex Text</title>
+<!-- .XS -->
+<!-- (SN Drawing Complex Text  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Text</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>text items</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+To draw 8-bit characters in a given drawable, use
+<function>XDrawText</function>.
+<indexterm significance="preferred"><primary>XDrawText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawtext'>
+<funcprototype>
+  <funcdef><function>XDrawText</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>XTextItem<parameter> *items</parameter></paramdef>
+  <paramdef>int<parameter> nitems</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>items</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of text items.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nitems</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of text items in the array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte characters in a given drawable, use
+<function>XDrawText16</function>.
+<indexterm significance="preferred"><primary>XDrawText16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawtext16'>
+<funcprototype>
+  <funcdef><function>XDrawText16</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>XTextItem16<parameter> *items</parameter></paramdef>
+  <paramdef>int<parameter> nitems</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>items</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of text items.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nitems</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of text items in the array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawText16</function>
+function is similar to
+<function>XDrawText</function>
+except that it uses 2-byte or 16-bit characters.
+Both functions allow complex spacing and font shifts between counted strings.
+</para>
+<para>
+<!-- .LP -->
+Each text item is processed in turn.
+A font member other than 
+<symbol>None</symbol>
+in an item causes the font to be stored in the GC
+and used for subsequent text.  
+A text element delta specifies an additional change
+in the position along the x axis before the string is drawn. 
+The delta is always added to the character origin
+and is not dependent on any characteristics of the font.
+Each character image, as defined by the font in the GC, is treated as an
+additional mask for a fill operation on the drawable.
+The drawable is modified only where the font character has a bit set to 1.
+If a text item generates a
+<errorname>BadFont</errorname>
+error, the previous text items may have been drawn.
+</para>
+<para>
+<!-- .LP -->
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each 
+<structname>XChar2b</structname>
+structure is interpreted as a 16-bit number with byte1 as the 
+most significant byte.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components:
+function, plane-mask, fill-style, font, subwindow-mode, 
+clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawText</function>
+and
+<function>XDrawText16</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadFont</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Text_Characters">
+<title>Drawing Text Characters</title>
+<!-- .XS -->
+<!-- (SN Drawing Text Characters  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Strings</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>strings</secondary></indexterm>
+To draw 8-bit characters in a given drawable, use
+<function>XDrawString</function>.
+<indexterm significance="preferred"><primary>XDrawString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawstring'>
+<funcprototype>
+  <funcdef><function>XDrawString</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte characters in a given drawable, use
+<function>XDrawString16</function>.
+<indexterm significance="preferred"><primary>XDrawString16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawstring16'>
+<funcprototype>
+  <funcdef><function>XDrawString16</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Each character image, as defined by the font in the GC, is treated as an
+additional mask for a fill operation on the drawable.
+The drawable is modified only where the font character has a bit set to 1.
+For fonts defined with 2-byte matrix indexing
+and used with
+<function>XDrawString16</function>,
+each byte is used as a byte2 with a byte1 of zero.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components: 
+function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, 
+clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawString</function>
+and
+<function>XDrawString16</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Drawing_Image_Text_Characters">
+<title>Drawing Image Text Characters</title>
+<!-- .XS -->
+<!-- (SN Drawing Image Text Characters  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Image text</primary><secondary>drawing</secondary></indexterm>
+<indexterm><primary>Drawing</primary><secondary>image text</secondary></indexterm>
+Some applications, in particular terminal emulators, need to
+print image text in which both the foreground and background bits of
+each character are painted.
+This prevents annoying flicker on many displays.
+<indexterm><primary>XDrawImageString</primary></indexterm>
+<indexterm><primary>XDrawImageString16</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To draw 8-bit image text characters in a given drawable, use
+<function>XDrawImageString</function>.
+<indexterm significance="preferred"><primary>XDrawImageString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawimagestring'>
+<funcprototype>
+  <funcdef><function>XDrawImageString</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte image text characters in a given drawable, use
+<function>XDrawImageString16</function>.
+<indexterm significance="preferred"><primary>XDrawImageString16</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdrawimagestring16'>
+<funcprototype>
+  <funcdef><function>XDrawImageString16</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>XChar2b<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
+and define the origin of the first character
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDrawImageString16</function>
+function is similar to
+<function>XDrawImageString</function>
+except that it uses 2-byte or 16-bit characters.
+Both functions also use both the foreground and background pixels 
+of the GC in the destination.
+</para>
+<para>
+<!-- .LP -->
+The effect is first to fill a
+destination rectangle with the background pixel defined in the GC and then
+to paint the text with the foreground pixel.
+The upper-left corner of the filled rectangle is at:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+[x, y - font-ascent]
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The width is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+overall-width
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The height is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+font-ascent + font-descent
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The overall-width, font-ascent, and font-descent
+are as would be returned by 
+<function>XQueryTextExtents</function>
+using gc and string.
+The function and fill-style defined in the GC are ignored for these functions. 
+The effective function is 
+<symbol>GXcopy</symbol>,
+and the effective fill-style is
+<symbol>FillSolid</symbol>.
+</para>
+<para>
+<!-- .LP -->
+For fonts defined with 2-byte matrix indexing
+and used with
+<function>XDrawImageString</function>,
+each byte is used as a byte2 with a byte1 of zero.
+</para>
+<para>
+<!-- .LP -->
+Both functions use these GC components: 
+plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, 
+clip-y-origin, and clip-mask.
+</para>
+<para>
+<!-- .LP -->
+<function>XDrawImageString</function>
+and
+<function>XDrawImageString16</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect2>
+</sect1>
+<sect1 id="Transferring_Images_between_Client_and_Server">
+<title>Transferring Images between Client and Server</title>
+<!-- .XS -->
+<!-- (SN Transferring Images between Client and Server  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to transfer images between a client 
+and the server.
+Because the server may require diverse data formats, 
+Xlib provides an image object that fully describes the data in memory 
+and that provides for basic operations on that data.  
+You should reference the data 
+through the image object rather than referencing the data directly.
+However, some implementations of the Xlib library may efficiently deal with 
+frequently used data formats by replacing
+functions in the procedure vector with special case functions.
+Supported operations include destroying the image, getting a pixel,
+storing a pixel, extracting a subimage of an image, and adding a constant
+to an image (see section 16.8).
+</para>
+<para>
+<!-- .LP -->
+All the image manipulation functions discussed in this section make use of 
+the 
+<structname>XImage</structname>
+structure,
+which describes an image as it exists in the client's memory.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XImage</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 3i -->
+<!-- .ta .5i 1i 3i -->
+typedef struct _XImage {
+     int width, height;         /* size of image */
+     int xoffset;               /* number of pixels offset in X direction */
+     int format;                /* XYBitmap, XYPixmap, ZPixmap */
+     char *data;                /* pointer to image data */
+     int byte_order;            /* data byte order, LSBFirst, MSBFirst */
+     int bitmap_unit;           /* quant. of scanline 8, 16, 32 */
+     int bitmap_bit_order;      /* LSBFirst, MSBFirst */
+     int bitmap_pad;            /* 8, 16, 32 either XY or ZPixmap */
+     int depth;                 /* depth of image */
+     int bytes_per_line;        /* accelerator to next scanline */
+     int bits_per_pixel;        /* bits per pixel (ZPixmap) */
+     unsigned long red_mask;    /* bits in z arrangement */
+     unsigned long green_mask;
+     unsigned long blue_mask;
+     XPointer obdata;           /* hook for the object routines to hang on */
+     struct funcs {             /* image manipulation routines */
+          struct _XImage *(*create_image)();
+          int             (*destroy_image)();
+          unsigned long   (*get_pixel)();
+          int             (*put_pixel)();
+          struct _XImage  *(*sub_image)();
+          int            (*add_pixel)();
+     } f;
+} XImage;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To initialize the image manipulation routines of an image structure, use
+<function>XInitImage</function>.
+<indexterm significance="preferred"><primary>XInitImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xinitimage'>
+<funcprototype>
+  <funcdef>Status <function>XInitImage</function></funcdef>
+  <paramdef>XImage<parameter> *image</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ximage</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the image.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInitImage</function>
+function initializes the internal image manipulation routines of an
+image structure, based on the values of the various structure members.
+All fields other than the manipulation routines must already be initialized.
+If the bytes_per_line member is zero,
+<function>XInitImage</function>
+will assume the image data is contiguous in memory and set the
+bytes_per_line member to an appropriate value based on the other
+members; otherwise, the value of bytes_per_line is not changed.
+All of the manipulation routines are initialized to functions
+that other Xlib image manipulation functions need to operate on the
+type of image specified by the rest of the structure.
+</para>
+<para>
+<!-- .LP -->
+This function must be called for any image constructed by the client
+before passing it to any other Xlib function.
+Image structures created or returned by Xlib do not need to be
+initialized in this fashion.
+</para>
+<para>
+<!-- .LP -->
+This function returns a nonzero status if initialization of the
+structure is successful.  It returns zero if it detected some error
+or inconsistency in the structure, in which case the image is not changed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To combine an image with a rectangle of a drawable on the display,
+use
+<function>XPutImage</function>.
+<indexterm significance="preferred"><primary>XPutImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xputimage'>
+<funcprototype>
+  <funcdef><function>XPutImage</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>XImage<parameter> *image</parameter></paramdef>
+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>image</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the image you want combined with the rectangle. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the offset in X from the left edge of the image defined
+by the 
+<structname>XImage</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the offset in Y from the top edge of the image defined
+by the 
+<structname>XImage</structname>
+structure.
+<!-- .ds Dx , which are relative to the origin of the drawable \ -->
+and are the coordinates of the subimage
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Dx. 
+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPutImage</function>
+function
+combines an image with a rectangle of the specified drawable.
+The section of the image defined by the src_x, src_y, width, and height 
+arguments is drawn on the specified part of the drawable.
+If 
+<symbol>XYBitmap</symbol>
+format is used, the depth of the image must be one,
+or a
+<errorname>BadMatch</errorname>
+error results.
+The foreground pixel in the GC defines the source for the one bits in the image,
+and the background pixel defines the source for the zero bits.
+For 
+<symbol>XYPixmap</symbol>
+and 
+<symbol>ZPixmap</symbol>,
+the depth of the image must match the depth of the drawable,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If the characteristics of the image (for example, byte_order and bitmap_unit)
+differ from what the server requires,
+<function>XPutImage</function>
+automatically makes the appropriate
+conversions.
+</para>
+<para>
+<!-- .LP -->
+This function uses these GC components: 
+function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, 
+and clip-mask.
+It also uses these GC mode-dependent components:
+foreground and background.
+</para>
+<para>
+<!-- .LP -->
+<function>XPutImage</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the contents of a rectangle in a given drawable on the display,
+use
+<function>XGetImage</function>.
+This function specifically supports rudimentary screen dumps.
+<indexterm significance="preferred"><primary>XGetImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetimage'>
+<funcprototype>
+  <funcdef>XImage *<function>XGetImage</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
+  <paramdef>int<parameter> format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and define the upper-left corner of the rectangle
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>plane_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the plane mask.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the format for the image.
+You can pass
+<symbol>XYPixmap</symbol>
+or 
+<symbol>ZPixmap</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetImage</function>
+function returns a pointer to an
+<structname>XImage</structname>
+structure.
+This structure provides you with the contents of the specified rectangle of
+the drawable in the format you specify.
+If the format argument is 
+<symbol>XYPixmap</symbol>,
+the image contains only the bit planes you passed to the plane_mask argument.
+If the plane_mask argument only requests a subset of the planes of the
+display, the depth of the returned image will be the number of planes
+requested.
+If the format argument is 
+<symbol>ZPixmap</symbol>,
+<function>XGetImage</function>
+returns as zero the bits in all planes not 
+specified in the plane_mask argument.
+The function performs no range checking on the values in plane_mask and ignores
+extraneous bits.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetImage</function>
+returns the depth of the image to the depth member of the
+<structname>XImage</structname>
+structure.
+The depth of the image is as specified when the drawable was created,
+except when getting a subset of the planes in 
+<symbol>XYPixmap</symbol>
+format, when the depth is given by the number of bits set to 1 in plane_mask.
+</para>
+<para>
+<!-- .LP -->
+If the drawable is a pixmap, 
+the given rectangle must be wholly contained within the pixmap, 
+or a
+<errorname>BadMatch</errorname>
+error results.
+If the drawable is a window, 
+the window must be viewable, 
+and it must be the case that if there were no inferiors or overlapping windows,
+the specified rectangle of the window would be fully visible on the screen
+and wholly contained within the outside edges of the window,
+or a
+<errorname>BadMatch</errorname>
+error results.
+Note that the borders of the window can be included and read with
+this request.
+If the window has backing-store, the backing-store contents are
+returned for regions of the window that are obscured by noninferior
+windows. 
+If the window does not have backing-store,
+the returned contents of such obscured regions are undefined.
+The returned contents of visible regions of inferiors
+of a different depth than the specified window's depth are also undefined.
+The pointer cursor image is not included in the returned contents.
+If a problem occurs,
+<function>XGetImage</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetImage</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To copy the contents of a rectangle on the display
+to a location within a preexisting image structure, use
+<function>XGetSubImage</function>.
+<indexterm significance="preferred"><primary>XGetSubImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetsubimage'>
+<funcprototype>
+  <funcdef>XImage *<function>XGetSubImage</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
+  <paramdef>int<parameter> format</parameter></paramdef>
+  <paramdef>XImage<parameter> *dest_image</parameter></paramdef>
+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+<!-- .ds Xy , which are relative to the origin of the drawable \ -->
+and define the upper-left corner of the rectangle
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>plane_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the plane mask.
+<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the format for the image.
+You can pass
+<symbol>XYPixmap</symbol>
+or 
+<symbol>ZPixmap</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_image</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the destination image.
+<!-- .ds Dx , which are relative to the origin of the destination rectangle, \ -->
+specify its upper-left corner, and determine where the subimage \
+is placed in the destination image
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Dx. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetSubImage</function>
+function updates dest_image with the specified subimage in the same manner as 
+<function>XGetImage</function>.
+If the format argument is 
+<symbol>XYPixmap</symbol>,
+the image contains only the bit planes you passed to the plane_mask argument.
+If the format argument is 
+<symbol>ZPixmap</symbol>,
+<function>XGetSubImage</function>
+returns as zero the bits in all planes not 
+specified in the plane_mask argument.
+The function performs no range checking on the values in plane_mask and ignores
+extraneous bits.
+As a convenience,
+<function>XGetSubImage</function>
+returns a pointer to the same
+<structname>XImage</structname>
+structure specified by dest_image.
+</para>
+<para>
+<!-- .LP -->
+The depth of the destination
+<structname>XImage</structname>
+structure must be the same as that of the drawable.
+If the specified subimage does not fit at the specified location
+on the destination image, the right and bottom edges are clipped.
+If the drawable is a pixmap,
+the given rectangle must be wholly contained within the pixmap,
+or a
+<errorname>BadMatch</errorname>
+error results.
+If the drawable is a window, 
+the window must be viewable, 
+and it must be the case that if there were no inferiors or overlapping windows,
+the specified rectangle of the window would be fully visible on the screen
+and wholly contained within the outside edges of the window,
+or a
+<errorname>BadMatch</errorname>
+error results.
+If the window has backing-store, 
+then the backing-store contents are returned for regions of the window 
+that are obscured by noninferior windows. 
+If the window does not have backing-store, 
+the returned contents of such obscured regions are undefined.
+The returned contents of visible regions of inferiors
+of a different depth than the specified window's depth are also undefined.
+If a problem occurs,
+<function>XGetSubImage</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetSubImage</function>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH09.xml b/libX11/specs/libX11/CH09.xml
index 7d0f779f1..eff97c39c 100644
--- a/libX11/specs/libX11/CH09.xml
+++ b/libX11/specs/libX11/CH09.xml
@@ -1,2016 +1,2016 @@
-<?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="window_and_session_manager_functions">

-<title>Window and Session Manager Functions</title>

-

-<para>

-Although it is difficult to categorize functions as exclusively for an application,

-a window manager, or a session manager, the functions in this chapter are most

-often used by window managers and session managers. It is not expected that

-these functions will be used by most application programs. Xlib provides

-management functions to:

-</para>

-

-<itemizedlist>

-  <listitem><para>Change the parent of a window</para></listitem>

-  <listitem><para>Control the lifetime of a window</para></listitem>

-  <listitem><para>Manage installed colormaps</para></listitem>

-  <listitem><para>Set and retrieve the font search path</para></listitem>

-  <listitem><para>Grab the server</para></listitem>

-  <listitem><para>Kill a client</para></listitem>

-  <listitem><para>Control the screen saver</para></listitem>

-  <listitem><para>Control host access</para></listitem>

-</itemizedlist>

-

-<sect1 id="Changing_the_Parent_of_a_Window">

-<title>Changing the Parent of a Window</title>

-<!-- .XS -->

-<!-- (SN Changing the Parent of a Window  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To change a window's parent to another window on the same screen, use

-<function>XReparentWindow</function>.

-There is no way to move a window between screens.

-<indexterm significance="preferred"><primary>XReparentWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XReparentWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Window<parameter> parent</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>parent</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the parent window.

-<!-- .ds Xy \ of the position in the new parent window -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If the specified window is mapped,

-<function>XReparentWindow</function>

-automatically performs an

-<systemitem>UnmapWindow</systemitem>

-request on it, removes it from its current position in the hierarchy,

-and inserts it as the child of the specified parent.

-The window is placed in the stacking order on top with respect to

-sibling windows.

-</para>

-<para>

-<!-- .LP -->

-After reparenting the specified window,

-<function>XReparentWindow</function>

-causes the X server to generate a

-<symbol>ReparentNotify</symbol>

-event.

-The override_redirect member returned in this event is

-set to the window's corresponding attribute.

-Window manager clients usually should ignore this window if this member

-is set to

-<symbol>True</symbol>.

-Finally, if the specified window was originally mapped,

-the X server automatically performs a

-<systemitem>MapWindow</systemitem>

-request on it.

-</para>

-<para>

-<!-- .LP -->

-The X server performs normal exposure processing on formerly obscured

-windows.

-The X server might not generate 

-<symbol>Expose</symbol>

-events for regions from the initial

-<systemitem>UnmapWindow</systemitem>

-request that are immediately obscured by the final

-<systemitem>MapWindow</systemitem>

-request.

-A

-<errorname>BadMatch</errorname>

-error results if:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The new parent window is not on the same screen as

-the old parent window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The new parent window is the specified window or an inferior of the

-specified window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The new parent is

-<symbol>InputOnly</symbol>,

-and the window is not.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The specified window has a

-<symbol>ParentRelative</symbol>

-background, and the new parent window is not the same depth as the

-specified window.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-<function>XReparentWindow</function>

-can generate

-<errorname>BadMatch</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Controlling_the_Lifetime_of_a_Window">

-<title>Controlling the Lifetime of a Window</title>

-<!-- .XS -->

-<!-- (SN Controlling the Lifetime of a Window  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The save-set of a client is a list of other clients' windows that,

-if they are inferiors of one of the client's windows at connection close,

-should not be destroyed and should be remapped if they are unmapped.

-For further information about close-connection processing,

-see section 2.6.

-To allow an application's window to survive when a window manager that

-has reparented a window fails,

-Xlib provides the save-set functions that you can 

-use to control the longevity of subwindows

-that are normally destroyed when the parent is destroyed.

-For example, a window manager that wants to add decoration

-to a window by adding a frame might reparent an application's

-window. 

-When the frame is destroyed,

-the application's window should not be destroyed 

-but be returned to its previous place in the window hierarchy.

-</para>

-<para>

-<!-- .LP -->

-The X server automatically removes windows from the save-set

-when they are destroyed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To add or remove a window from the client's save-set, use

-<function>XChangeSaveSet</function>.

-<indexterm significance="preferred"><primary>XChangeSaveSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XChangeSaveSet</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> change_mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi that you want to add to or delete from the client's save-set -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>change_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the mode.

-You can pass

-<symbol>SetModeInsert</symbol>

-or

-<symbol>SetModeDelete</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Depending on the specified mode,

-<function>XChangeSaveSet</function>

-either inserts or deletes the specified window from the client's save-set. 

-The specified window must have been created by some other client,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XChangeSaveSet</function>

-can generate

-<errorname>BadMatch</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To add a window to the client's save-set, use

-<function>XAddToSaveSet</function>.

-<indexterm significance="preferred"><primary>XAddToSaveSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAddToSaveSet</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi that you want to add to the client's save-set -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAddToSaveSet</function>

-function adds the specified window to the client's save-set.

-The specified window must have been created by some other client,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XAddToSaveSet</function>

-can generate

-<errorname>BadMatch</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove a window from the client's save-set, use

-<function>XRemoveFromSaveSet</function>.

-<indexterm significance="preferred"><primary>XRemoveFromSaveSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRemoveFromSaveSet</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi that you want to delete from the client's save-set -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRemoveFromSaveSet</function>

-function removes the specified window from the client's save-set.

-The specified window must have been created by some other client,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XRemoveFromSaveSet</function>

-can generate

-<errorname>BadMatch</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Managing_Installed_Colormaps">

-<title>Managing Installed Colormaps</title>

-<!-- .XS -->

-<!-- (SN Managing Installed Colormaps -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The X server maintains a list of installed colormaps.

-Windows using these colormaps are guaranteed to display with

-correct colors; windows using other colormaps may or may not display

-with correct colors.

-Xlib provides functions that you can use to install a colormap, 

-uninstall a colormap, and obtain a list of installed colormaps.

-</para>

-<para>

-<!-- .LP -->

-At any time,

-there is a subset of the installed maps that is viewed as an ordered list

-and is called the required list.

-The length of the required list is at most M,

-where M is the minimum number of installed colormaps specified for the screen

-in the connection setup.

-The required list is maintained as follows.

-When a colormap is specified to

-<function>XInstallColormap</function>,

-it is added to the head of the list;

-the list is truncated at the tail, if necessary, to keep its length to 

-at most M.

-When a colormap is specified to

-<function>XUninstallColormap</function>

-and it is in the required list,

-it is removed from the list.

-A colormap is not added to the required list when it is implicitly installed

-by the X server,

-and the X server cannot implicitly uninstall a colormap that is in the

-required list.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To install a colormap, use

-<function>XInstallColormap</function>.

-<indexterm significance="preferred"><primary>XInstallColormap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XInstallColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XInstallColormap</function>

-function installs the specified colormap for its associated screen.

-All windows associated with this colormap immediately display with

-true colors.

-You associated the windows with this colormap when you created them by calling

-<function>XCreateWindow</function>,

-<function>XCreateSimpleWindow</function>,

-<function>XChangeWindowAttributes</function>,

-or

-<function>XSetWindowColormap</function>.

-</para>

-<para>

-<!-- .LP -->

-If the specified colormap is not already an installed colormap, 

-the X server generates a

-<symbol>ColormapNotify</symbol>

-event on each window that has that colormap.

-In addition, for every other colormap that is installed as 

-a result of a call to

-<function>XInstallColormap</function>,

-the X server generates a

-<symbol>ColormapNotify</symbol>

-event on each window that has that colormap.

-</para>

-<para>

-<!-- .LP -->

-<function>XInstallColormap</function>

-can generate a

-<errorname>BadColor</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To uninstall a colormap, use

-<function>XUninstallColormap</function>.

-<indexterm significance="preferred"><primary>XUninstallColormap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUninstallColormap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Colormap<parameter> colormap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the colormap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUninstallColormap</function>

-function removes the specified colormap from the required

-list for its screen.

-As a result,

-the specified colormap might be uninstalled, 

-and the X server might implicitly install or uninstall additional colormaps.

-Which colormaps get installed or uninstalled is server dependent

-except that the required list must remain installed.

-</para>

-<para>

-<!-- .LP -->

-If the specified colormap becomes uninstalled, 

-the X server generates a

-<symbol>ColormapNotify</symbol>

-event on each window that has that colormap.

-In addition, for every other colormap that is installed or uninstalled as a 

-result of a call to 

-<function>XUninstallColormap</function>,

-the X server generates a

-<symbol>ColormapNotify</symbol>

-event on each window that has that colormap.

-</para>

-<para>

-<!-- .LP -->

-<function>XUninstallColormap</function>

-can generate a

-<errorname>BadColor</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a list of the currently installed colormaps for a given screen, use

-<function>XListInstalledColormaps</function>.

-<indexterm significance="preferred"><primary>XListInstalledColormaps</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Colormap *<function>XListInstalledColormaps</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> *num_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi that determines the screen -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of currently installed colormaps.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XListInstalledColormaps</function>

-function returns a list of the currently installed colormaps for the screen 

-of the specified window.

-The order of the colormaps in the list is not significant

-and is no explicit indication of the required list.

-When the allocated list is no longer needed,

-free it by using

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XListInstalledColormaps</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Setting_and_Retrieving_the_Font_Search_Path">

-<title>Setting and Retrieving the Font Search Path</title>

-<!-- .XS -->

-<!-- (SN Setting and Retrieving the Font Search Path  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The set of fonts available from a server depends on a font

-search path.  Xlib provides functions to set and retrieve the

-search path for a server.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the font search path, use

-<function>XSetFontPath</function>.

-<indexterm significance="preferred"><primary>XSetFontPath</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetFontPath</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> **directories</parameter></paramdef>

-  <paramdef>int<parameter> ndirs</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>directories</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the directory path used to look for a font.

-Setting the path to the empty list restores the default path defined

-for the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ndirs</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of directories in the path.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetFontPath</function>

-function defines the directory search path for font lookup.

-There is only one search path per X server, not one per client.

-The encoding and interpretation of the strings are implementation-dependent,

-but typically they specify directories or font servers to be searched 

-in the order listed.

-An X server is permitted to cache font information internally;

-for example, it might cache an entire font from a file and not

-check on subsequent opens of that font to see if the underlying

-font file has changed.

-However,

-when the font path is changed,

-the X server is guaranteed to flush all cached information about fonts 

-for which there currently are no explicit resource IDs allocated.

-The meaning of an error from this request is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetFontPath</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the current font search path, use

-<function>XGetFontPath</function>.

-<indexterm significance="preferred"><primary>XGetFontPath</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char **<function>XGetFontPath</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> *npaths_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>npaths_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of strings in the font path array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetFontPath</function>

-function allocates and returns an array of strings containing the search path.

-The contents of these strings are implementation-dependent

-and are not intended to be interpreted by client applications.

-When it is no longer needed,

-the data in the font path should be freed by using

-<function>XFreeFontPath</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To free data returned by

-<function>XGetFontPath</function>,

-use

-<function>XFreeFontPath</function>.

-<indexterm significance="preferred"><primary>XFreeFontPath</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeFontPath</function></funcdef>

-  <paramdef>char<parameter> **list</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the array of strings you want to free.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeFontPath</function>

-function

-frees the data allocated by

-<function>XGetFontPath</function>.

-</para>

-</sect1>

-<sect1 id="Grabbing_the_Server_">

-<title>Grabbing the Server </title>

-<!-- .XS -->

-<!-- (SN Grabbing the Server  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to grab and ungrab the server.

-These functions can be used to control processing of output on other

-connections by the window system server.

-While the server is grabbed,

-no processing of requests or close downs on any other connection will occur.

-A client closing its connection automatically ungrabs the server.

-<indexterm><primary>Menus</primary></indexterm>

-<indexterm><primary>Window</primary><secondary>managers</secondary></indexterm>

-Although grabbing the server is highly discouraged, it is sometimes necessary.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To grab the server, use

-<function>XGrabServer</function>.

-<indexterm><primary>Server</primary><secondary>grabbing</secondary></indexterm>

-<indexterm><primary>Grabbing</primary><secondary>server</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGrabServer</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGrabServer</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGrabServer</function>

-function disables processing of requests and close downs on all other 

-connections than the one this request arrived on.

-You should not grab the X server any more than is absolutely necessary.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To ungrab the server, use

-<function>XUngrabServer</function>.

-<indexterm significance="preferred"><primary>XUngrabServer</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUngrabServer</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUngrabServer</function>

-function restarts processing of requests and close downs on other connections.

-You should avoid grabbing the X server as much as possible.

-</para>

-</sect1>

-<sect1 id="Killing_Clients">

-<title>Killing Clients</title>

-<!-- .XS -->

-<!-- (SN Killing Clients  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides a function to cause the connection to

-a client to be closed and its resources to be destroyed.

-To destroy a client, use

-<function>XKillClient</function>.

-<indexterm significance="preferred"><primary>XKillClient</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XKillClient</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XID<parameter> resource</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>resource</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies any resource associated with the client that you want to destroy or

-<symbol>AllTemporary</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XKillClient</function>

-function

-forces a close down of the client

-that created the resource

-if a valid resource is specified.

-If the client has already terminated in

-either 

-<symbol>RetainPermanent</symbol>

-or 

-<symbol>RetainTemporary</symbol>

-mode, all of the client's

-resources are destroyed.

-If 

-<symbol>AllTemporary</symbol>

-is specified, the resources of all clients that have terminated in

-<symbol>RetainTemporary</symbol>

-are destroyed (see section 2.5).

-This permits implementation of window manager facilities that aid debugging.

-A client can set its close-down mode to

-<symbol>RetainTemporary</symbol>.

-If the client then crashes,

-its windows would not be destroyed. 

-The programmer can then inspect the application's window tree 

-and use the window manager to destroy the zombie windows.

-</para>

-<para>

-<!-- .LP -->

-<function>XKillClient</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Controlling_the_Screen_Saver_">

-<title>Controlling the Screen Saver </title>

-<!-- .XS -->

-<!-- (SN Controlling the Screen Saver  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set or reset the mode 

-of the screen saver, to force or activate the screen saver,

-or to obtain the current screen saver values.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the screen saver mode, use

-<function>XSetScreenSaver</function>.

-<indexterm significance="preferred"><primary>XSetScreenSaver</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetScreenSaver</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>inttimeout,<parameter> interval</parameter></paramdef>

-  <paramdef>int<parameter> prefer_blanking</parameter></paramdef>

-  <paramdef>int<parameter> allow_exposures</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>timeout</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the timeout, in seconds, until the screen saver turns on.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>interval</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the interval, in seconds, between screen saver alterations.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>prefer_blanking</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies how to enable screen blanking.

-You can pass

-<symbol>DontPreferBlanking</symbol>,

-<symbol>PreferBlanking</symbol>,

-or

-<symbol>DefaultBlanking</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>allow_exposures</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the screen save control values.

-You can pass

-<symbol>DontAllowExposures</symbol>,

-<symbol>AllowExposures</symbol>,

-or

-<symbol>DefaultExposures</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Timeout and interval are specified in seconds. 

-A timeout of 0 disables the screen saver 

-(but an activated screen saver is not deactivated),

-and a timeout of &minus;1 restores the default.

-Other negative values generate a

-<errorname>BadValue</errorname>

-error.

-If the timeout value is nonzero, 

-<function>XSetScreenSaver</function>

-enables the screen saver.

-An interval of 0 disables the random-pattern motion.

-If no input from devices (keyboard, mouse, and so on) is generated 

-for the specified number of timeout seconds once the screen saver is enabled,

-the screen saver is activated.

-</para>

-<para>

-<!-- .LP -->

-For each screen, 

-if blanking is preferred and the hardware supports video blanking, 

-the screen simply goes blank.  

-Otherwise, if either exposures are allowed or the screen can be regenerated 

-without sending 

-<symbol>Expose</symbol>

-events to clients, 

-the screen is tiled with the root window background tile randomly 

-re-origined each interval seconds.

-Otherwise, the screens' state do not change, 

-and the screen saver is not activated.

-The screen saver is deactivated,

-and all screen states are restored at the next

-keyboard or pointer input or at the next call to

-<function>XForceScreenSaver</function>

-with mode

-<symbol>ScreenSaverReset</symbol>.

-</para>

-<para>

-<!-- .LP -->

-If the server-dependent screen saver method supports periodic change,

-the interval argument serves as a hint about how long the change period

-should be, and zero hints that no periodic change should be made.

-Examples of ways to change the screen include scrambling the colormap

-periodically, moving an icon image around the screen periodically, or tiling

-the screen with the root window background tile, randomly re-origined

-periodically.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetScreenSaver</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To force the screen saver on or off, use

-<function>XForceScreenSaver</function>.

-<indexterm significance="preferred"><primary>XForceScreenSaver</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XForceScreenSaver</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the mode that is to be applied.

-You can pass

-<symbol>ScreenSaverActive</symbol>

-or

-<symbol>ScreenSaverReset</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If the specified mode is 

-<symbol>ScreenSaverActive</symbol>

-and the screen saver currently is deactivated,

-<function>XForceScreenSaver</function>

-activates the screen saver even if the screen saver had been disabled

-with a timeout of zero.

-If the specified mode is 

-<symbol>ScreenSaverReset</symbol>

-and the screen saver currently is enabled,

-<function>XForceScreenSaver</function>

-deactivates the screen saver if it was activated,

-and the activation timer is reset to its initial state 

-(as if device input had been received).

-</para>

-<para>

-<!-- .LP -->

-<function>XForceScreenSaver</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To activate the screen saver, use

-<function>XActivateScreenSaver</function>.

-<indexterm significance="preferred"><primary>XActivateScreenSaver</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XActivateScreenSaver</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To reset the screen saver, use

-<function>XResetScreenSaver</function>.

-<indexterm significance="preferred"><primary>XResetScreenSaver</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XResetScreenSaver</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To get the current screen saver values, use

-<function>XGetScreenSaver</function>.

-<indexterm significance="preferred"><primary>XGetScreenSaver</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGetScreenSaver</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int*timeout_return,<parameter> *interval_return</parameter></paramdef>

-  <paramdef>int<parameter> *prefer_blanking_return</parameter></paramdef>

-  <paramdef>int<parameter> *allow_exposures_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>timeout_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the timeout, in seconds, until the screen saver turns on.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>interval_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the interval between screen saver invocations.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>prefer_blanking_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the current screen blanking preference

-(<symbol>DontPreferBlanking</symbol>,

-<symbol>PreferBlanking</symbol>,

-or

-<symbol>DefaultBlanking</symbol>).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>allow_exposures_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the current screen save control value

-(<symbol>DontAllowExposures</symbol>,

-<symbol>AllowExposures</symbol>,

-or

-<symbol>DefaultExposures</symbol>).

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-</sect1>

-<sect1 id="Controlling_Host_Access">

-<title>Controlling Host Access</title>

-<!-- .XS -->

-<!-- (SN Controlling Host Access  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section discusses how to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Add, get, or remove hosts from the access control list

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Change, enable, or disable access

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-<indexterm><primary>Access control list</primary></indexterm>

-<indexterm><primary>Authentication</primary></indexterm>

-X does not provide any protection on a per-window basis.

-If you find out the resource ID of a resource, you can manipulate it.

-To provide some minimal level of protection, however,

-connections are permitted only from machines you trust.

-This is adequate on single-user workstations but obviously

-breaks down on timesharing machines.

-Although provisions exist in the X protocol for proper connection

-authentication, the lack of a standard authentication server

-leaves host-level access control as the only common mechanism.

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>Default Protection</primary></indexterm>

-The initial set of hosts allowed to open connections typically consists of:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The host the window system is running on.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-On <acronym>POSIX</acronym>-conformant systems, each host listed in the

-<filename>/etc/X<replaceable>?</replaceable>.hosts</filename>

-file.

-The ? indicates the number of the

-display.

-<indexterm><primary>Files</primary><secondary><filename>/etc/X<replaceable>?</replaceable>.hosts</filename></secondary></indexterm>

-This file should consist of host names separated by newlines.

-DECnet nodes must terminate in :: to distinguish them from Internet hosts.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-If a host is not in the access control list when the access control 

-mechanism is enabled and if the host attempts to establish a connection,

-the server refuses the connection.

-To change the access list,

-the client must reside on the same host as the server and/or must

-have been granted permission in the initial authorization at connection

-setup.

-</para>

-<para>

-<!-- .LP -->

-Servers also can implement other access control policies in addition to

-or in place of this host access facility.

-For further information about other access control implementations,

-see ``X Window System Protocol.''

-</para>

-<sect2 id="Adding_Getting_or_Removing_Hosts">

-<title>Adding, Getting, or Removing Hosts</title>

-<!-- .XS -->

-<!-- (SN Adding, Getting, or Removing Hosts  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to add, get, or remove hosts

-from the access control list.

-All the host access control functions use the 

-<structname>XHostAddress</structname>

-structure, which contains:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XHostAddress</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     int family;        /* for example FamilyInternet */

-     int length;        /* length of address, in bytes */

-     char *address;     /* pointer to where to find the address */

-} XHostAddress;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The family member specifies which protocol address family to use 

-(for example, <acronym>TCP</acronym>/<acronym>IP</acronym> or DECnet) and can be

-<symbol>FamilyInternet</symbol>,

-<symbol>FamilyInternet6</symbol>,

-<symbol>FamilyServerInterpreted</symbol>,

-<symbol>FamilyDECnet</symbol>,

-or

-<symbol>FamilyChaos</symbol>.

-The length member specifies the length of the address in bytes.

-The address member specifies a pointer to the address.

-</para>

-<para>

-<!-- .LP -->

-For <acronym>TCP</acronym>/<acronym>IP</acronym>, the address should be in network byte order.

-For <acronym>IP</acronym> version 4 addresses, the family should be FamilyInternet

-and the length should be 4 bytes.  For <acronym>IP</acronym> version 6 addresses, the

-family should be FamilyInternet6 and the length should be 16 bytes.

-</para>

-<para>

-<!-- .LP -->

-For the DECnet family, 

-the server performs no automatic swapping on the address bytes.

-A Phase IV address is 2 bytes long.

-The first byte contains the least significant 8 bits of the node number.

-The second byte contains the most significant 2 bits of the

-node number in the least significant 2 bits of the byte

-and the area in the most significant 6 bits of the byte.

-</para>

-<para>

-<!-- .LP -->

-For the ServerInterpreted family, the length is ignored and the address 

-member is a pointer to a 

-<structname>XServerInterpretedAddress</structname>

-structure, which contains:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XServerInterpretedAddress</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     int typelength;     /* length of type string, in bytes */

-     int valuelength;    /* length of value string, in bytes */

-     char *type;         /* pointer to where to find the type string */

-     char *value;        /* pointer to where to find the address */

-} XServerInterpretedAddress;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The type and value members point to strings representing the type and value of

-the server interpreted entry.  These strings may not be NULL-terminated so care

-should be used when accessing them.  The typelength and valuelength members

-specify the length in byte of the type and value strings.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To add a single host, use

-<function>XAddHost</function>.

-<indexterm significance="preferred"><primary>XAddHost</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAddHost</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XHostAddress<parameter> *host</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Ho added -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>host</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the host that is to be (Ho.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAddHost</function>

-function adds the specified host to the access control list for that display.

-The server must be on the same host as the client issuing the command, or a

-<errorname>BadAccess</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XAddHost</function>

-can generate

-<errorname>BadAccess</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To add multiple hosts at one time, use

-<function>XAddHosts</function>.

-<indexterm significance="preferred"><primary>XAddHosts</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAddHosts</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>

-  <paramdef>int<parameter> num_hosts</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Ho added -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hosts</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies each host that is to be (Ho.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_hosts</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of hosts.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAddHosts</function>

-function adds each specified host to the access control list for that display.

-The server must be on the same host as the client issuing the command, or a

-<errorname>BadAccess</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XAddHosts</function>

-can generate

-<errorname>BadAccess</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a host list, use

-<function>XListHosts</function>.

-<indexterm significance="preferred"><primary>XListHosts</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XHostAddress *<function>XListHosts</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> *nhosts_return</parameter></paramdef>

-  <paramdef>Bool<parameter> *state_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nhosts_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of hosts currently in the access control list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>state_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the state of the access control.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XListHosts</function>

-function returns the current access control list as well as whether the use 

-of the list at connection setup was enabled or disabled.

-<function>XListHosts</function>

-allows a program to find out what machines can make connections.

-It also returns a pointer to a list of host structures that

-were allocated by the function. 

-When no longer needed,

-this memory should be freed by calling

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove a single host, use

-<function>XRemoveHost</function>.

-<indexterm significance="preferred"><primary>XRemoveHost</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRemoveHost</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XHostAddress<parameter> *host</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Ho removed -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>host</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the host that is to be (Ho.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRemoveHost</function>

-function removes the specified host from the access control list 

-for that display.

-The server must be on the same host as the client process, or a

-<errorname>BadAccess</errorname>

-error results.

-If you remove your machine from the access list,

-you can no longer connect to that server,

-and this operation cannot be reversed unless you reset the server.

-</para>

-<para>

-<!-- .LP -->

-<function>XRemoveHost</function>

-can generate

-<errorname>BadAccess</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove multiple hosts at one time, use

-<function>XRemoveHosts</function>.

-<indexterm significance="preferred"><primary>XRemoveHosts</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRemoveHosts</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>

-  <paramdef>int<parameter> num_hosts</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Ho removed -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hosts</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies each host that is to be (Ho.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_hosts</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of hosts.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRemoveHosts</function>

-function removes each specified host from the access control list for that 

-display.  

-The X server must be on the same host as the client process, or a

-<errorname>BadAccess</errorname>

-error results.

-If you remove your machine from the access list, 

-you can no longer connect to that server,

-and this operation cannot be reversed unless you reset the server.

-</para>

-<para>

-<!-- .LP -->

-<function>XRemoveHosts</function>

-can generate

-<errorname>BadAccess</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Changing_Enabling_or_Disabling_Access_Control">

-<title>Changing, Enabling, or Disabling Access Control</title>

-<!-- .XS -->

-<!-- (SN Changing, Enabling, or Disabling Access Control  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to enable, disable, 

-or change access control.

-</para>

-<para>

-<!-- .LP -->

-For these functions to execute successfully,

-the client application must reside on the same host as the X server

-and/or have been given permission in the initial authorization

-at connection setup.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change access control, use

-<function>XSetAccessControl</function>.

-<indexterm significance="preferred"><primary>XSetAccessControl</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetAccessControl</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the mode.

-You can pass

-<symbol>EnableAccess</symbol>

-or

-<symbol>DisableAccess</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetAccessControl</function>

-function either enables or disables the use of the access control list 

-at each connection setup.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetAccessControl</function>

-can generate

-<errorname>BadAccess</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To enable access control, use

-<function>XEnableAccessControl</function>.

-<indexterm significance="preferred"><primary>XEnableAccessControl</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XEnableAccessControl</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XEnableAccessControl</function>

-function enables the use of the access control list at each connection setup.

-</para>

-<para>

-<!-- .LP -->

-<function>XEnableAccessControl</function>

-can generate a

-<errorname>BadAccess</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To disable access control, use

-<function>XDisableAccessControl</function>.

-<indexterm significance="preferred"><primary>XDisableAccessControl</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDisableAccessControl</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDisableAccessControl</function>

-function disables the use of the access control list at each connection setup.

-</para>

-<para>

-<!-- .LP -->

-<function>XDisableAccessControl</function>

-can generate a

-<errorname>BadAccess</errorname>

-error.

-<!-- .bp -->

-

-</para>

-</sect2>

-</sect1>

-</chapter>

+<?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="window_and_session_manager_functions">
+<title>Window and Session Manager Functions</title>
+
+<para>
+Although it is difficult to categorize functions as exclusively for an application,
+a window manager, or a session manager, the functions in this chapter are most
+often used by window managers and session managers. It is not expected that
+these functions will be used by most application programs. Xlib provides
+management functions to:
+</para>
+
+<itemizedlist>
+  <listitem><para>Change the parent of a window</para></listitem>
+  <listitem><para>Control the lifetime of a window</para></listitem>
+  <listitem><para>Manage installed colormaps</para></listitem>
+  <listitem><para>Set and retrieve the font search path</para></listitem>
+  <listitem><para>Grab the server</para></listitem>
+  <listitem><para>Kill a client</para></listitem>
+  <listitem><para>Control the screen saver</para></listitem>
+  <listitem><para>Control host access</para></listitem>
+</itemizedlist>
+
+<sect1 id="Changing_the_Parent_of_a_Window">
+<title>Changing the Parent of a Window</title>
+<!-- .XS -->
+<!-- (SN Changing the Parent of a Window  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To change a window's parent to another window on the same screen, use
+<function>XReparentWindow</function>.
+There is no way to move a window between screens.
+<indexterm significance="preferred"><primary>XReparentWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xreparentwindow'>
+<funcprototype>
+  <funcdef><function>XReparentWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Window<parameter> parent</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>parent</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the parent window.
+<!-- .ds Xy \ of the position in the new parent window -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the specified window is mapped,
+<function>XReparentWindow</function>
+automatically performs an
+<systemitem>UnmapWindow</systemitem>
+request on it, removes it from its current position in the hierarchy,
+and inserts it as the child of the specified parent.
+The window is placed in the stacking order on top with respect to
+sibling windows.
+</para>
+<para>
+<!-- .LP -->
+After reparenting the specified window,
+<function>XReparentWindow</function>
+causes the X server to generate a
+<symbol>ReparentNotify</symbol>
+event.
+The override_redirect member returned in this event is
+set to the window's corresponding attribute.
+Window manager clients usually should ignore this window if this member
+is set to
+<symbol>True</symbol>.
+Finally, if the specified window was originally mapped,
+the X server automatically performs a
+<systemitem>MapWindow</systemitem>
+request on it.
+</para>
+<para>
+<!-- .LP -->
+The X server performs normal exposure processing on formerly obscured
+windows.
+The X server might not generate 
+<symbol>Expose</symbol>
+events for regions from the initial
+<systemitem>UnmapWindow</systemitem>
+request that are immediately obscured by the final
+<systemitem>MapWindow</systemitem>
+request.
+A
+<errorname>BadMatch</errorname>
+error results if:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The new parent window is not on the same screen as
+the old parent window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The new parent window is the specified window or an inferior of the
+specified window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The new parent is
+<symbol>InputOnly</symbol>,
+and the window is not.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The specified window has a
+<symbol>ParentRelative</symbol>
+background, and the new parent window is not the same depth as the
+specified window.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XReparentWindow</function>
+can generate
+<errorname>BadMatch</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Controlling_the_Lifetime_of_a_Window">
+<title>Controlling the Lifetime of a Window</title>
+<!-- .XS -->
+<!-- (SN Controlling the Lifetime of a Window  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The save-set of a client is a list of other clients' windows that,
+if they are inferiors of one of the client's windows at connection close,
+should not be destroyed and should be remapped if they are unmapped.
+For further information about close-connection processing,
+see section 2.6.
+To allow an application's window to survive when a window manager that
+has reparented a window fails,
+Xlib provides the save-set functions that you can 
+use to control the longevity of subwindows
+that are normally destroyed when the parent is destroyed.
+For example, a window manager that wants to add decoration
+to a window by adding a frame might reparent an application's
+window. 
+When the frame is destroyed,
+the application's window should not be destroyed 
+but be returned to its previous place in the window hierarchy.
+</para>
+<para>
+<!-- .LP -->
+The X server automatically removes windows from the save-set
+when they are destroyed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add or remove a window from the client's save-set, use
+<function>XChangeSaveSet</function>.
+<indexterm significance="preferred"><primary>XChangeSaveSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchangesaveset'>
+<funcprototype>
+  <funcdef><function>XChangeSaveSet</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> change_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi that you want to add to or delete from the client's save-set -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>change_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the mode.
+You can pass
+<symbol>SetModeInsert</symbol>
+or
+<symbol>SetModeDelete</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Depending on the specified mode,
+<function>XChangeSaveSet</function>
+either inserts or deletes the specified window from the client's save-set. 
+The specified window must have been created by some other client,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeSaveSet</function>
+can generate
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a window to the client's save-set, use
+<function>XAddToSaveSet</function>.
+<indexterm significance="preferred"><primary>XAddToSaveSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xaddtosaveset'>
+<funcprototype>
+  <funcdef><function>XAddToSaveSet</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi that you want to add to the client's save-set -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddToSaveSet</function>
+function adds the specified window to the client's save-set.
+The specified window must have been created by some other client,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XAddToSaveSet</function>
+can generate
+<errorname>BadMatch</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove a window from the client's save-set, use
+<function>XRemoveFromSaveSet</function>.
+<indexterm significance="preferred"><primary>XRemoveFromSaveSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xremovefromsaveset'>
+<funcprototype>
+  <funcdef><function>XRemoveFromSaveSet</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi that you want to delete from the client's save-set -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveFromSaveSet</function>
+function removes the specified window from the client's save-set.
+The specified window must have been created by some other client,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XRemoveFromSaveSet</function>
+can generate
+<errorname>BadMatch</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Managing_Installed_Colormaps">
+<title>Managing Installed Colormaps</title>
+<!-- .XS -->
+<!-- (SN Managing Installed Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The X server maintains a list of installed colormaps.
+Windows using these colormaps are guaranteed to display with
+correct colors; windows using other colormaps may or may not display
+with correct colors.
+Xlib provides functions that you can use to install a colormap, 
+uninstall a colormap, and obtain a list of installed colormaps.
+</para>
+<para>
+<!-- .LP -->
+At any time,
+there is a subset of the installed maps that is viewed as an ordered list
+and is called the required list.
+The length of the required list is at most M,
+where M is the minimum number of installed colormaps specified for the screen
+in the connection setup.
+The required list is maintained as follows.
+When a colormap is specified to
+<function>XInstallColormap</function>,
+it is added to the head of the list;
+the list is truncated at the tail, if necessary, to keep its length to 
+at most M.
+When a colormap is specified to
+<function>XUninstallColormap</function>
+and it is in the required list,
+it is removed from the list.
+A colormap is not added to the required list when it is implicitly installed
+by the X server,
+and the X server cannot implicitly uninstall a colormap that is in the
+required list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To install a colormap, use
+<function>XInstallColormap</function>.
+<indexterm significance="preferred"><primary>XInstallColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xinstallcolormap'>
+<funcprototype>
+  <funcdef><function>XInstallColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInstallColormap</function>
+function installs the specified colormap for its associated screen.
+All windows associated with this colormap immediately display with
+true colors.
+You associated the windows with this colormap when you created them by calling
+<function>XCreateWindow</function>,
+<function>XCreateSimpleWindow</function>,
+<function>XChangeWindowAttributes</function>,
+or
+<function>XSetWindowColormap</function>.
+</para>
+<para>
+<!-- .LP -->
+If the specified colormap is not already an installed colormap, 
+the X server generates a
+<symbol>ColormapNotify</symbol>
+event on each window that has that colormap.
+In addition, for every other colormap that is installed as 
+a result of a call to
+<function>XInstallColormap</function>,
+the X server generates a
+<symbol>ColormapNotify</symbol>
+event on each window that has that colormap.
+</para>
+<para>
+<!-- .LP -->
+<function>XInstallColormap</function>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To uninstall a colormap, use
+<function>XUninstallColormap</function>.
+<indexterm significance="preferred"><primary>XUninstallColormap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xuninstallcolormap'>
+<funcprototype>
+  <funcdef><function>XUninstallColormap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Colormap<parameter> colormap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the colormap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUninstallColormap</function>
+function removes the specified colormap from the required
+list for its screen.
+As a result,
+the specified colormap might be uninstalled, 
+and the X server might implicitly install or uninstall additional colormaps.
+Which colormaps get installed or uninstalled is server dependent
+except that the required list must remain installed.
+</para>
+<para>
+<!-- .LP -->
+If the specified colormap becomes uninstalled, 
+the X server generates a
+<symbol>ColormapNotify</symbol>
+event on each window that has that colormap.
+In addition, for every other colormap that is installed or uninstalled as a 
+result of a call to 
+<function>XUninstallColormap</function>,
+the X server generates a
+<symbol>ColormapNotify</symbol>
+event on each window that has that colormap.
+</para>
+<para>
+<!-- .LP -->
+<function>XUninstallColormap</function>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a list of the currently installed colormaps for a given screen, use
+<function>XListInstalledColormaps</function>.
+<indexterm significance="preferred"><primary>XListInstalledColormaps</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlistinstalledcolormaps'>
+<funcprototype>
+  <funcdef>Colormap *<function>XListInstalledColormaps</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> *num_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi that determines the screen -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of currently installed colormaps.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListInstalledColormaps</function>
+function returns a list of the currently installed colormaps for the screen 
+of the specified window.
+The order of the colormaps in the list is not significant
+and is no explicit indication of the required list.
+When the allocated list is no longer needed,
+free it by using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XListInstalledColormaps</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Setting_and_Retrieving_the_Font_Search_Path">
+<title>Setting and Retrieving the Font Search Path</title>
+<!-- .XS -->
+<!-- (SN Setting and Retrieving the Font Search Path  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The set of fonts available from a server depends on a font
+search path.  Xlib provides functions to set and retrieve the
+search path for a server.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the font search path, use
+<function>XSetFontPath</function>.
+<indexterm significance="preferred"><primary>XSetFontPath</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetfontpath'>
+<funcprototype>
+  <funcdef><function>XSetFontPath</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> **directories</parameter></paramdef>
+  <paramdef>int<parameter> ndirs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>directories</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the directory path used to look for a font.
+Setting the path to the empty list restores the default path defined
+for the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ndirs</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of directories in the path.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetFontPath</function>
+function defines the directory search path for font lookup.
+There is only one search path per X server, not one per client.
+The encoding and interpretation of the strings are implementation-dependent,
+but typically they specify directories or font servers to be searched 
+in the order listed.
+An X server is permitted to cache font information internally;
+for example, it might cache an entire font from a file and not
+check on subsequent opens of that font to see if the underlying
+font file has changed.
+However,
+when the font path is changed,
+the X server is guaranteed to flush all cached information about fonts 
+for which there currently are no explicit resource IDs allocated.
+The meaning of an error from this request is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetFontPath</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the current font search path, use
+<function>XGetFontPath</function>.
+<indexterm significance="preferred"><primary>XGetFontPath</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetfontpath'>
+<funcprototype>
+  <funcdef>char **<function>XGetFontPath</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> *npaths_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>npaths_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of strings in the font path array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetFontPath</function>
+function allocates and returns an array of strings containing the search path.
+The contents of these strings are implementation-dependent
+and are not intended to be interpreted by client applications.
+When it is no longer needed,
+the data in the font path should be freed by using
+<function>XFreeFontPath</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free data returned by
+<function>XGetFontPath</function>,
+use
+<function>XFreeFontPath</function>.
+<indexterm significance="preferred"><primary>XFreeFontPath</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreefontpath'>
+<funcprototype>
+  <funcdef><function>XFreeFontPath</function></funcdef>
+  <paramdef>char<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the array of strings you want to free.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFontPath</function>
+function
+frees the data allocated by
+<function>XGetFontPath</function>.
+</para>
+</sect1>
+<sect1 id="Grabbing_the_Server_">
+<title>Grabbing the Server </title>
+<!-- .XS -->
+<!-- (SN Grabbing the Server  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to grab and ungrab the server.
+These functions can be used to control processing of output on other
+connections by the window system server.
+While the server is grabbed,
+no processing of requests or close downs on any other connection will occur.
+A client closing its connection automatically ungrabs the server.
+<indexterm><primary>Menus</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>managers</secondary></indexterm>
+Although grabbing the server is highly discouraged, it is sometimes necessary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab the server, use
+<function>XGrabServer</function>.
+<indexterm><primary>Server</primary><secondary>grabbing</secondary></indexterm>
+<indexterm><primary>Grabbing</primary><secondary>server</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabServer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgrabserver'>
+<funcprototype>
+  <funcdef><function>XGrabServer</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabServer</function>
+function disables processing of requests and close downs on all other 
+connections than the one this request arrived on.
+You should not grab the X server any more than is absolutely necessary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the server, use
+<function>XUngrabServer</function>.
+<indexterm significance="preferred"><primary>XUngrabServer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xungrabserver'>
+<funcprototype>
+  <funcdef><function>XUngrabServer</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabServer</function>
+function restarts processing of requests and close downs on other connections.
+You should avoid grabbing the X server as much as possible.
+</para>
+</sect1>
+<sect1 id="Killing_Clients">
+<title>Killing Clients</title>
+<!-- .XS -->
+<!-- (SN Killing Clients  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides a function to cause the connection to
+a client to be closed and its resources to be destroyed.
+To destroy a client, use
+<function>XKillClient</function>.
+<indexterm significance="preferred"><primary>XKillClient</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xkillclient'>
+<funcprototype>
+  <funcdef><function>XKillClient</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XID<parameter> resource</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>resource</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies any resource associated with the client that you want to destroy or
+<symbol>AllTemporary</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XKillClient</function>
+function
+forces a close down of the client
+that created the resource
+if a valid resource is specified.
+If the client has already terminated in
+either 
+<symbol>RetainPermanent</symbol>
+or 
+<symbol>RetainTemporary</symbol>
+mode, all of the client's
+resources are destroyed.
+If 
+<symbol>AllTemporary</symbol>
+is specified, the resources of all clients that have terminated in
+<symbol>RetainTemporary</symbol>
+are destroyed (see section 2.5).
+This permits implementation of window manager facilities that aid debugging.
+A client can set its close-down mode to
+<symbol>RetainTemporary</symbol>.
+If the client then crashes,
+its windows would not be destroyed. 
+The programmer can then inspect the application's window tree 
+and use the window manager to destroy the zombie windows.
+</para>
+<para>
+<!-- .LP -->
+<function>XKillClient</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Controlling_the_Screen_Saver_">
+<title>Controlling the Screen Saver </title>
+<!-- .XS -->
+<!-- (SN Controlling the Screen Saver  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set or reset the mode 
+of the screen saver, to force or activate the screen saver,
+or to obtain the current screen saver values.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the screen saver mode, use
+<function>XSetScreenSaver</function>.
+<indexterm significance="preferred"><primary>XSetScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetscreensaver'>
+<funcprototype>
+  <funcdef><function>XSetScreenSaver</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>inttimeout,<parameter> interval</parameter></paramdef>
+  <paramdef>int<parameter> prefer_blanking</parameter></paramdef>
+  <paramdef>int<parameter> allow_exposures</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>timeout</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the timeout, in seconds, until the screen saver turns on.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>interval</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the interval, in seconds, between screen saver alterations.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>prefer_blanking</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies how to enable screen blanking.
+You can pass
+<symbol>DontPreferBlanking</symbol>,
+<symbol>PreferBlanking</symbol>,
+or
+<symbol>DefaultBlanking</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>allow_exposures</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the screen save control values.
+You can pass
+<symbol>DontAllowExposures</symbol>,
+<symbol>AllowExposures</symbol>,
+or
+<symbol>DefaultExposures</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Timeout and interval are specified in seconds. 
+A timeout of 0 disables the screen saver 
+(but an activated screen saver is not deactivated),
+and a timeout of &minus;1 restores the default.
+Other negative values generate a
+<errorname>BadValue</errorname>
+error.
+If the timeout value is nonzero, 
+<function>XSetScreenSaver</function>
+enables the screen saver.
+An interval of 0 disables the random-pattern motion.
+If no input from devices (keyboard, mouse, and so on) is generated 
+for the specified number of timeout seconds once the screen saver is enabled,
+the screen saver is activated.
+</para>
+<para>
+<!-- .LP -->
+For each screen, 
+if blanking is preferred and the hardware supports video blanking, 
+the screen simply goes blank.  
+Otherwise, if either exposures are allowed or the screen can be regenerated 
+without sending 
+<symbol>Expose</symbol>
+events to clients, 
+the screen is tiled with the root window background tile randomly 
+re-origined each interval seconds.
+Otherwise, the screens' state do not change, 
+and the screen saver is not activated.
+The screen saver is deactivated,
+and all screen states are restored at the next
+keyboard or pointer input or at the next call to
+<function>XForceScreenSaver</function>
+with mode
+<symbol>ScreenSaverReset</symbol>.
+</para>
+<para>
+<!-- .LP -->
+If the server-dependent screen saver method supports periodic change,
+the interval argument serves as a hint about how long the change period
+should be, and zero hints that no periodic change should be made.
+Examples of ways to change the screen include scrambling the colormap
+periodically, moving an icon image around the screen periodically, or tiling
+the screen with the root window background tile, randomly re-origined
+periodically.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetScreenSaver</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To force the screen saver on or off, use
+<function>XForceScreenSaver</function>.
+<indexterm significance="preferred"><primary>XForceScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xforcescreensaver'>
+<funcprototype>
+  <funcdef><function>XForceScreenSaver</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the mode that is to be applied.
+You can pass
+<symbol>ScreenSaverActive</symbol>
+or
+<symbol>ScreenSaverReset</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the specified mode is 
+<symbol>ScreenSaverActive</symbol>
+and the screen saver currently is deactivated,
+<function>XForceScreenSaver</function>
+activates the screen saver even if the screen saver had been disabled
+with a timeout of zero.
+If the specified mode is 
+<symbol>ScreenSaverReset</symbol>
+and the screen saver currently is enabled,
+<function>XForceScreenSaver</function>
+deactivates the screen saver if it was activated,
+and the activation timer is reset to its initial state 
+(as if device input had been received).
+</para>
+<para>
+<!-- .LP -->
+<function>XForceScreenSaver</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To activate the screen saver, use
+<function>XActivateScreenSaver</function>.
+<indexterm significance="preferred"><primary>XActivateScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xactivatescreensaver'>
+<funcprototype>
+  <funcdef><function>XActivateScreenSaver</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To reset the screen saver, use
+<function>XResetScreenSaver</function>.
+<indexterm significance="preferred"><primary>XResetScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xresetscreensaver'>
+<funcprototype>
+  <funcdef><function>XResetScreenSaver</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To get the current screen saver values, use
+<function>XGetScreenSaver</function>.
+<indexterm significance="preferred"><primary>XGetScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetscreensaver'>
+<funcprototype>
+  <funcdef><function>XGetScreenSaver</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int*timeout_return,<parameter> *interval_return</parameter></paramdef>
+  <paramdef>int<parameter> *prefer_blanking_return</parameter></paramdef>
+  <paramdef>int<parameter> *allow_exposures_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>timeout_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the timeout, in seconds, until the screen saver turns on.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>interval_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the interval between screen saver invocations.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>prefer_blanking_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the current screen blanking preference
+(<symbol>DontPreferBlanking</symbol>,
+<symbol>PreferBlanking</symbol>,
+or
+<symbol>DefaultBlanking</symbol>).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>allow_exposures_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the current screen save control value
+(<symbol>DontAllowExposures</symbol>,
+<symbol>AllowExposures</symbol>,
+or
+<symbol>DefaultExposures</symbol>).
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect1>
+<sect1 id="Controlling_Host_Access">
+<title>Controlling Host Access</title>
+<!-- .XS -->
+<!-- (SN Controlling Host Access  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Add, get, or remove hosts from the access control list
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Change, enable, or disable access
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<indexterm><primary>Access control list</primary></indexterm>
+<indexterm><primary>Authentication</primary></indexterm>
+X does not provide any protection on a per-window basis.
+If you find out the resource ID of a resource, you can manipulate it.
+To provide some minimal level of protection, however,
+connections are permitted only from machines you trust.
+This is adequate on single-user workstations but obviously
+breaks down on timesharing machines.
+Although provisions exist in the X protocol for proper connection
+authentication, the lack of a standard authentication server
+leaves host-level access control as the only common mechanism.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Default Protection</primary></indexterm>
+The initial set of hosts allowed to open connections typically consists of:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The host the window system is running on.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+On <acronym>POSIX</acronym>-conformant systems, each host listed in the
+<filename>/etc/X<replaceable>?</replaceable>.hosts</filename>
+file.
+The ? indicates the number of the
+display.
+<indexterm><primary>Files</primary><secondary><filename>/etc/X<replaceable>?</replaceable>.hosts</filename></secondary></indexterm>
+This file should consist of host names separated by newlines.
+DECnet nodes must terminate in :: to distinguish them from Internet hosts.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If a host is not in the access control list when the access control 
+mechanism is enabled and if the host attempts to establish a connection,
+the server refuses the connection.
+To change the access list,
+the client must reside on the same host as the server and/or must
+have been granted permission in the initial authorization at connection
+setup.
+</para>
+<para>
+<!-- .LP -->
+Servers also can implement other access control policies in addition to
+or in place of this host access facility.
+For further information about other access control implementations,
+see ``X Window System Protocol.''
+</para>
+<sect2 id="Adding_Getting_or_Removing_Hosts">
+<title>Adding, Getting, or Removing Hosts</title>
+<!-- .XS -->
+<!-- (SN Adding, Getting, or Removing Hosts  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to add, get, or remove hosts
+from the access control list.
+All the host access control functions use the 
+<structname>XHostAddress</structname>
+structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XHostAddress</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     int family;        /* for example FamilyInternet */
+     int length;        /* length of address, in bytes */
+     char *address;     /* pointer to where to find the address */
+} XHostAddress;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The family member specifies which protocol address family to use 
+(for example, <acronym>TCP</acronym>/<acronym>IP</acronym> or DECnet) and can be
+<symbol>FamilyInternet</symbol>,
+<symbol>FamilyInternet6</symbol>,
+<symbol>FamilyServerInterpreted</symbol>,
+<symbol>FamilyDECnet</symbol>,
+or
+<symbol>FamilyChaos</symbol>.
+The length member specifies the length of the address in bytes.
+The address member specifies a pointer to the address.
+</para>
+<para>
+<!-- .LP -->
+For <acronym>TCP</acronym>/<acronym>IP</acronym>, the address should be in network byte order.
+For <acronym>IP</acronym> version 4 addresses, the family should be FamilyInternet
+and the length should be 4 bytes.  For <acronym>IP</acronym> version 6 addresses, the
+family should be FamilyInternet6 and the length should be 16 bytes.
+</para>
+<para>
+<!-- .LP -->
+For the DECnet family, 
+the server performs no automatic swapping on the address bytes.
+A Phase IV address is 2 bytes long.
+The first byte contains the least significant 8 bits of the node number.
+The second byte contains the most significant 2 bits of the
+node number in the least significant 2 bits of the byte
+and the area in the most significant 6 bits of the byte.
+</para>
+<para>
+<!-- .LP -->
+For the ServerInterpreted family, the length is ignored and the address 
+member is a pointer to a 
+<structname>XServerInterpretedAddress</structname>
+structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XServerInterpretedAddress</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     int typelength;     /* length of type string, in bytes */
+     int valuelength;    /* length of value string, in bytes */
+     char *type;         /* pointer to where to find the type string */
+     char *value;        /* pointer to where to find the address */
+} XServerInterpretedAddress;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The type and value members point to strings representing the type and value of
+the server interpreted entry.  These strings may not be NULL-terminated so care
+should be used when accessing them.  The typelength and valuelength members
+specify the length in byte of the type and value strings.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a single host, use
+<function>XAddHost</function>.
+<indexterm significance="preferred"><primary>XAddHost</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xaddhost'>
+<funcprototype>
+  <funcdef><function>XAddHost</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XHostAddress<parameter> *host</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Ho added -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>host</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the host that is to be (Ho.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddHost</function>
+function adds the specified host to the access control list for that display.
+The server must be on the same host as the client issuing the command, or a
+<errorname>BadAccess</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XAddHost</function>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add multiple hosts at one time, use
+<function>XAddHosts</function>.
+<indexterm significance="preferred"><primary>XAddHosts</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xaddhosts'>
+<funcprototype>
+  <funcdef><function>XAddHosts</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>
+  <paramdef>int<parameter> num_hosts</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Ho added -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hosts</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies each host that is to be (Ho.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_hosts</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of hosts.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddHosts</function>
+function adds each specified host to the access control list for that display.
+The server must be on the same host as the client issuing the command, or a
+<errorname>BadAccess</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XAddHosts</function>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a host list, use
+<function>XListHosts</function>.
+<indexterm significance="preferred"><primary>XListHosts</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlisthosts'>
+<funcprototype>
+  <funcdef>XHostAddress *<function>XListHosts</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> *nhosts_return</parameter></paramdef>
+  <paramdef>Bool<parameter> *state_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nhosts_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of hosts currently in the access control list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>state_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the state of the access control.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListHosts</function>
+function returns the current access control list as well as whether the use 
+of the list at connection setup was enabled or disabled.
+<function>XListHosts</function>
+allows a program to find out what machines can make connections.
+It also returns a pointer to a list of host structures that
+were allocated by the function. 
+When no longer needed,
+this memory should be freed by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove a single host, use
+<function>XRemoveHost</function>.
+<indexterm significance="preferred"><primary>XRemoveHost</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xremovehost'>
+<funcprototype>
+  <funcdef><function>XRemoveHost</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XHostAddress<parameter> *host</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Ho removed -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>host</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the host that is to be (Ho.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveHost</function>
+function removes the specified host from the access control list 
+for that display.
+The server must be on the same host as the client process, or a
+<errorname>BadAccess</errorname>
+error results.
+If you remove your machine from the access list,
+you can no longer connect to that server,
+and this operation cannot be reversed unless you reset the server.
+</para>
+<para>
+<!-- .LP -->
+<function>XRemoveHost</function>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove multiple hosts at one time, use
+<function>XRemoveHosts</function>.
+<indexterm significance="preferred"><primary>XRemoveHosts</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xremovehosts'>
+<funcprototype>
+  <funcdef><function>XRemoveHosts</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>
+  <paramdef>int<parameter> num_hosts</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Ho removed -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hosts</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies each host that is to be (Ho.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_hosts</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of hosts.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveHosts</function>
+function removes each specified host from the access control list for that 
+display.  
+The X server must be on the same host as the client process, or a
+<errorname>BadAccess</errorname>
+error results.
+If you remove your machine from the access list, 
+you can no longer connect to that server,
+and this operation cannot be reversed unless you reset the server.
+</para>
+<para>
+<!-- .LP -->
+<function>XRemoveHosts</function>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Changing_Enabling_or_Disabling_Access_Control">
+<title>Changing, Enabling, or Disabling Access Control</title>
+<!-- .XS -->
+<!-- (SN Changing, Enabling, or Disabling Access Control  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to enable, disable, 
+or change access control.
+</para>
+<para>
+<!-- .LP -->
+For these functions to execute successfully,
+the client application must reside on the same host as the X server
+and/or have been given permission in the initial authorization
+at connection setup.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change access control, use
+<function>XSetAccessControl</function>.
+<indexterm significance="preferred"><primary>XSetAccessControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetaccesscontrol'>
+<funcprototype>
+  <funcdef><function>XSetAccessControl</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the mode.
+You can pass
+<symbol>EnableAccess</symbol>
+or
+<symbol>DisableAccess</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetAccessControl</function>
+function either enables or disables the use of the access control list 
+at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetAccessControl</function>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To enable access control, use
+<function>XEnableAccessControl</function>.
+<indexterm significance="preferred"><primary>XEnableAccessControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xenableaccesscontrol'>
+<funcprototype>
+  <funcdef><function>XEnableAccessControl</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XEnableAccessControl</function>
+function enables the use of the access control list at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<function>XEnableAccessControl</function>
+can generate a
+<errorname>BadAccess</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To disable access control, use
+<function>XDisableAccessControl</function>.
+<indexterm significance="preferred"><primary>XDisableAccessControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisableaccesscontrol'>
+<funcprototype>
+  <funcdef><function>XDisableAccessControl</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisableAccessControl</function>
+function disables the use of the access control list at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<function>XDisableAccessControl</function>
+can generate a
+<errorname>BadAccess</errorname>
+error.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH11.xml b/libX11/specs/libX11/CH11.xml
index c8031649a..df8a9630a 100644
--- a/libX11/specs/libX11/CH11.xml
+++ b/libX11/specs/libX11/CH11.xml
@@ -1,2542 +1,2542 @@
-<?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="event_handling_functions">

-<title>Event Handling Functions</title>

-

-<para>

-This chapter discusses the Xlib functions you can use to:

-</para>

-<itemizedlist>

-  <listitem><para>Select events</para></listitem>

-  <listitem><para>Handle the output buffer and the event queue</para></listitem>

-  <listitem><para>Select events from the event queue</para></listitem>

-  <listitem><para>Send and get events</para></listitem>

-  <listitem><para>Handle protocol errors</para></listitem>

-</itemizedlist>

-<note><para>

-Some toolkits use their own event-handling functions and do not allow you to

-interchange these event-handling functions with those in Xlib. For further

-information, see the documentation supplied with the toolkit.

-</para></note>

-

-<para>

-Most applications simply are event loops: they wait for an event, decide what to do with it,

-execute some amount of code that results in changes to the display, and then wait for the next

-event.

-</para>

-

-<sect1 id="Selecting_Events">

-<title>Selecting Events</title>

-<!-- .XS -->

-<!-- (SN Selecting Events  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-There are two ways to select the events you want reported to your client

-application.

-One way is to set the event_mask member of the

-<structname>XSetWindowAttributes</structname>

-structure when you call

-<function>XCreateWindow</function>

-and

-<function>XChangeWindowAttributes</function>.

-Another way is to use

-<function>XSelectInput</function>.

-<indexterm significance="preferred"><primary>XSelectInput</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSelectInput</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN	 -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose events you are interested in -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XSelectInput</function>

-function requests that the X server report the events associated with the 

-specified event mask.

-Initially, X will not report any of these events.

-Events are reported relative to a window.

-If a window is not interested in a device event, it usually propagates to

-the closest ancestor that is interested,

-unless the do_not_propagate mask prohibits it.

-<indexterm><primary>Event</primary><secondary>propagation</secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-Setting the event-mask attribute of a window overrides any previous call

-for the same window but not for other clients.

-Multiple clients can select for the same events on the same window

-with the following restrictions:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Multiple clients can select events on the same window because their event masks

-are disjoint.

-When the X server generates an event, it reports it

-to all interested clients.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Only one client at a time can select

-<symbol>CirculateRequest</symbol>,

-<symbol>ConfigureRequest</symbol>,

-or

-<symbol>MapRequest</symbol>

-events, which are associated with

-the event mask

-<symbol>SubstructureRedirectMask</symbol>.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Only one client at a time can select

-a

-<symbol>ResizeRequest</symbol>

-event, which is associated with

-the event mask

-<symbol>ResizeRedirectMask</symbol>.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Only one client at a time can select a 

-<symbol>ButtonPress</symbol>

-event, which is associated with

-the event mask

-<symbol>ButtonPressMask</symbol>.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The server reports the event to all interested clients.

-</para>

-<para>

-<!-- .LP -->

-<function>XSelectInput</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Handling_the_Output_Buffer">

-<title>Handling the Output Buffer</title>

-<!-- .XS -->

-<!-- (SN Handling the Output Buffer -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The output buffer is an area used by Xlib to store requests.

-The functions described in this section flush the output buffer

-if the function would block or not return an event.

-That is, all requests residing in the output buffer that

-have not yet been sent are transmitted to the X server.

-These functions differ in the additional tasks they might perform.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To flush the output buffer, use 

-<function>XFlush</function>.

-<indexterm significance="preferred"><primary>XFlush</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFlush</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFlush</function>

-function

-flushes the output buffer.

-Most client applications need not use this function because the output

-buffer is automatically flushed as needed by calls to

-<function>XPending</function>,

-<function>XNextEvent</function>,

-and

-<function>XWindowEvent</function>.

-<indexterm><primary>XPending</primary></indexterm>

-<indexterm><primary>XNextEvent</primary></indexterm>

-<indexterm><primary>XWindowEvent</primary></indexterm>

-Events generated by the server may be enqueued into the library's event queue.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To flush the output buffer and then wait until all requests have been processed,

-use 

-<function>XSync</function>.

-<indexterm significance="preferred"><primary>XSync</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSync</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Bool<parameter> discard</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>discard</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether 

-<function>XSync</function>

-discards all events on the event queue.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSync</function>

-function

-flushes the output buffer and then waits until all requests have been received

-and processed by the X server.

-Any errors generated must be handled by the error handler.

-For each protocol error received by Xlib,

-<function>XSync</function>

-calls the client application's error handling routine (see section 11.8.2).

-Any events generated by the server are enqueued into the library's 

-event queue.

-</para>

-<para>

-<!-- .LP -->

-Finally, if you passed 

-<symbol>False</symbol>,

-<function>XSync</function>

-does not discard the events in the queue.

-If you passed 

-<symbol>True</symbol>,

-<function>XSync</function>

-discards all events in the queue,

-including those events that were on the queue before

-<function>XSync</function>

-was called.

-Client applications seldom need to call

-<function>XSync</function>.

-</para>

-</sect1>

-<sect1 id="Event_Queue_Management">

-<title>Event Queue Management</title>

-<!-- .XS -->

-<!-- (SN Event Queue Management -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib maintains an event queue.

-However, the operating system also may be buffering data 

-in its network connection that is not yet read into the event queue.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To check the number of events in the event queue, use

-<function>XEventsQueued</function>.

-<indexterm significance="preferred"><primary>XEventsQueued</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XEventsQueued</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the mode.

-You can pass

-<symbol>QueuedAlready</symbol>,

-<symbol>QueuedAfterFlush</symbol>,

-or

-<symbol>QueuedAfterReading</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If mode is 

-<symbol>QueuedAlready</symbol>,

-<function>XEventsQueued</function>

-returns the number of events

-already in the event queue (and never performs a system call).

-If mode is 

-<symbol>QueuedAfterFlush</symbol>,

-<function>XEventsQueued</function>

-returns the number of events already in the queue if the number is nonzero.

-If there are no events in the queue, 

-<function>XEventsQueued</function>

-flushes the output buffer, 

-attempts to read more events out of the application's connection,

-and returns the number read.

-If mode is 

-<symbol>QueuedAfterReading</symbol>,

-<function>XEventsQueued</function>

-returns the number of events already in the queue if the number is nonzero. 

-If there are no events in the queue, 

-<function>XEventsQueued</function>

-attempts to read more events out of the application's connection 

-without flushing the output buffer and returns the number read.

-</para>

-<para>

-<!-- .LP -->

-<function>XEventsQueued</function>

-always returns immediately without I/O if there are events already in the

-queue.

-<function>XEventsQueued</function>

-with mode 

-<symbol>QueuedAfterFlush</symbol>

-is identical in behavior to

-<function>XPending</function>.

-<function>XEventsQueued</function>

-with mode

-<symbol>QueuedAlready</symbol>

-is identical to the

-<function>XQLength</function>

-function.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return the number of events that are pending, use 

-<function>XPending</function>.

-<indexterm significance="preferred"><primary>XPending</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XPending</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN	 -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPending</function>

-function returns the number of events that have been received from the

-X server but have not been removed from the event queue.

-<function>XPending</function>

-is identical to

-<function>XEventsQueued</function>

-with the mode

-<symbol>QueuedAfterFlush</symbol>

-specified.

-</para>

-</sect1>

-<sect1 id="Manipulating_the_Event_Queue">

-<title>Manipulating the Event Queue</title>

-<!-- .XS -->

-<!-- (SN Manipulating the Event Queue  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that let you manipulate the event queue.

-This section discusses how to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Obtain events, in order, and remove them from the queue

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Peek at events in the queue without removing them

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Obtain events that match the event mask or the arbitrary

-predicate procedures that you provide

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Returning_the_Next_Event">

-<title>Returning the Next Event</title>

-<!-- .XS -->

-<!-- (SN Returning the Next Event -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To get the next event and remove it from the queue, use

-<function>XNextEvent</function>.

-<indexterm significance="preferred"><primary>XNextEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XNextEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the next event in the queue.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XNextEvent</function>

-function copies the first event from the event queue into the specified

-<structname>XEvent</structname>

-structure and then removes it from the queue.

-If the event queue is empty,

-<function>XNextEvent</function>

-flushes the output buffer and blocks until an event is received.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To peek at the event queue, use

-<function>XPeekEvent</function>.

-<indexterm significance="preferred"><primary>XPeekEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XPeekEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a copy of the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPeekEvent</function>

-function returns the first event from the event queue,

-but it does not remove the event from the queue.

-If the queue is empty,

-<function>XPeekEvent</function>

-flushes the output buffer and blocks until an event is received.

-It then copies the event into the client-supplied

-<structname>XEvent</structname>

-structure without removing it from the event queue.

-</para>

-</sect2>

-<sect2 id="Selecting_Events_Using_a_Predicate_Procedure">

-<title>Selecting Events Using a Predicate Procedure</title>

-<!-- .XS -->

-<!-- (SN Selecting Events Using a Predicate Procedure -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Each of the functions discussed in this section requires you to

-pass a predicate procedure that determines if an event matches 

-what you want.

-Your predicate procedure must decide if the event is useful

-without calling any Xlib functions.

-If the predicate directly or indirectly causes the state of the event queue

-to change, the result is not defined.

-If Xlib has been initialized for threads, the predicate is called with

-the display locked and the result of a call by the predicate to any

-Xlib function that locks the display is not defined unless the caller

-has first called

-<function>XLockDisplay</function>.

-</para>

-<para>

-<!-- .LP -->

-The predicate procedure and its associated arguments are:

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><type>Bool</type></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XEvent</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the argument passed in from the 

-<function>XIfEvent</function>,

-<function>XCheckIfEvent</function>,

-or

-<function>XPeekIfEvent</function>

-function.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The predicate procedure is called once for each

-event in the queue until it finds a match. 

-After finding a match, the predicate procedure must return 

-<symbol>True</symbol>.

-If it did not find a match, it must return

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To check the event queue for a matching event

-and, if found, remove the event from the queue, use

-<function>XIfEvent</function>.

-<indexterm significance="preferred"><primary>XIfEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XIfEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>predicate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure that is to be called to determine

-if the next event in the queue matches what you want.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the user-supplied argument that will be passed to the predicate procedure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XIfEvent</function>

-function completes only when the specified predicate

-procedure returns 

-<symbol>True</symbol>

-for an event, 

-which indicates an event in the queue matches.

-<function>XIfEvent</function>

-flushes the output buffer if it blocks waiting for additional events.

-<function>XIfEvent</function>

-removes the matching event from the queue 

-and copies the structure into the client-supplied

-<structname>XEvent</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To check the event queue for a matching event without blocking, use

-<function>XCheckIfEvent</function>.

-<indexterm significance="preferred"><primary>XCheckIfEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckIfEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a copy of the matched event's associated structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>predicate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure that is to be called to determine

-if the next event in the queue matches what you want.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the user-supplied argument that will be passed to the predicate procedure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-When the predicate procedure finds a match,

-<function>XCheckIfEvent</function>

-copies the matched event into the client-supplied

-<structname>XEvent</structname>

-structure and returns 

-<symbol>True</symbol>.

-(This event is removed from the queue.)

-If the predicate procedure finds no match,

-<function>XCheckIfEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-All earlier events stored in the queue are not discarded.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To check the event queue for a matching event

-without removing the event from the queue, use

-<function>XPeekIfEvent</function>.

-<indexterm significance="preferred"><primary>XPeekIfEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XPeekIfEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a copy of the matched event's associated structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>predicate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure that is to be called to determine

-if the next event in the queue matches what you want.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the user-supplied argument that will be passed to the predicate procedure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPeekIfEvent</function>

-function returns only when the specified predicate

-procedure returns 

-<symbol>True</symbol>

-for an event.

-After the predicate procedure finds a match,

-<function>XPeekIfEvent</function>

-copies the matched event into the client-supplied

-<structname>XEvent</structname>

-structure without removing the event from the queue.

-<function>XPeekIfEvent</function>

-flushes the output buffer if it blocks waiting for additional events.

-</para>

-</sect2>

-<sect2 id="Selecting_Events_Using_a_Window_or_Event_Mask">

-<title>Selecting Events Using a Window or Event Mask</title>

-<!-- .XS -->

-<!-- (SN Selecting Events Using a Window or Event Mask -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The functions discussed in this section let you select events by window 

-or event types, allowing you to process events out of order.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove the next event that matches both a window and an event mask, use

-<function>XWindowEvent</function>.

-<indexterm significance="preferred"><primary>XWindowEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XWindowEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose events you are interested in -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XWindowEvent</function>

-function searches the event queue for an event that matches both the specified

-window and event mask.

-When it finds a match,

-<function>XWindowEvent</function>

-removes that event from the queue and copies it into the specified

-<structname>XEvent</structname>

-structure.

-The other events stored in the queue are not discarded.

-If a matching event is not in the queue,

-<function>XWindowEvent</function>

-flushes the output buffer and blocks until one is received.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove the next event that matches both a window and an event mask (if any),

-use

-<function>XCheckWindowEvent</function>.

-<indexterm><primary>XCheckWindowEvent</primary></indexterm>

-This function is similar to

-<function>XWindowEvent</function>

-except that it never blocks and it returns a 

-<type>Bool</type>

-indicating if the event was returned.

-<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckWindowEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose events you are interested in -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCheckWindowEvent</function>

-function searches the event queue and then the events available 

-on the server connection for the first event that matches the specified window

-and event mask.

-If it finds a match,

-<function>XCheckWindowEvent</function>

-removes that event, copies it into the specified

-<structname>XEvent</structname>

-structure, and returns

-<symbol>True</symbol>.

-The other events stored in the queue are not discarded.

-If the event you requested is not available,

-<function>XCheckWindowEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove the next event that matches an event mask, use

-<function>XMaskEvent</function>.

-<indexterm significance="preferred"><primary>XMaskEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XMaskEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMaskEvent</function>

-function searches the event queue for the events associated with the 

-specified mask.

-When it finds a match,

-<function>XMaskEvent</function>

-removes that event and copies it into the specified

-<structname>XEvent</structname>

-structure.

-The other events stored in the queue are not discarded.

-If the event you requested is not in the queue,

-<function>XMaskEvent</function>

-flushes the output buffer and blocks until one is received.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return and remove the next event that matches an event mask (if any), use

-<function>XCheckMaskEvent</function>.

-This function is similar to 

-<function>XMaskEvent</function>

-except that it never blocks and it returns a 

-<type>Bool</type>

-indicating if the event was returned.

-<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckMaskEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCheckMaskEvent</function>

-function searches the event queue and then any events available on the

-server connection for the first event that matches the specified mask.

-If it finds a match,

-<function>XCheckMaskEvent</function>

-removes that event, copies it into the specified

-<structname>XEvent</structname>

-structure, and returns

-<symbol>True</symbol>.

-The other events stored in the queue are not discarded.

-If the event you requested is not available,

-<function>XCheckMaskEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp  -->

-To return and remove the next event in the queue that matches an event type, use

-<function>XCheckTypedEvent</function>.

-<indexterm significance="preferred"><primary>XCheckTypedEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckTypedEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> event_type</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_type</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event type to be compared.

-

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCheckTypedEvent</function>

-function searches the event queue and then any events available  

-on the server connection for the first event that matches the specified type.

-If it finds a match,

-<function>XCheckTypedEvent</function>

-removes that event, copies it into the specified

-<structname>XEvent</structname>

-structure, and returns

-<symbol>True</symbol>.

-The other events in the queue are not discarded.

-If the event is not available,

-<function>XCheckTypedEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return and remove the next event in the queue that matches an event type 

-and a window, use

-<function>XCheckTypedWindowEvent</function>.

-<indexterm significance="preferred"><primary>XCheckTypedWindowEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckTypedWindowEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> event_type</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_type</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event type to be compared.

-

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCheckTypedWindowEvent</function>

-function searches the event queue and then any events available  

-on the server connection for the first event that matches the specified

-type and window.

-If it finds a match,

-<function>XCheckTypedWindowEvent</function>

-removes the event from the queue, copies it into the specified

-<structname>XEvent</structname>

-structure, and returns

-<symbol>True</symbol>.

-The other events in the queue are not discarded.

-If the event is not available,

-<function>XCheckTypedWindowEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Putting_an_Event_Back_into_the_Queue">

-<title>Putting an Event Back into the Queue</title>

-<!-- .XS -->

-<!-- (SN Putting an Event Back into the Queue  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To push an event back into the event queue, use

-<function>XPutBackEvent</function>.

-<indexterm significance="preferred"><primary>XPutBackEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XPutBackEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XPutBackEvent</function>

-function pushes an event back onto the head of the display's event queue

-by copying the event into the queue.

-This can be useful if you read an event and then decide that you

-would rather deal with it later.

-There is no limit to the number of times in succession that you can call

-<function>XPutBackEvent</function>.

-</para>

-</sect1>

-<sect1 id="Sending_Events_to_Other_Applications">

-<title>Sending Events to Other Applications</title>

-<!-- .XS -->

-<!-- (SN Sending Events to Other Applications -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To send an event to a specified window, use

-<function>XSendEvent</function>.

-<indexterm><primary>XSendEvent</primary></indexterm>

-This function is often used in selection processing.

-For example, the owner of a selection should use

-<function>XSendEvent</function>

-to send a

-<symbol>SelectionNotify</symbol>

-event to a requestor when a selection has been converted 

-and stored as a property.

-<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XSendEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Bool<parameter> propagate</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_send</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window the event is to be sent to, or

-<symbol>PointerWindow</symbol>,

-or

-<symbol>InputFocus</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>propagate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_send</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event that is to be sent.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSendEvent</function>

-function identifies the destination window, 

-determines which clients should receive the specified events, 

-and ignores any active grabs.

-This function requires you to pass an event mask.

-For a discussion of the valid event mask names,

-see section 10.3.

-This function uses the w argument to identify the destination window as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If w is

-<symbol>PointerWindow</symbol>,

-the destination window is the window that contains the pointer.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If w is

-<symbol>InputFocus</symbol>

-and if the focus window contains the pointer, 

-the destination window is the window that contains the pointer; 

-otherwise, the destination window is the focus window.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-To determine which clients should receive the specified events,

-<function>XSendEvent</function>

-uses the propagate argument as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If event_mask is the empty set,

-the event is sent to the client that created the destination window.

-If that client no longer exists,

-no event is sent.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If propagate is 

-<symbol>False</symbol>,

-the event is sent to every client selecting on destination any of the event

-types in the event_mask argument.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If propagate is 

-<symbol>True</symbol>

-and no clients have selected on destination any of

-the event types in event-mask, the destination is replaced with the

-closest ancestor of destination for which some client has selected a

-type in event-mask and for which no intervening window has that type in its

-do-not-propagate-mask. 

-If no such window exists or if the window is

-an ancestor of the focus window and 

-<symbol>InputFocus</symbol>

-was originally specified

-as the destination, the event is not sent to any clients.

-Otherwise, the event is reported to every client selecting on the final

-destination any of the types specified in event_mask.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The event in the

-<structname>XEvent</structname>

-structure must be one of the core events or one of the events

-defined by an extension (or a 

-<errorname>BadValue</errorname>

-error results) so that the X server can correctly byte-swap 

-the contents as necessary.  

-The contents of the event are

-otherwise unaltered and unchecked by the X server except to force send_event to

-<symbol>True</symbol>

-in the forwarded event and to set the serial number in the event correctly;

-therefore these fields

-and the display field are ignored by

-<function>XSendEvent</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XSendEvent</function>

-returns zero if the conversion to wire protocol format failed

-and returns nonzero otherwise.

-</para>

-<para>

-<!-- .LP -->

-<function>XSendEvent</function>

-can generate

-<errorname>BadValue</errorname>

-and 

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Getting_Pointer_Motion_History">

-<title>Getting Pointer Motion History</title>

-<!-- .XS -->

-<!-- (SN Getting Pointer Motion History -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Some X server implementations will maintain a more complete

-history of pointer motion than is reported by event notification.

-The pointer position at each pointer hardware interrupt may be

-stored in a buffer for later retrieval.

-This buffer is called the motion history buffer.

-For example, a few applications, such as paint programs,

-want to have a precise history of where the pointer

-traveled. 

-However, this historical information is highly excessive for most applications.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To determine the approximate maximum number of elements in the motion buffer, 

-use

-<function>XDisplayMotionBufferSize</function>.

-<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>unsigned <type>long</type></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The server may retain the recent history of the pointer motion

-and do so to a finer granularity than is reported by

-<symbol>MotionNotify</symbol>

-events.

-The

-<function>XGetMotionEvents</function>

-function makes this history available.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the motion history for a specified window and time, use

-<function>XGetMotionEvents</function>.

-<indexterm significance="preferred"><primary>XGetMotionEvents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XTimeCoord *<function>XGetMotionEvents</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Timestart,<parameter> stop</parameter></paramdef>

-  <paramdef>int<parameter> *nevents_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>start</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>stop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the time interval in which the events are returned from the motion

-history buffer.

-You can pass a timestamp or

-<symbol>CurrentTime</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nevents_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of events from the motion history buffer.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetMotionEvents</function>

-function returns all events in the motion history buffer that fall between the

-specified start and stop times, inclusive, and that have coordinates

-that lie within the specified window (including its borders) at its present

-placement.

-If the server does not support motion history, 

-if the start time is later than the stop time,

-or if the start time is in the future, 

-no events are returned;

-<function>XGetMotionEvents</function>

-returns NULL.

-If the stop time is in the future, it is equivalent to specifying

-<symbol>CurrentTime</symbol>.

-The return type for this function is a structure defined as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XTimeCoord</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i -->

-<!-- .ta .5i -->

-typedef struct {

-	Time time;

-	short x, y;

-} XTimeCoord;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The time member is set to the time, in milliseconds. 

-The x and y members are set to the coordinates of the pointer and

-are reported relative to the origin

-of the specified window.

-To free the data returned from this call, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetMotionEvents</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Handling_Protocol_Errors">

-<title>Handling Protocol Errors</title>

-<!-- .XS -->

-<!-- (SN Handling Protocol Errors -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to enable or disable synchronization

-and to use the default error handlers.

-</para>

-<sect2 id="Enabling_or_Disabling_Synchronization">

-<title>Enabling or Disabling Synchronization</title>

-<!-- .XS -->

-<!-- (SN Enabling or Disabling Synchronization  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-When debugging X applications, 

-it often is very convenient to require Xlib to behave synchronously

-so that errors are reported as they occur.

-The following function lets you disable or enable synchronous behavior.

-Note that graphics may occur 30 or more times more slowly when 

-synchronization is enabled.

-<indexterm><primary>_Xdebug</primary></indexterm>

-On <acronym>POSIX</acronym>-conformant systems,

-there is also a global variable 

-<varname>_Xdebug</varname>

-that, if set to nonzero before starting a program under a debugger, will force

-synchronous library behavior.

-</para>

-<para>

-<!-- .LP -->

-After completing their work,

-all Xlib functions that generate protocol requests call what is known as

-an after function.

-<function>XSetAfterFunction</function>

-sets which function is to be called.

-<indexterm significance="preferred"><primary>XSetAfterFunction</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><type>int</type></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> (*procedure)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>procedure</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to be called.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The specified procedure is called with only a display pointer.

-<function>XSetAfterFunction</function>

-returns the previous after function.

-</para>

-<para>

-<!-- .LP -->

-To enable or disable synchronization, use 

-<function>XSynchronize</function>.

-<indexterm><primary>Debugging</primary><secondary>synchronous mode</secondary></indexterm>

-<indexterm significance="preferred"><primary>XSynchronize</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><type>int</type></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Bool<parameter> onoff</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>onoff</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether to enable 

-or disable synchronization.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSynchronize</function>

-function returns 

-the previous after function.

-If onoff is 

-<symbol>True</symbol>,

-<function>XSynchronize</function>

-turns on synchronous behavior.

-If onoff is

-<symbol>False</symbol>,

-<function>XSynchronize</function>

-turns off synchronous behavior.

-</para>

-</sect2>

-<sect2 id="Using_the_Default_Error_Handlers">

-<title>Using the Default Error Handlers</title>

-<!-- .XS -->

-<!-- (SN Using the Default Error Handlers  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Debugging</primary><secondary>error handlers</secondary></indexterm>

-<indexterm><primary>Error</primary><secondary>handlers</secondary></indexterm>

-There are two default error handlers in Xlib: 

-one to handle typically fatal conditions (for example, 

-the connection to a display server dying because a machine crashed) 

-and one to handle protocol errors from the X server.

-These error handlers can be changed to user-supplied routines if you

-prefer your own error handling and can be changed as often as you like.

-If either function is passed a NULL pointer, it will

-reinvoke the default handler.

-The action of the default handlers is to print an explanatory

-message and exit.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the error handler, use

-<function>XSetErrorHandler</function>.

-<indexterm significance="preferred"><primary>XSetErrorHandler</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XSetErrorHandler</function></funcdef>

-  <paramdef>int <parameter> *handler</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>handler</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the program's supplied error handler.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-Xlib generally calls the program's

-supplied error handler whenever an error is received.

-It is not called on

-<errorname>BadName</errorname>

-errors from

-<systemitem>OpenFont</systemitem>,

-<systemitem>LookupColor</systemitem>,

-or

-<systemitem>AllocNamedColor</systemitem>

-protocol requests or on

-<errorname>BadFont</errorname>

-errors from a

-<systemitem>QueryFont</systemitem>

-protocol request.

-These errors generally are reflected back to the program through the

-procedural interface.

-Because this condition is not assumed to be fatal, 

-it is acceptable for your error handler to return;

-the returned value is ignored.

-However, the error handler should not

-call any functions (directly or indirectly) on the display

-that will generate protocol requests or that will look for input events.

-The previous error handler is returned.

-</para>

-<para>

-<!-- .LP -->

-The 

-<structname>XErrorEvent</structname>

-structure contains:

-<indexterm><primary>Debugging</primary><secondary>error event</secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XErrorEvent</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	int type;

-	Display *display;	/* Display the event was read from */

-	unsigned long serial;		/* serial number of failed request */

-	unsigned char error_code;	/* error code of failed request */

-	unsigned char request_code;	/* Major op-code of failed request */

-	unsigned char minor_code;	/* Minor op-code of failed request */

-	XID resourceid;		/* resource id */

-} XErrorEvent;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>Serial Number</primary></indexterm>

-The serial member is the number of requests, starting from one, 

-sent over the network connection since it was opened. 

-It is the number that was the value of 

-<function>NextRequest</function>

-immediately before the failing call was made.  

-The request_code member is a protocol request

-of the procedure that failed, as defined in 

-&lt; X11/Xproto.h .&gt;

-The following error codes can be returned by the functions described in this

-chapter:

-</para>

-<!-- .br -->

-<!-- .ne 13 -->

-<indexterm><primary>Debugging</primary><secondary>error numbers</secondary></indexterm>

-<indexterm><primary>Error</primary><secondary>codes</secondary></indexterm>

-<!-- .\".CP T 3 -->

-<!-- .\"Error Codes -->

-<indexterm significance="preferred"><primary>BadAccess</primary></indexterm>

-<indexterm significance="preferred"><primary>BadAlloc</primary></indexterm>

-<indexterm significance="preferred"><primary>BadAtom</primary></indexterm>

-<indexterm significance="preferred"><primary>BadColor</primary></indexterm>

-<indexterm significance="preferred"><primary>BadCursor</primary></indexterm>

-<indexterm significance="preferred"><primary>BadDrawable</primary></indexterm>

-<indexterm significance="preferred"><primary>BadFont</primary></indexterm>

-<indexterm significance="preferred"><primary>BadGC</primary></indexterm>

-<indexterm significance="preferred"><primary>BadIDChoice</primary></indexterm>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry>Error Code</entry>

-      <entry>Description</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry><errorname>BadAccess</errorname></entry>

-      <entry>A client attempts to grab a key/button combination already grabbed

-      by another client.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>A client attempts to free a colormap entry that it had not already allocated

-      or to free an entry in a colormap that was created with all entries writable.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>A client attempts to store into a read-only or unallocated colormap entry.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>A client attempts to modify the access control list from other than the local

-      (or otherwise authorized) host.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>A client attempts to select an event type that another client

-      has already selected.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadAlloc</errorname></entry>

-      <entry>The server fails to allocate the requested resource.

-      Note that the explicit listing of

-      <errorname>BadAlloc</errorname>

-      errors in requests only covers allocation errors at a very coarse level

-      and is not intended to (nor can it in practice hope to) cover all cases of

-      a server running out of allocation space in the middle of service.

-      The semantics when a server runs out of allocation space are left unspecified,

-      but a server may generate a

-      <errorname>BadAlloc</errorname>

-      error on any request for this reason,

-      and clients should be prepared to receive such errors and handle or discard

-      them.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadAtom</errorname></entry>

-      <entry>A value for an atom argument does not name a defined atom.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadColor</errorname></entry>

-      <entry>A value for a colormap argument does not name a defined colormap.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadCursor</errorname></entry>

-      <entry>A value for a cursor argument does not name a defined cursor.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadDrawable</errorname></entry>

-      <entry>A value for a drawable argument does not name a defined window or pixmap.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadFont</errorname></entry>

-      <entry>A value for a font argument does not name a defined font (or, in some cases,

-      <type>GContext</type>).</entry>

-    </row>

-    <row>

-      <entry><errorname>BadGC</errorname></entry>

-      <entry>A value for a

-      <type>GContext</type>

-      argument does not name a defined 

-      <type>GContext</type>.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadIDChoice</errorname></entry>

-      <entry>The value chosen for a resource identifier either is not included in the

-      range assigned to the client or is already in use.

-      Under normal circumstances,

-      this cannot occur and should be considered a server or Xlib error.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadImplementation</errorname></entry>

-      <entry>The server does not implement some aspect of the request.

-      A server that generates this error for a core request is deficient.

-      As such, this error is not listed for any of the requests,

-      but clients should be prepared to receive such errors

-      and handle or discard them.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadLength</errorname></entry>

-      <entry>The length of a request is shorter or longer than that required to

-      contain the arguments.

-      This is an internal Xlib or server error.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>

-      The length of a request exceeds the maximum length accepted by the server.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadMatch</errorname></entry>

-      <entry>In a graphics request,

-      the root and depth of the graphics context do not match those of the drawable.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>An <symbol>InputOnly</symbol> window is used as a drawable.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>

-      Some argument or pair of arguments has the correct type and range,

-      but it fails to match in some other way required by the request.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>An <symbol>InputOnly</symbol>

-      window lacks this attribute.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadName</errorname></entry>

-      <entry>A font or color of the specified name does not exist.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadPixmap</errorname></entry>

-      <entry>A value for a pixmap argument does not name a defined pixmap.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadRequest</errorname></entry>

-      <entry>The major or minor opcode does not specify a valid request.

-      This usually is an Xlib or server error.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadValue</errorname></entry>

-      <entry>Some numeric value falls outside of the range of values accepted

-      by the request.

-      Unless a specific range is specified for an argument,

-      the full range defined by the argument's type is accepted.

-      Any argument defined as a set of alternatives typically can generate

-      this error (due to the encoding).</entry>

-    </row>

-    <row>

-      <entry><errorname>BadWindow</errorname></entry>

-      <entry>A value for a window argument does not name a defined window.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<indexterm significance="preferred"><primary>BadImplementation</primary></indexterm>

-<indexterm significance="preferred"><primary>BadLength</primary></indexterm>

-<indexterm significance="preferred"><primary>BadMatch</primary></indexterm>

-<indexterm significance="preferred"><primary>BadName</primary></indexterm>

-<indexterm significance="preferred"><primary>BadPixmap</primary></indexterm>

-<indexterm significance="preferred"><primary>BadRequest</primary></indexterm>

-<indexterm significance="preferred"><primary>BadValue</primary></indexterm>

-<indexterm significance="preferred"><primary>BadWindow</primary></indexterm>

-<!-- .NT Note -->

-

-<note>

-<para>

-The 

-<errorname>BadAtom</errorname>,

-<errorname>BadColor</errorname>,

-<errorname>BadCursor</errorname>,

-<errorname>BadDrawable</errorname>,

-<errorname>BadFont</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadPixmap</errorname>,

-and 

-<errorname>BadWindow</errorname>

-errors are also used when the argument type is extended by a set of

-fixed alternatives.

-</para>

-</note>

-

-<!-- .NE -->

-<!-- .sp -->

-<para>

-<!-- .LP -->

-To obtain textual descriptions of the specified error code, use 

-<function>XGetErrorText</function>.

-<indexterm significance="preferred"><primary>XGetErrorText</primary></indexterm>

-<indexterm><primary>Debugging</primary><secondary>error message strings</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGetErrorText</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> code</parameter></paramdef>

-  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

-  <paramdef>int<parameter> length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>code</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the error code for which you want to obtain a description.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buffer_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the error description.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size of the buffer.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XGetErrorText</function>

-function copies a null-terminated string describing the specified error code

-into the specified buffer.

-The returned text is in the encoding of the current locale.

-It is recommended that you use this function to obtain an error description

-because extensions to Xlib may define their own error codes

-and error strings.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain error messages from the error database, use

-<function>XGetErrorDatabaseText</function>.

-<indexterm significance="preferred"><primary>XGetErrorDatabaseText</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGetErrorDatabaseText</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char*name,<parameter> *message</parameter></paramdef>

-  <paramdef>char<parameter> *default_string</parameter></paramdef>

-  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

-  <paramdef>int<parameter> length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the name of the application.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>message</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the type of the error message.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>default_string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the default error message if none is found in the database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buffer_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the error description.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size of the buffer.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetErrorDatabaseText</function>

-function returns a null-terminated message

-(or the default message) from the error message

-database.

-Xlib uses this function internally to look up its error messages.

-The text in the default_string argument is assumed

-to be in the encoding of the current locale,

-and the text stored in the buffer_return argument

-is in the encoding of the current locale.

-</para>

-<para>

-<!-- .LP -->

-The name argument should generally be the name of your application.

-The message argument should indicate which type of error message you want.

-If the name and message are not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-Xlib uses three predefined ``application names'' to report errors.

-In these names,

-uppercase and lowercase matter.

-<variablelist>

-  <varlistentry>

-    <term>

-      XProtoError

-    </term>

-    <listitem>

-      <para>

-The protocol error number is used as a string for the message argument.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      XlibMessage

-    </term>

-    <listitem>

-      <para>

-These are the message strings that are used internally by the library.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      XRequest

-    </term>

-    <listitem>

-      <para>

-For a core protocol request,

-the major request protocol number is used for the message argument.

-For an extension request,

-the extension name (as given by

-<function>InitExtension</function>)

-followed by a period (.) and the minor request protocol number 

-is used for the message argument.

-If no string is found in the error database,

-the default_string is returned to the buffer argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To report an error to the user when the requested display does not exist, use

-<function>XDisplayName</function>.

-<indexterm significance="preferred"><primary>XDisplayName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XDisplayName</function></funcdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDisplayName</function>

-function returns the name of the display that 

-<function>XOpenDisplay</function>

-would attempt to use.

-If a NULL string is specified,

-<function>XDisplayName</function>

-looks in the environment for the display and returns the display name that

-<function>XOpenDisplay</function>

-would attempt to use.

-This makes it easier to report to the user precisely which display the

-program attempted to open when the initial connection attempt failed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To handle fatal I/O errors, use

-<function>XSetIOErrorHandler</function>.

-<indexterm significance="preferred"><primary>XSetIOErrorHandler</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><type>int</type></funcdef>

-  <paramdef>int(*handler)(Display<parameter> *)</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>handler</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the program's supplied error handler.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetIOErrorHandler</function>

-sets the fatal I/O error handler.

-Xlib calls the program's supplied error handler if any sort of system call

-error occurs (for example, the connection to the server was lost).

-This is assumed to be a fatal condition,

-and the called routine should not return.

-If the I/O error handler does return,

-the client process exits.

-</para>

-<para>

-<!-- .LP -->

-Note that the previous error handler is returned.

-<!-- .bp -->

-

-</para>

-</sect2>

-</sect1>

-</chapter>

+<?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="event_handling_functions">
+<title>Event Handling Functions</title>
+
+<para>
+This chapter discusses the Xlib functions you can use to:
+</para>
+<itemizedlist>
+  <listitem><para>Select events</para></listitem>
+  <listitem><para>Handle the output buffer and the event queue</para></listitem>
+  <listitem><para>Select events from the event queue</para></listitem>
+  <listitem><para>Send and get events</para></listitem>
+  <listitem><para>Handle protocol errors</para></listitem>
+</itemizedlist>
+<note><para>
+Some toolkits use their own event-handling functions and do not allow you to
+interchange these event-handling functions with those in Xlib. For further
+information, see the documentation supplied with the toolkit.
+</para></note>
+
+<para>
+Most applications simply are event loops: they wait for an event, decide what to do with it,
+execute some amount of code that results in changes to the display, and then wait for the next
+event.
+</para>
+
+<sect1 id="Selecting_Events">
+<title>Selecting Events</title>
+<!-- .XS -->
+<!-- (SN Selecting Events  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+There are two ways to select the events you want reported to your client
+application.
+One way is to set the event_mask member of the
+<structname>XSetWindowAttributes</structname>
+structure when you call
+<function>XCreateWindow</function>
+and
+<function>XChangeWindowAttributes</function>.
+Another way is to use
+<function>XSelectInput</function>.
+<indexterm significance="preferred"><primary>XSelectInput</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xselectinput'>
+<funcprototype>
+  <funcdef><function>XSelectInput</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN	 -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XSelectInput</function>
+function requests that the X server report the events associated with the 
+specified event mask.
+Initially, X will not report any of these events.
+Events are reported relative to a window.
+If a window is not interested in a device event, it usually propagates to
+the closest ancestor that is interested,
+unless the do_not_propagate mask prohibits it.
+<indexterm><primary>Event</primary><secondary>propagation</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Setting the event-mask attribute of a window overrides any previous call
+for the same window but not for other clients.
+Multiple clients can select for the same events on the same window
+with the following restrictions:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Multiple clients can select events on the same window because their event masks
+are disjoint.
+When the X server generates an event, it reports it
+to all interested clients.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Only one client at a time can select
+<symbol>CirculateRequest</symbol>,
+<symbol>ConfigureRequest</symbol>,
+or
+<symbol>MapRequest</symbol>
+events, which are associated with
+the event mask
+<symbol>SubstructureRedirectMask</symbol>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Only one client at a time can select
+a
+<symbol>ResizeRequest</symbol>
+event, which is associated with
+the event mask
+<symbol>ResizeRedirectMask</symbol>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Only one client at a time can select a 
+<symbol>ButtonPress</symbol>
+event, which is associated with
+the event mask
+<symbol>ButtonPressMask</symbol>.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The server reports the event to all interested clients.
+</para>
+<para>
+<!-- .LP -->
+<function>XSelectInput</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Handling_the_Output_Buffer">
+<title>Handling the Output Buffer</title>
+<!-- .XS -->
+<!-- (SN Handling the Output Buffer -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The output buffer is an area used by Xlib to store requests.
+The functions described in this section flush the output buffer
+if the function would block or not return an event.
+That is, all requests residing in the output buffer that
+have not yet been sent are transmitted to the X server.
+These functions differ in the additional tasks they might perform.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To flush the output buffer, use 
+<function>XFlush</function>.
+<indexterm significance="preferred"><primary>XFlush</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xflush'>
+<funcprototype>
+  <funcdef><function>XFlush</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFlush</function>
+function
+flushes the output buffer.
+Most client applications need not use this function because the output
+buffer is automatically flushed as needed by calls to
+<function>XPending</function>,
+<function>XNextEvent</function>,
+and
+<function>XWindowEvent</function>.
+<indexterm><primary>XPending</primary></indexterm>
+<indexterm><primary>XNextEvent</primary></indexterm>
+<indexterm><primary>XWindowEvent</primary></indexterm>
+Events generated by the server may be enqueued into the library's event queue.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To flush the output buffer and then wait until all requests have been processed,
+use 
+<function>XSync</function>.
+<indexterm significance="preferred"><primary>XSync</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsync'>
+<funcprototype>
+  <funcdef><function>XSync</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Bool<parameter> discard</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>discard</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether 
+<function>XSync</function>
+discards all events on the event queue.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSync</function>
+function
+flushes the output buffer and then waits until all requests have been received
+and processed by the X server.
+Any errors generated must be handled by the error handler.
+For each protocol error received by Xlib,
+<function>XSync</function>
+calls the client application's error handling routine (see section 11.8.2).
+Any events generated by the server are enqueued into the library's 
+event queue.
+</para>
+<para>
+<!-- .LP -->
+Finally, if you passed 
+<symbol>False</symbol>,
+<function>XSync</function>
+does not discard the events in the queue.
+If you passed 
+<symbol>True</symbol>,
+<function>XSync</function>
+discards all events in the queue,
+including those events that were on the queue before
+<function>XSync</function>
+was called.
+Client applications seldom need to call
+<function>XSync</function>.
+</para>
+</sect1>
+<sect1 id="Event_Queue_Management">
+<title>Event Queue Management</title>
+<!-- .XS -->
+<!-- (SN Event Queue Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib maintains an event queue.
+However, the operating system also may be buffering data 
+in its network connection that is not yet read into the event queue.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the number of events in the event queue, use
+<function>XEventsQueued</function>.
+<indexterm significance="preferred"><primary>XEventsQueued</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xeventsqueued'>
+<funcprototype>
+  <funcdef>int <function>XEventsQueued</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the mode.
+You can pass
+<symbol>QueuedAlready</symbol>,
+<symbol>QueuedAfterFlush</symbol>,
+or
+<symbol>QueuedAfterReading</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If mode is 
+<symbol>QueuedAlready</symbol>,
+<function>XEventsQueued</function>
+returns the number of events
+already in the event queue (and never performs a system call).
+If mode is 
+<symbol>QueuedAfterFlush</symbol>,
+<function>XEventsQueued</function>
+returns the number of events already in the queue if the number is nonzero.
+If there are no events in the queue, 
+<function>XEventsQueued</function>
+flushes the output buffer, 
+attempts to read more events out of the application's connection,
+and returns the number read.
+If mode is 
+<symbol>QueuedAfterReading</symbol>,
+<function>XEventsQueued</function>
+returns the number of events already in the queue if the number is nonzero. 
+If there are no events in the queue, 
+<function>XEventsQueued</function>
+attempts to read more events out of the application's connection 
+without flushing the output buffer and returns the number read.
+</para>
+<para>
+<!-- .LP -->
+<function>XEventsQueued</function>
+always returns immediately without I/O if there are events already in the
+queue.
+<function>XEventsQueued</function>
+with mode 
+<symbol>QueuedAfterFlush</symbol>
+is identical in behavior to
+<function>XPending</function>.
+<function>XEventsQueued</function>
+with mode
+<symbol>QueuedAlready</symbol>
+is identical to the
+<function>XQLength</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the number of events that are pending, use 
+<function>XPending</function>.
+<indexterm significance="preferred"><primary>XPending</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpending'>
+<funcprototype>
+  <funcdef>int <function>XPending</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN	 -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPending</function>
+function returns the number of events that have been received from the
+X server but have not been removed from the event queue.
+<function>XPending</function>
+is identical to
+<function>XEventsQueued</function>
+with the mode
+<symbol>QueuedAfterFlush</symbol>
+specified.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Event_Queue">
+<title>Manipulating the Event Queue</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Event Queue  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that let you manipulate the event queue.
+This section discusses how to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Obtain events, in order, and remove them from the queue
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Peek at events in the queue without removing them
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Obtain events that match the event mask or the arbitrary
+predicate procedures that you provide
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Returning_the_Next_Event">
+<title>Returning the Next Event</title>
+<!-- .XS -->
+<!-- (SN Returning the Next Event -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To get the next event and remove it from the queue, use
+<function>XNextEvent</function>.
+<indexterm significance="preferred"><primary>XNextEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xnextevent'>
+<funcprototype>
+  <funcdef><function>XNextEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the next event in the queue.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNextEvent</function>
+function copies the first event from the event queue into the specified
+<structname>XEvent</structname>
+structure and then removes it from the queue.
+If the event queue is empty,
+<function>XNextEvent</function>
+flushes the output buffer and blocks until an event is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To peek at the event queue, use
+<function>XPeekEvent</function>.
+<indexterm significance="preferred"><primary>XPeekEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpeekevent'>
+<funcprototype>
+  <funcdef><function>XPeekEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a copy of the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPeekEvent</function>
+function returns the first event from the event queue,
+but it does not remove the event from the queue.
+If the queue is empty,
+<function>XPeekEvent</function>
+flushes the output buffer and blocks until an event is received.
+It then copies the event into the client-supplied
+<structname>XEvent</structname>
+structure without removing it from the event queue.
+</para>
+</sect2>
+<sect2 id="Selecting_Events_Using_a_Predicate_Procedure">
+<title>Selecting Events Using a Predicate Procedure</title>
+<!-- .XS -->
+<!-- (SN Selecting Events Using a Predicate Procedure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Each of the functions discussed in this section requires you to
+pass a predicate procedure that determines if an event matches 
+what you want.
+Your predicate procedure must decide if the event is useful
+without calling any Xlib functions.
+If the predicate directly or indirectly causes the state of the event queue
+to change, the result is not defined.
+If Xlib has been initialized for threads, the predicate is called with
+the display locked and the result of a call by the predicate to any
+Xlib function that locks the display is not defined unless the caller
+has first called
+<function>XLockDisplay</function>.
+</para>
+<para>
+<!-- .LP -->
+The predicate procedure and its associated arguments are:
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef><type>Bool</type></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XEvent</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the argument passed in from the 
+<function>XIfEvent</function>,
+<function>XCheckIfEvent</function>,
+or
+<function>XPeekIfEvent</function>
+function.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The predicate procedure is called once for each
+event in the queue until it finds a match. 
+After finding a match, the predicate procedure must return 
+<symbol>True</symbol>.
+If it did not find a match, it must return
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event
+and, if found, remove the event from the queue, use
+<function>XIfEvent</function>.
+<indexterm significance="preferred"><primary>XIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xifevent'>
+<funcprototype>
+  <funcdef><function>XIfEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>predicate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIfEvent</function>
+function completes only when the specified predicate
+procedure returns 
+<symbol>True</symbol>
+for an event, 
+which indicates an event in the queue matches.
+<function>XIfEvent</function>
+flushes the output buffer if it blocks waiting for additional events.
+<function>XIfEvent</function>
+removes the matching event from the queue 
+and copies the structure into the client-supplied
+<structname>XEvent</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event without blocking, use
+<function>XCheckIfEvent</function>.
+<indexterm significance="preferred"><primary>XCheckIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcheckifevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckIfEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a copy of the matched event's associated structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>predicate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When the predicate procedure finds a match,
+<function>XCheckIfEvent</function>
+copies the matched event into the client-supplied
+<structname>XEvent</structname>
+structure and returns 
+<symbol>True</symbol>.
+(This event is removed from the queue.)
+If the predicate procedure finds no match,
+<function>XCheckIfEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+All earlier events stored in the queue are not discarded.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event
+without removing the event from the queue, use
+<function>XPeekIfEvent</function>.
+<indexterm significance="preferred"><primary>XPeekIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpeekifevent'>
+<funcprototype>
+  <funcdef><function>XPeekIfEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a copy of the matched event's associated structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>predicate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPeekIfEvent</function>
+function returns only when the specified predicate
+procedure returns 
+<symbol>True</symbol>
+for an event.
+After the predicate procedure finds a match,
+<function>XPeekIfEvent</function>
+copies the matched event into the client-supplied
+<structname>XEvent</structname>
+structure without removing the event from the queue.
+<function>XPeekIfEvent</function>
+flushes the output buffer if it blocks waiting for additional events.
+</para>
+</sect2>
+<sect2 id="Selecting_Events_Using_a_Window_or_Event_Mask">
+<title>Selecting Events Using a Window or Event Mask</title>
+<!-- .XS -->
+<!-- (SN Selecting Events Using a Window or Event Mask -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The functions discussed in this section let you select events by window 
+or event types, allowing you to process events out of order.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches both a window and an event mask, use
+<function>XWindowEvent</function>.
+<indexterm significance="preferred"><primary>XWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xwindowevent'>
+<funcprototype>
+  <funcdef><function>XWindowEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWindowEvent</function>
+function searches the event queue for an event that matches both the specified
+window and event mask.
+When it finds a match,
+<function>XWindowEvent</function>
+removes that event from the queue and copies it into the specified
+<structname>XEvent</structname>
+structure.
+The other events stored in the queue are not discarded.
+If a matching event is not in the queue,
+<function>XWindowEvent</function>
+flushes the output buffer and blocks until one is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches both a window and an event mask (if any),
+use
+<function>XCheckWindowEvent</function>.
+<indexterm><primary>XCheckWindowEvent</primary></indexterm>
+This function is similar to
+<function>XWindowEvent</function>
+except that it never blocks and it returns a 
+<type>Bool</type>
+indicating if the event was returned.
+<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcheckwindowevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckWindowEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckWindowEvent</function>
+function searches the event queue and then the events available 
+on the server connection for the first event that matches the specified window
+and event mask.
+If it finds a match,
+<function>XCheckWindowEvent</function>
+removes that event, copies it into the specified
+<structname>XEvent</structname>
+structure, and returns
+<symbol>True</symbol>.
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+<function>XCheckWindowEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches an event mask, use
+<function>XMaskEvent</function>.
+<indexterm significance="preferred"><primary>XMaskEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmaskevent'>
+<funcprototype>
+  <funcdef><function>XMaskEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMaskEvent</function>
+function searches the event queue for the events associated with the 
+specified mask.
+When it finds a match,
+<function>XMaskEvent</function>
+removes that event and copies it into the specified
+<structname>XEvent</structname>
+structure.
+The other events stored in the queue are not discarded.
+If the event you requested is not in the queue,
+<function>XMaskEvent</function>
+flushes the output buffer and blocks until one is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event that matches an event mask (if any), use
+<function>XCheckMaskEvent</function>.
+This function is similar to 
+<function>XMaskEvent</function>
+except that it never blocks and it returns a 
+<type>Bool</type>
+indicating if the event was returned.
+<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcheckmaskevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckMaskEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckMaskEvent</function>
+function searches the event queue and then any events available on the
+server connection for the first event that matches the specified mask.
+If it finds a match,
+<function>XCheckMaskEvent</function>
+removes that event, copies it into the specified
+<structname>XEvent</structname>
+structure, and returns
+<symbol>True</symbol>.
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+<function>XCheckMaskEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp  -->
+To return and remove the next event in the queue that matches an event type, use
+<function>XCheckTypedEvent</function>.
+<indexterm significance="preferred"><primary>XCheckTypedEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchecktypedevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckTypedEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> event_type</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_type</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event type to be compared.
+
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckTypedEvent</function>
+function searches the event queue and then any events available  
+on the server connection for the first event that matches the specified type.
+If it finds a match,
+<function>XCheckTypedEvent</function>
+removes that event, copies it into the specified
+<structname>XEvent</structname>
+structure, and returns
+<symbol>True</symbol>.
+The other events in the queue are not discarded.
+If the event is not available,
+<function>XCheckTypedEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event in the queue that matches an event type 
+and a window, use
+<function>XCheckTypedWindowEvent</function>.
+<indexterm significance="preferred"><primary>XCheckTypedWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchecktypedwindowevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckTypedWindowEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> event_type</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_type</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event type to be compared.
+
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckTypedWindowEvent</function>
+function searches the event queue and then any events available  
+on the server connection for the first event that matches the specified
+type and window.
+If it finds a match,
+<function>XCheckTypedWindowEvent</function>
+removes the event from the queue, copies it into the specified
+<structname>XEvent</structname>
+structure, and returns
+<symbol>True</symbol>.
+The other events in the queue are not discarded.
+If the event is not available,
+<function>XCheckTypedWindowEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Putting_an_Event_Back_into_the_Queue">
+<title>Putting an Event Back into the Queue</title>
+<!-- .XS -->
+<!-- (SN Putting an Event Back into the Queue  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To push an event back into the event queue, use
+<function>XPutBackEvent</function>.
+<indexterm significance="preferred"><primary>XPutBackEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xputbackevent'>
+<funcprototype>
+  <funcdef><function>XPutBackEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XPutBackEvent</function>
+function pushes an event back onto the head of the display's event queue
+by copying the event into the queue.
+This can be useful if you read an event and then decide that you
+would rather deal with it later.
+There is no limit to the number of times in succession that you can call
+<function>XPutBackEvent</function>.
+</para>
+</sect1>
+<sect1 id="Sending_Events_to_Other_Applications">
+<title>Sending Events to Other Applications</title>
+<!-- .XS -->
+<!-- (SN Sending Events to Other Applications -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To send an event to a specified window, use
+<function>XSendEvent</function>.
+<indexterm><primary>XSendEvent</primary></indexterm>
+This function is often used in selection processing.
+For example, the owner of a selection should use
+<function>XSendEvent</function>
+to send a
+<symbol>SelectionNotify</symbol>
+event to a requestor when a selection has been converted 
+and stored as a property.
+<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsendevent'>
+<funcprototype>
+  <funcdef>Status <function>XSendEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Bool<parameter> propagate</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_send</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window the event is to be sent to, or
+<symbol>PointerWindow</symbol>,
+or
+<symbol>InputFocus</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>propagate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_send</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event that is to be sent.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSendEvent</function>
+function identifies the destination window, 
+determines which clients should receive the specified events, 
+and ignores any active grabs.
+This function requires you to pass an event mask.
+For a discussion of the valid event mask names,
+see section 10.3.
+This function uses the w argument to identify the destination window as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If w is
+<symbol>PointerWindow</symbol>,
+the destination window is the window that contains the pointer.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If w is
+<symbol>InputFocus</symbol>
+and if the focus window contains the pointer, 
+the destination window is the window that contains the pointer; 
+otherwise, the destination window is the focus window.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To determine which clients should receive the specified events,
+<function>XSendEvent</function>
+uses the propagate argument as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If event_mask is the empty set,
+the event is sent to the client that created the destination window.
+If that client no longer exists,
+no event is sent.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If propagate is 
+<symbol>False</symbol>,
+the event is sent to every client selecting on destination any of the event
+types in the event_mask argument.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If propagate is 
+<symbol>True</symbol>
+and no clients have selected on destination any of
+the event types in event-mask, the destination is replaced with the
+closest ancestor of destination for which some client has selected a
+type in event-mask and for which no intervening window has that type in its
+do-not-propagate-mask. 
+If no such window exists or if the window is
+an ancestor of the focus window and 
+<symbol>InputFocus</symbol>
+was originally specified
+as the destination, the event is not sent to any clients.
+Otherwise, the event is reported to every client selecting on the final
+destination any of the types specified in event_mask.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The event in the
+<structname>XEvent</structname>
+structure must be one of the core events or one of the events
+defined by an extension (or a 
+<errorname>BadValue</errorname>
+error results) so that the X server can correctly byte-swap 
+the contents as necessary.  
+The contents of the event are
+otherwise unaltered and unchecked by the X server except to force send_event to
+<symbol>True</symbol>
+in the forwarded event and to set the serial number in the event correctly;
+therefore these fields
+and the display field are ignored by
+<function>XSendEvent</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XSendEvent</function>
+returns zero if the conversion to wire protocol format failed
+and returns nonzero otherwise.
+</para>
+<para>
+<!-- .LP -->
+<function>XSendEvent</function>
+can generate
+<errorname>BadValue</errorname>
+and 
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Getting_Pointer_Motion_History">
+<title>Getting Pointer Motion History</title>
+<!-- .XS -->
+<!-- (SN Getting Pointer Motion History -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some X server implementations will maintain a more complete
+history of pointer motion than is reported by event notification.
+The pointer position at each pointer hardware interrupt may be
+stored in a buffer for later retrieval.
+This buffer is called the motion history buffer.
+For example, a few applications, such as paint programs,
+want to have a precise history of where the pointer
+traveled. 
+However, this historical information is highly excessive for most applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine the approximate maximum number of elements in the motion buffer, 
+use
+<function>XDisplayMotionBufferSize</function>.
+<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplaymotionbuffersize'>
+<funcprototype>
+  <funcdef>unsigned <type>long</type></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The server may retain the recent history of the pointer motion
+and do so to a finer granularity than is reported by
+<symbol>MotionNotify</symbol>
+events.
+The
+<function>XGetMotionEvents</function>
+function makes this history available.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the motion history for a specified window and time, use
+<function>XGetMotionEvents</function>.
+<indexterm significance="preferred"><primary>XGetMotionEvents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetmotionevents'>
+<funcprototype>
+  <funcdef>XTimeCoord *<function>XGetMotionEvents</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Timestart,<parameter> stop</parameter></paramdef>
+  <paramdef>int<parameter> *nevents_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>start</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>stop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the time interval in which the events are returned from the motion
+history buffer.
+You can pass a timestamp or
+<symbol>CurrentTime</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nevents_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of events from the motion history buffer.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetMotionEvents</function>
+function returns all events in the motion history buffer that fall between the
+specified start and stop times, inclusive, and that have coordinates
+that lie within the specified window (including its borders) at its present
+placement.
+If the server does not support motion history, 
+if the start time is later than the stop time,
+or if the start time is in the future, 
+no events are returned;
+<function>XGetMotionEvents</function>
+returns NULL.
+If the stop time is in the future, it is equivalent to specifying
+<symbol>CurrentTime</symbol>.
+The return type for this function is a structure defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XTimeCoord</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+	Time time;
+	short x, y;
+} XTimeCoord;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The time member is set to the time, in milliseconds. 
+The x and y members are set to the coordinates of the pointer and
+are reported relative to the origin
+of the specified window.
+To free the data returned from this call, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetMotionEvents</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Handling_Protocol_Errors">
+<title>Handling Protocol Errors</title>
+<!-- .XS -->
+<!-- (SN Handling Protocol Errors -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to enable or disable synchronization
+and to use the default error handlers.
+</para>
+<sect2 id="Enabling_or_Disabling_Synchronization">
+<title>Enabling or Disabling Synchronization</title>
+<!-- .XS -->
+<!-- (SN Enabling or Disabling Synchronization  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When debugging X applications, 
+it often is very convenient to require Xlib to behave synchronously
+so that errors are reported as they occur.
+The following function lets you disable or enable synchronous behavior.
+Note that graphics may occur 30 or more times more slowly when 
+synchronization is enabled.
+<indexterm><primary>_Xdebug</primary></indexterm>
+On <acronym>POSIX</acronym>-conformant systems,
+there is also a global variable 
+<varname>_Xdebug</varname>
+that, if set to nonzero before starting a program under a debugger, will force
+synchronous library behavior.
+</para>
+<para>
+<!-- .LP -->
+After completing their work,
+all Xlib functions that generate protocol requests call what is known as
+an after function.
+<function>XSetAfterFunction</function>
+sets which function is to be called.
+<indexterm significance="preferred"><primary>XSetAfterFunction</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetafterfunction'>
+<funcprototype>
+  <funcdef><type>int</type></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> (*procedure)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>procedure</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to be called.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The specified procedure is called with only a display pointer.
+<function>XSetAfterFunction</function>
+returns the previous after function.
+</para>
+<para>
+<!-- .LP -->
+To enable or disable synchronization, use 
+<function>XSynchronize</function>.
+<indexterm><primary>Debugging</primary><secondary>synchronous mode</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSynchronize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsynchronize'>
+<funcprototype>
+  <funcdef><type>int</type></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Bool<parameter> onoff</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>onoff</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether to enable 
+or disable synchronization.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSynchronize</function>
+function returns 
+the previous after function.
+If onoff is 
+<symbol>True</symbol>,
+<function>XSynchronize</function>
+turns on synchronous behavior.
+If onoff is
+<symbol>False</symbol>,
+<function>XSynchronize</function>
+turns off synchronous behavior.
+</para>
+</sect2>
+<sect2 id="Using_the_Default_Error_Handlers">
+<title>Using the Default Error Handlers</title>
+<!-- .XS -->
+<!-- (SN Using the Default Error Handlers  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Debugging</primary><secondary>error handlers</secondary></indexterm>
+<indexterm><primary>Error</primary><secondary>handlers</secondary></indexterm>
+There are two default error handlers in Xlib: 
+one to handle typically fatal conditions (for example, 
+the connection to a display server dying because a machine crashed) 
+and one to handle protocol errors from the X server.
+These error handlers can be changed to user-supplied routines if you
+prefer your own error handling and can be changed as often as you like.
+If either function is passed a NULL pointer, it will
+reinvoke the default handler.
+The action of the default handlers is to print an explanatory
+message and exit.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the error handler, use
+<function>XSetErrorHandler</function>.
+<indexterm significance="preferred"><primary>XSetErrorHandler</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xseterrorhandler'>
+<funcprototype>
+  <funcdef>int *<function>XSetErrorHandler</function></funcdef>
+  <paramdef>int <parameter> *handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>handler</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the program's supplied error handler.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+Xlib generally calls the program's
+supplied error handler whenever an error is received.
+It is not called on
+<errorname>BadName</errorname>
+errors from
+<systemitem>OpenFont</systemitem>,
+<systemitem>LookupColor</systemitem>,
+or
+<systemitem>AllocNamedColor</systemitem>
+protocol requests or on
+<errorname>BadFont</errorname>
+errors from a
+<systemitem>QueryFont</systemitem>
+protocol request.
+These errors generally are reflected back to the program through the
+procedural interface.
+Because this condition is not assumed to be fatal, 
+it is acceptable for your error handler to return;
+the returned value is ignored.
+However, the error handler should not
+call any functions (directly or indirectly) on the display
+that will generate protocol requests or that will look for input events.
+The previous error handler is returned.
+</para>
+<para>
+<!-- .LP -->
+The 
+<structname>XErrorEvent</structname>
+structure contains:
+<indexterm><primary>Debugging</primary><secondary>error event</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XErrorEvent</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	int type;
+	Display *display;	/* Display the event was read from */
+	unsigned long serial;		/* serial number of failed request */
+	unsigned char error_code;	/* error code of failed request */
+	unsigned char request_code;	/* Major op-code of failed request */
+	unsigned char minor_code;	/* Minor op-code of failed request */
+	XID resourceid;		/* resource id */
+} XErrorEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Serial Number</primary></indexterm>
+The serial member is the number of requests, starting from one, 
+sent over the network connection since it was opened. 
+It is the number that was the value of 
+<function>NextRequest</function>
+immediately before the failing call was made.  
+The request_code member is a protocol request
+of the procedure that failed, as defined in 
+&lt; X11/Xproto.h .&gt;
+The following error codes can be returned by the functions described in this
+chapter:
+</para>
+<!-- .br -->
+<!-- .ne 13 -->
+<indexterm><primary>Debugging</primary><secondary>error numbers</secondary></indexterm>
+<indexterm><primary>Error</primary><secondary>codes</secondary></indexterm>
+<!-- .\".CP T 3 -->
+<!-- .\"Error Codes -->
+<indexterm significance="preferred"><primary>BadAccess</primary></indexterm>
+<indexterm significance="preferred"><primary>BadAlloc</primary></indexterm>
+<indexterm significance="preferred"><primary>BadAtom</primary></indexterm>
+<indexterm significance="preferred"><primary>BadColor</primary></indexterm>
+<indexterm significance="preferred"><primary>BadCursor</primary></indexterm>
+<indexterm significance="preferred"><primary>BadDrawable</primary></indexterm>
+<indexterm significance="preferred"><primary>BadFont</primary></indexterm>
+<indexterm significance="preferred"><primary>BadGC</primary></indexterm>
+<indexterm significance="preferred"><primary>BadIDChoice</primary></indexterm>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry>Error Code</entry>
+      <entry>Description</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry><errorname>BadAccess</errorname></entry>
+      <entry>A client attempts to grab a key/button combination already grabbed
+      by another client.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>A client attempts to free a colormap entry that it had not already allocated
+      or to free an entry in a colormap that was created with all entries writable.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>A client attempts to store into a read-only or unallocated colormap entry.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>A client attempts to modify the access control list from other than the local
+      (or otherwise authorized) host.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>A client attempts to select an event type that another client
+      has already selected.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadAlloc</errorname></entry>
+      <entry>The server fails to allocate the requested resource.
+      Note that the explicit listing of
+      <errorname>BadAlloc</errorname>
+      errors in requests only covers allocation errors at a very coarse level
+      and is not intended to (nor can it in practice hope to) cover all cases of
+      a server running out of allocation space in the middle of service.
+      The semantics when a server runs out of allocation space are left unspecified,
+      but a server may generate a
+      <errorname>BadAlloc</errorname>
+      error on any request for this reason,
+      and clients should be prepared to receive such errors and handle or discard
+      them.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadAtom</errorname></entry>
+      <entry>A value for an atom argument does not name a defined atom.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadColor</errorname></entry>
+      <entry>A value for a colormap argument does not name a defined colormap.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadCursor</errorname></entry>
+      <entry>A value for a cursor argument does not name a defined cursor.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadDrawable</errorname></entry>
+      <entry>A value for a drawable argument does not name a defined window or pixmap.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadFont</errorname></entry>
+      <entry>A value for a font argument does not name a defined font (or, in some cases,
+      <type>GContext</type>).</entry>
+    </row>
+    <row>
+      <entry><errorname>BadGC</errorname></entry>
+      <entry>A value for a
+      <type>GContext</type>
+      argument does not name a defined 
+      <type>GContext</type>.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadIDChoice</errorname></entry>
+      <entry>The value chosen for a resource identifier either is not included in the
+      range assigned to the client or is already in use.
+      Under normal circumstances,
+      this cannot occur and should be considered a server or Xlib error.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadImplementation</errorname></entry>
+      <entry>The server does not implement some aspect of the request.
+      A server that generates this error for a core request is deficient.
+      As such, this error is not listed for any of the requests,
+      but clients should be prepared to receive such errors
+      and handle or discard them.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadLength</errorname></entry>
+      <entry>The length of a request is shorter or longer than that required to
+      contain the arguments.
+      This is an internal Xlib or server error.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>
+      The length of a request exceeds the maximum length accepted by the server.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadMatch</errorname></entry>
+      <entry>In a graphics request,
+      the root and depth of the graphics context do not match those of the drawable.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>An <symbol>InputOnly</symbol> window is used as a drawable.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>
+      Some argument or pair of arguments has the correct type and range,
+      but it fails to match in some other way required by the request.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>An <symbol>InputOnly</symbol>
+      window lacks this attribute.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadName</errorname></entry>
+      <entry>A font or color of the specified name does not exist.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadPixmap</errorname></entry>
+      <entry>A value for a pixmap argument does not name a defined pixmap.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadRequest</errorname></entry>
+      <entry>The major or minor opcode does not specify a valid request.
+      This usually is an Xlib or server error.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadValue</errorname></entry>
+      <entry>Some numeric value falls outside of the range of values accepted
+      by the request.
+      Unless a specific range is specified for an argument,
+      the full range defined by the argument's type is accepted.
+      Any argument defined as a set of alternatives typically can generate
+      this error (due to the encoding).</entry>
+    </row>
+    <row>
+      <entry><errorname>BadWindow</errorname></entry>
+      <entry>A value for a window argument does not name a defined window.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<indexterm significance="preferred"><primary>BadImplementation</primary></indexterm>
+<indexterm significance="preferred"><primary>BadLength</primary></indexterm>
+<indexterm significance="preferred"><primary>BadMatch</primary></indexterm>
+<indexterm significance="preferred"><primary>BadName</primary></indexterm>
+<indexterm significance="preferred"><primary>BadPixmap</primary></indexterm>
+<indexterm significance="preferred"><primary>BadRequest</primary></indexterm>
+<indexterm significance="preferred"><primary>BadValue</primary></indexterm>
+<indexterm significance="preferred"><primary>BadWindow</primary></indexterm>
+<!-- .NT Note -->
+
+<note>
+<para>
+The 
+<errorname>BadAtom</errorname>,
+<errorname>BadColor</errorname>,
+<errorname>BadCursor</errorname>,
+<errorname>BadDrawable</errorname>,
+<errorname>BadFont</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadPixmap</errorname>,
+and 
+<errorname>BadWindow</errorname>
+errors are also used when the argument type is extended by a set of
+fixed alternatives.
+</para>
+</note>
+
+<!-- .NE -->
+<!-- .sp -->
+<para>
+<!-- .LP -->
+To obtain textual descriptions of the specified error code, use 
+<function>XGetErrorText</function>.
+<indexterm significance="preferred"><primary>XGetErrorText</primary></indexterm>
+<indexterm><primary>Debugging</primary><secondary>error message strings</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeterrortext'>
+<funcprototype>
+  <funcdef><function>XGetErrorText</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> code</parameter></paramdef>
+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+  <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>code</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the error code for which you want to obtain a description.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buffer_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the error description.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size of the buffer.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XGetErrorText</function>
+function copies a null-terminated string describing the specified error code
+into the specified buffer.
+The returned text is in the encoding of the current locale.
+It is recommended that you use this function to obtain an error description
+because extensions to Xlib may define their own error codes
+and error strings.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain error messages from the error database, use
+<function>XGetErrorDatabaseText</function>.
+<indexterm significance="preferred"><primary>XGetErrorDatabaseText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeterrordatabasetext'>
+<funcprototype>
+  <funcdef><function>XGetErrorDatabaseText</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char*name,<parameter> *message</parameter></paramdef>
+  <paramdef>char<parameter> *default_string</parameter></paramdef>
+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+  <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the name of the application.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>message</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the type of the error message.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>default_string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the default error message if none is found in the database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buffer_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the error description.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size of the buffer.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetErrorDatabaseText</function>
+function returns a null-terminated message
+(or the default message) from the error message
+database.
+Xlib uses this function internally to look up its error messages.
+The text in the default_string argument is assumed
+to be in the encoding of the current locale,
+and the text stored in the buffer_return argument
+is in the encoding of the current locale.
+</para>
+<para>
+<!-- .LP -->
+The name argument should generally be the name of your application.
+The message argument should indicate which type of error message you want.
+If the name and message are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Xlib uses three predefined ``application names'' to report errors.
+In these names,
+uppercase and lowercase matter.
+<variablelist>
+  <varlistentry>
+    <term>
+      XProtoError
+    </term>
+    <listitem>
+      <para>
+The protocol error number is used as a string for the message argument.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      XlibMessage
+    </term>
+    <listitem>
+      <para>
+These are the message strings that are used internally by the library.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      XRequest
+    </term>
+    <listitem>
+      <para>
+For a core protocol request,
+the major request protocol number is used for the message argument.
+For an extension request,
+the extension name (as given by
+<function>InitExtension</function>)
+followed by a period (.) and the minor request protocol number 
+is used for the message argument.
+If no string is found in the error database,
+the default_string is returned to the buffer argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To report an error to the user when the requested display does not exist, use
+<function>XDisplayName</function>.
+<indexterm significance="preferred"><primary>XDisplayName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplayname'>
+<funcprototype>
+  <funcdef>char *<function>XDisplayName</function></funcdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayName</function>
+function returns the name of the display that 
+<function>XOpenDisplay</function>
+would attempt to use.
+If a NULL string is specified,
+<function>XDisplayName</function>
+looks in the environment for the display and returns the display name that
+<function>XOpenDisplay</function>
+would attempt to use.
+This makes it easier to report to the user precisely which display the
+program attempted to open when the initial connection attempt failed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To handle fatal I/O errors, use
+<function>XSetIOErrorHandler</function>.
+<indexterm significance="preferred"><primary>XSetIOErrorHandler</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetioerrorhandler'>
+<funcprototype>
+  <funcdef><type>int</type></funcdef>
+  <paramdef>int(*handler)(Display<parameter> *)</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>handler</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the program's supplied error handler.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIOErrorHandler</function>
+sets the fatal I/O error handler.
+Xlib calls the program's supplied error handler if any sort of system call
+error occurs (for example, the connection to the server was lost).
+This is assumed to be a fatal condition,
+and the called routine should not return.
+If the I/O error handler does return,
+the client process exits.
+</para>
+<para>
+<!-- .LP -->
+Note that the previous error handler is returned.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH12.xml b/libX11/specs/libX11/CH12.xml
index bfde8d927..2a688bdc5 100644
--- a/libX11/specs/libX11/CH12.xml
+++ b/libX11/specs/libX11/CH12.xml
@@ -1,3937 +1,3937 @@
-<?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="input_device_functions">

-<title>Input Device Functions</title>

-

-<para>

-You can use the Xlib input device functions to:

-</para>

-

-<itemizedlist>

-  <listitem><para>Grab the pointer and individual buttons on the pointer</para></listitem>

-  <listitem><para>Grab the keyboard and individual keys on the keyboard</para></listitem>

-  <listitem><para>Resume event processing</para></listitem>

-  <listitem><para>Move the pointer</para></listitem>

-  <listitem><para>Set the input focus</para></listitem>

-  <listitem><para>Manipulate the keyboard and pointer settings</para></listitem>

-  <listitem><para>Manipulate the keyboard encoding</para></listitem>

-</itemizedlist>

-

-<sect1 id="Pointer_Grabbing_">

-<title>Pointer Grabbing </title>

-<!-- .XS -->

-<!-- (SN Pointer Grabbing   -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to control input from the pointer,

-which usually is a mouse.

-Usually, as soon as keyboard and mouse events occur,

-the X server delivers them to the appropriate client,

-which is determined by the window and input focus.

-The X server provides sufficient control over event delivery to

-allow window managers to support mouse ahead and various other

-styles of user interface.

-Many of these user interfaces depend on synchronous delivery of events.

-The delivery of  pointer and keyboard events can be controlled

-independently.

-</para>

-<para>

-<!-- .LP -->

-When mouse buttons or keyboard keys are grabbed, events

-will be sent to the grabbing client rather than the normal

-client who would have received the event.

-If the keyboard or pointer is in asynchronous mode,

-further mouse and keyboard events will continue to be processed.

-If the keyboard or pointer is in synchronous mode, no

-further events are processed until the grabbing client

-allows them (see

-<function>XAllowEvents</function>).

-The keyboard or pointer is considered frozen during this

-interval.

-The event that triggered the grab can also be replayed.

-</para>

-<para>

-<!-- .LP -->

-Note that the logical state of a device (as seen by client applications)

-may lag the physical state if device event processing is frozen.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>Active grab</primary></indexterm>

-There are two kinds of grabs:

-active and passive.

-An active grab occurs when a single client grabs the keyboard and/or pointer

-explicitly (see

-<function>XGrabPointer</function>

-and

-<function>XGrabKeyboard</function>).

-<indexterm><primary>Passive grab</primary></indexterm>

-A passive grab occurs when clients grab a particular keyboard key 

-or pointer button in a window,

-and the grab will activate when the key or button is actually pressed.

-Passive grabs are convenient for implementing reliable pop-up menus.

-For example, you can guarantee that the pop-up is mapped 

-before the up pointer button event occurs by

-grabbing a button requesting synchronous behavior.

-The down event will trigger the grab and freeze further

-processing of pointer events until you have the chance to

-map the pop-up window.

-You can then allow further event processing.

-The up event will then be correctly processed relative to the

-pop-up window.

-</para>

-<para>

-<!-- .LP -->

-For many operations,

-there are functions that take a time argument.

-The X server includes a timestamp in various events.

-One special time, called

-<indexterm significance="preferred"><primary>CurrentTime</primary></indexterm>

-<indexterm significance="preferred"><primary>Time</primary></indexterm>

-<symbol>CurrentTime</symbol>,

-represents the current server time.

-The X server maintains the time when the input focus was last changed,

-when the keyboard was last grabbed,

-when the pointer was last grabbed,

-or when a selection was last changed.

-Your

-application may be slow reacting to an event.

-You often need some way to specify that your

-request should not occur if another application has in the meanwhile

-taken control of the keyboard, pointer, or selection.

-By providing the timestamp from the event in the request, 

-you can arrange that the operation not take effect

-if someone else has performed an operation in the meanwhile.

-</para>

-<para>

-<!-- .LP -->

-A timestamp is a time value, expressed in milliseconds. 

-It typically is the time since the last server reset.

-Timestamp values wrap around (after about 49.7 days).

-The server, given its current time is represented by timestamp T, 

-always interprets timestamps from clients by treating half of the timestamp 

-space as being later in time than T.

-One timestamp value, named

-<symbol>CurrentTime</symbol>,

-is never generated by the server.

-This value is reserved for use in requests to represent the current server time.

-</para>

-<para>

-<!-- .LP -->

-For many functions in this section,

-you pass pointer event mask bits.

-The valid pointer event mask bits are:

-<symbol>ButtonPressMask</symbol>,

-<symbol>ButtonReleaseMask</symbol>,

-<symbol>EnterWindowMask</symbol>,

-<symbol>LeaveWindowMask</symbol>,

-<symbol>PointerMotionMask</symbol>,

-<symbol>PointerMotionHintMask</symbol>,

-<symbol>Button1MotionMask</symbol>,

-<symbol>Button2MotionMask</symbol>,

-<symbol>Button3MotionMask</symbol>,

-<symbol>Button4MotionMask</symbol>,

-<symbol>Button5MotionMask</symbol>,

-<symbol>ButtonMotionMask</symbol>,

-and

-<symbol>KeymapStateMask</symbol>.

-For other functions in this section,

-you pass keymask bits.

-The valid keymask bits are:

-<symbol>ShiftMask</symbol>,

-<symbol>LockMask</symbol>,

-<symbol>ControlMask</symbol>,

-<symbol>Mod1Mask</symbol>,

-<symbol>Mod2Mask</symbol>,

-<symbol>Mod3Mask</symbol>,

-<symbol>Mod4Mask</symbol>,

-and

-<symbol>Mod5Mask</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To grab the pointer, use

-<function>XGrabPointer</function>.

-<indexterm><primary>Grabbing</primary><secondary>pointer</secondary></indexterm>

-<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGrabPointer</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XGrabPointer</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> grab_window</parameter></paramdef>

-  <paramdef>Bool<parameter> owner_events</parameter></paramdef>

-  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>

-  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>

-  <paramdef>Window<parameter> confine_to</parameter></paramdef>

-  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>grab_window</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the grab window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>owner_events</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether the pointer 

-events are to be reported as usual or reported with respect to the grab window 

-if selected by the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which pointer events are reported to the client.

-The mask is the bitwise inclusive OR of the valid pointer event mask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pointer_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies further processing of pointer events.

-You can pass 

-<symbol>GrabModeSync</symbol>

-or

-<symbol>GrabModeAsync</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keyboard_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies further processing of keyboard events.

-You can pass 

-<symbol>GrabModeSync</symbol>

-or

-<symbol>GrabModeAsync</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>confine_to</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window to confine the pointer in or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>cursor</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the cursor that is to be displayed during the grab or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGrabPointer</function>

-function actively grabs control of the pointer and returns

-<symbol>GrabSuccess</symbol>

-if the grab was successful.

-Further pointer events are reported only to the grabbing client.

-<function>XGrabPointer</function>

-overrides any active pointer grab by this client.

-If owner_events is 

-<symbol>False</symbol>,

-all generated pointer events

-are reported with respect to grab_window and are reported only if

-selected by event_mask.

-If owner_events is 

-<symbol>True</symbol>

-and if a generated

-pointer event would normally be reported to this client, 

-it is reported as usual. 

-Otherwise, the event is reported with respect to the

-grab_window and is reported only if selected by event_mask.

-For either value of owner_events, unreported events are discarded.

-</para>

-<para>

-<!-- .LP -->

-If the pointer_mode is 

-<symbol>GrabModeAsync</symbol>,

-pointer event processing continues as usual.

-If the pointer is currently frozen by this client, 

-the processing of events for the pointer is resumed.

-If the pointer_mode is 

-<symbol>GrabModeSync</symbol>,

-the state of the pointer, as seen by

-client applications,

-appears to freeze, and the X server generates no further pointer events

-until the grabbing client calls 

-<function>XAllowEvents</function>

-or until the pointer grab is released.

-Actual pointer changes are not lost while the pointer is frozen;

-they are simply queued in the server for later processing.

-</para>

-<para>

-<!-- .LP -->

-If the keyboard_mode is 

-<symbol>GrabModeAsync</symbol>,

-keyboard event processing is unaffected by activation of the grab.

-If the keyboard_mode is 

-<symbol>GrabModeSync</symbol>,

-the state of the keyboard, as seen by

-client applications,

-appears to freeze, and the X server generates no further keyboard events

-until the grabbing client calls 

-<function>XAllowEvents</function>

-or until the pointer grab is released.

-Actual keyboard changes are not lost while the pointer is frozen;

-they are simply queued in the server for later processing.

-</para>

-<para>

-<!-- .LP -->

-If a cursor is specified, it is displayed regardless of what

-window the pointer is in.  

-If 

-<symbol>None</symbol>

-is specified,

-the normal cursor for that window is displayed

-when the pointer is in grab_window or one of its subwindows;

-otherwise, the cursor for grab_window is displayed.

-</para>

-<para>

-<!-- .LP -->

-If a confine_to window is specified,

-the pointer is restricted to stay contained in that window.

-The confine_to window need have no relationship to the grab_window.

-If the pointer is not initially in the confine_to window, 

-it is warped automatically to the closest edge 

-just before the grab activates and enter/leave events are generated as usual. 

-If the confine_to window is subsequently reconfigured, 

-the pointer is warped automatically, as necessary, 

-to keep it contained in the window.

-</para>

-<para>

-<!-- .LP -->

-The time argument allows you to avoid certain circumstances that come up

-if applications take a long time to respond or if there are long network

-delays.

-Consider a situation where you have two applications, both

-of which normally grab the pointer when clicked on.

-If both applications specify the timestamp from the event, 

-the second application may wake up faster and successfully grab the pointer

-before the first application. 

-The first application then will get an indication that the other application 

-grabbed the pointer before its request was processed.

-</para>

-<para>

-<!-- .LP -->

-<function>XGrabPointer</function>

-generates

-<symbol>EnterNotify</symbol>

-and

-<symbol>LeaveNotify</symbol>

-events.

-</para>

-<para>

-<!-- .LP -->

-Either if grab_window or confine_to window is not viewable

-or if the confine_to window lies completely outside the boundaries of the root

-window,

-<function>XGrabPointer</function>

-fails and returns

-<symbol>GrabNotViewable</symbol>.

-If the pointer is actively grabbed by some other client,

-it fails and returns

-<symbol>AlreadyGrabbed</symbol>.

-If the pointer is frozen by an active grab of another client,

-it fails and returns

-<symbol>GrabFrozen</symbol>.

-If the specified time is earlier than the last-pointer-grab time or later 

-than the current X server time, it fails and returns

-<symbol>GrabInvalidTime</symbol>.

-Otherwise, the last-pointer-grab time is set to the specified time

-(<symbol>CurrentTime</symbol>

-is replaced by the current X server time).

-</para>

-<para>

-<!-- .LP -->

-<function>XGrabPointer</function>

-can generate

-<errorname>BadCursor</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To ungrab the pointer, use

-<function>XUngrabPointer</function>.

-<indexterm><primary>Ungrabbing</primary><secondary>pointer</secondary></indexterm>

-<indexterm><primary>Pointer</primary><secondary>ungrabbing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XUngrabPointer</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUngrabPointer</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUngrabPointer</function>

-function releases the pointer and any queued events

-if this client has actively grabbed the pointer from

-<function>XGrabPointer</function>,

-<function>XGrabButton</function>,

-or from a normal button press.

-<function>XUngrabPointer</function>

-does not release the pointer if the specified

-time is earlier than the last-pointer-grab time or is later than the

-current X server time.

-It also generates 

-<symbol>EnterNotify</symbol>

-and 

-<symbol>LeaveNotify</symbol>

-events.

-The X server performs an 

-<systemitem>UngrabPointer</systemitem>

-request automatically if the event window or confine_to window 

-for an active pointer grab becomes not viewable

-or if window reconfiguration causes the confine_to window to lie completely

-outside the boundaries of the root window.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change an active pointer grab, use

-<function>XChangeActivePointerGrab</function>.

-<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>

-<indexterm ><primary>Changing</primary><secondary>pointer grab</secondary></indexterm>

-<indexterm significance="preferred"><primary>XChangeActivePointerGrab</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XChangeActivePointerGrab</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>

-  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which pointer events are reported to the client.

-The mask is the bitwise inclusive OR of the valid pointer event mask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>cursor</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the cursor that is to be displayed or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XChangeActivePointerGrab</function>

-function changes the specified dynamic parameters if the pointer is actively

-grabbed by the client and if the specified time is no earlier than the

-last-pointer-grab time and no later than the current X server time.

-This function has no effect on the passive parameters of an

-<function>XGrabButton</function>.

-The interpretation of event_mask and cursor is the same as described in

-<function>XGrabPointer</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XChangeActivePointerGrab</function>

-can generate

-<errorname>BadCursor</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To grab a pointer button, use

-<function>XGrabButton</function>.

-<indexterm><primary>Grabbing</primary><secondary>buttons</secondary></indexterm>

-<indexterm><primary>Button</primary><secondary>grabbing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGrabButton</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGrabButton</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedint<parameter> button</parameter></paramdef>

-  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>

-  <paramdef>Window<parameter> grab_window</parameter></paramdef>

-  <paramdef>Bool<parameter> owner_events</parameter></paramdef>

-  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>

-  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>

-  <paramdef>Window<parameter> confine_to</parameter></paramdef>

-  <paramdef>Cursor<parameter> cursor</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Bu grabbed -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>button</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the pointer button that is to be (Bu or

-<symbol>AnyButton</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modifiers</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the set of keymasks or

-<symbol>AnyModifier</symbol>.

-The mask is the bitwise inclusive OR of the valid keymask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>grab_window</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the grab window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>owner_events</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether the pointer 

-events are to be reported as usual or reported with respect to the grab window 

-if selected by the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which pointer events are reported to the client.

-The mask is the bitwise inclusive OR of the valid pointer event mask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pointer_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies further processing of pointer events.

-You can pass 

-<symbol>GrabModeSync</symbol>

-or

-<symbol>GrabModeAsync</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keyboard_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies further processing of keyboard events.

-You can pass 

-<symbol>GrabModeSync</symbol>

-or

-<symbol>GrabModeAsync</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>confine_to</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window to confine the pointer in or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>cursor</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the cursor that is to be displayed or

-<symbol>None</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGrabButton</function>

-function establishes a passive grab.

-In the future,

-the pointer is actively grabbed (as for

-<function>XGrabPointer</function>),

-the last-pointer-grab time is set to the time at which the button was pressed

-(as transmitted in the

-<symbol>ButtonPress</symbol>

-event), and the

-<symbol>ButtonPress</symbol>

-event is reported if all of the following conditions are true:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The pointer is not grabbed, and the specified button is logically pressed

-when the specified modifier keys are logically down,

-and no other buttons or modifier keys are logically down.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The grab_window contains the pointer.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The confine_to window (if any) is viewable.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A passive grab on the same button/key combination does not exist

-on any ancestor of grab_window.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The interpretation of the remaining arguments is as for

-<function>XGrabPointer</function>.

-The active grab is terminated automatically when the logical state of the

-pointer has all buttons released

-(independent of the state of the logical modifier keys).

-</para>

-<para>

-<!-- .LP -->

-Note that the logical state of a device (as seen by client applications)

-may lag the physical state if device event processing is frozen.

-</para>

-<para>

-<!-- .LP -->

-This request overrides all previous grabs by the same client on the same

-button/key combinations on the same window.

-A modifiers of 

-<symbol>AnyModifier</symbol>

-is equivalent to issuing the grab request for all

-possible modifier combinations (including the combination of no modifiers).  

-It is not required that all modifiers specified have currently assigned 

-KeyCodes.

-A button of 

-<symbol>AnyButton</symbol>

-is equivalent to

-issuing the request for all possible buttons.

-Otherwise, it is not required that the specified button currently be assigned

-to a physical button.

-</para>

-<para>

-<!-- .LP -->

-If some other client has already issued an

-<function>XGrabButton</function>

-with the same button/key combination on the same window, a

-<errorname>BadAccess</errorname>

-error results.

-When using 

-<symbol>AnyModifier</symbol>

-or 

-<symbol>AnyButton</symbol>,

-the request fails completely,

-and a

-<errorname>BadAccess</errorname>

-error results (no grabs are

-established) if there is a conflicting grab for any combination.

-<function>XGrabButton</function>

-has no effect on an active grab.

-</para>

-<para>

-<!-- .LP -->

-<function>XGrabButton</function>

-can generate

-<errorname>BadCursor</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To ungrab a pointer button, use

-<function>XUngrabButton</function>.

-<indexterm><primary>Ungrabbing</primary><secondary>buttons</secondary></indexterm>

-<indexterm><primary>Button</primary><secondary>ungrabbing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XUngrabButton</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUngrabButton</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedint<parameter> button</parameter></paramdef>

-  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>

-  <paramdef>Window<parameter> grab_window</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Bu released -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>button</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the pointer button that is to be (Bu or

-<symbol>AnyButton</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modifiers</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the set of keymasks or

-<symbol>AnyModifier</symbol>.

-The mask is the bitwise inclusive OR of the valid keymask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>grab_window</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the grab window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUngrabButton</function>

-function releases the passive button/key combination on the specified window if

-it was grabbed by this client.

-A modifiers of 

-<symbol>AnyModifier</symbol>

-is

-equivalent to issuing 

-the ungrab request for all possible modifier combinations, including 

-the combination of no modifiers.

-A button of 

-<symbol>AnyButton</symbol>

-is equivalent to issuing the

-request for all possible buttons.

-<function>XUngrabButton</function>

-has no effect on an active grab.

-</para>

-<para>

-<!-- .LP -->

-<function>XUngrabButton</function>

-can generate

-<errorname>BadValue</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Keyboard_Grabbing_">

-<title>Keyboard Grabbing </title>

-<!-- .XS -->

-<!-- (SN Keyboard Grabbing  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to grab or ungrab the keyboard

-as well as allow events.

-</para>

-<para>

-<!-- .LP -->

-For many functions in this section,

-you pass keymask bits.

-The valid keymask bits are:

-<symbol>ShiftMask</symbol>,

-<symbol>LockMask</symbol>,

-<symbol>ControlMask</symbol>,

-<symbol>Mod1Mask</symbol>,

-<symbol>Mod2Mask</symbol>,

-<symbol>Mod3Mask</symbol>,

-<symbol>Mod4Mask</symbol>,

-and

-<symbol>Mod5Mask</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To grab the keyboard, use

-<function>XGrabKeyboard</function>.

-<indexterm><primary>Keyboard</primary><secondary>grabbing</secondary></indexterm>

-<indexterm><primary>Grabbing</primary><secondary>keyboard</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGrabKeyboard</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XGrabKeyboard</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> grab_window</parameter></paramdef>

-  <paramdef>Bool<parameter> owner_events</parameter></paramdef>

-  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>grab_window</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the grab window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>owner_events</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether the keyboard events 

-are to be reported as usual.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pointer_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies further processing of pointer events.

-You can pass 

-<symbol>GrabModeSync</symbol>

-or

-<symbol>GrabModeAsync</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keyboard_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies further processing of keyboard events.

-You can pass 

-<symbol>GrabModeSync</symbol>

-or

-<symbol>GrabModeAsync</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGrabKeyboard</function>

-function actively grabs control of the keyboard and generates

-<symbol>FocusIn</symbol>

-and

-<symbol>FocusOut</symbol>

-events.

-Further key events are reported only to the

-grabbing client.

-<function>XGrabKeyboard</function>

-overrides any active keyboard grab by this client.

-If owner_events is 

-<symbol>False</symbol>,

-all generated key events are reported with

-respect to grab_window.  

-If owner_events is 

-<symbol>True</symbol>

-and if a generated

-key event would normally be reported to this client, it is reported

-normally; otherwise, the event is reported with respect to the

-grab_window.  

-Both 

-<symbol>KeyPress</symbol>

-and 

-<symbol>KeyRelease</symbol>

-events are always reported,

-independent of any event selection made by the client.

-</para>

-<para>

-<!-- .LP -->

-If the keyboard_mode argument is 

-<symbol>GrabModeAsync</symbol>,

-keyboard event processing continues

-as usual. 

-If the keyboard is currently frozen by this client, 

-then processing of keyboard events is resumed.

-If the keyboard_mode  argument is

-<symbol>GrabModeSync</symbol>,

-the state of the keyboard (as seen by client applications) appears to freeze,

-and the X server generates no further keyboard events until the

-grabbing client issues a releasing 

-<function>XAllowEvents</function>

-call or until the keyboard grab is released.

-Actual keyboard changes are not lost while the keyboard is frozen; 

-they are simply queued in the server for later processing.

-</para>

-<para>

-<!-- .LP -->

-If pointer_mode is 

-<symbol>GrabModeAsync</symbol>,

-pointer event processing is unaffected

-by activation of the grab.  

-If pointer_mode is 

-<symbol>GrabModeSync</symbol>,

-the state of the pointer (as seen by client applications) appears to freeze, 

-and the X server generates no further pointer events 

-until the grabbing client issues a releasing 

-<function>XAllowEvents</function>

-call or until the keyboard grab is released.

-Actual pointer changes are not lost while the pointer is frozen; 

-they are simply queued in the server for later processing.

-</para>

-<para>

-<!-- .LP -->

-If the keyboard is actively grabbed by some other client,

-<function>XGrabKeyboard</function>

-fails and returns

-<symbol>AlreadyGrabbed</symbol>.

-If grab_window is not viewable,

-it fails and returns

-<symbol>GrabNotViewable</symbol>.

-If the keyboard is frozen by an active grab of another client,

-it fails and returns

-<symbol>GrabFrozen</symbol>.

-If the specified time is earlier than the last-keyboard-grab time 

-or later than the current X server time,

-it fails and returns

-<symbol>GrabInvalidTime</symbol>.

-Otherwise, the last-keyboard-grab time is set to the specified time

-(<symbol>CurrentTime</symbol>

-is replaced by the current X server time).

-</para>

-<para>

-<!-- .LP -->

-<function>XGrabKeyboard</function>

-can generate

-<errorname>BadValue</errorname>

-and 

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To ungrab the keyboard, use

-<function>XUngrabKeyboard</function>.

-<indexterm><primary>Keyboard</primary><secondary>ungrabbing</secondary></indexterm>

-<indexterm><primary>Ungrabbing</primary><secondary>keyboard</secondary></indexterm>

-<indexterm significance="preferred"><primary>XUngrabKeyboard</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUngrabKeyboard</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUngrabKeyboard</function>

-function

-releases the keyboard and any queued events if this client has it actively grabbed from

-either

-<function>XGrabKeyboard</function>

-or

-<function>XGrabKey</function>.

-<function>XUngrabKeyboard</function>

-does not release the keyboard and any queued events

-if the specified time is earlier than

-the last-keyboard-grab time or is later than the current X server time.

-It also generates

-<symbol>FocusIn</symbol>

-and 

-<symbol>FocusOut</symbol>

-events.

-The X server automatically performs an 

-<systemitem>UngrabKeyboard</systemitem>

-request if the event window for an

-active keyboard grab becomes not viewable.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To passively grab a single key of the keyboard, use

-<function>XGrabKey</function>.

-<indexterm><primary>Key</primary><secondary>grabbing</secondary></indexterm>

-<indexterm><primary>Grabbing</primary><secondary>keys</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGrabKey</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGrabKey</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> keycode</parameter></paramdef>

-  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>

-  <paramdef>Window<parameter> grab_window</parameter></paramdef>

-  <paramdef>Bool<parameter> owner_events</parameter></paramdef>

-  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keycode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeyCode or

-<symbol>AnyKey</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modifiers</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the set of keymasks or

-<symbol>AnyModifier</symbol>.

-The mask is the bitwise inclusive OR of the valid keymask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>grab_window</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the grab window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>owner_events</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether the keyboard events 

-are to be reported as usual.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pointer_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies further processing of pointer events.

-You can pass 

-<symbol>GrabModeSync</symbol>

-or

-<symbol>GrabModeAsync</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keyboard_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies further processing of keyboard events.

-You can pass 

-<symbol>GrabModeSync</symbol>

-or

-<symbol>GrabModeAsync</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGrabKey</function>

-function establishes a passive grab on the keyboard.

-In the future,

-the keyboard is actively grabbed (as for

-<function>XGrabKeyboard</function>),

-the last-keyboard-grab time is set to the time at which the key was pressed

-(as transmitted in the

-<symbol>KeyPress</symbol>

-event), and the

-<symbol>KeyPress</symbol>

-event is reported if all of the following conditions are true:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The keyboard is not grabbed and the specified key

-(which can itself be a modifier key) is logically pressed

-when the specified modifier keys are logically down,

-and no other modifier keys are logically down.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Either the grab_window is an ancestor of (or is) the focus window,

-or the grab_window is a descendant of the focus window and contains the pointer.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A passive grab on the same key combination does not exist

-on any ancestor of grab_window.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The interpretation of the remaining arguments is as for 

-<function>XGrabKeyboard</function>.

-The active grab is terminated automatically when the logical state of the

-keyboard has the specified key released

-(independent of the logical state of the modifier keys).

-</para>

-<para>

-<!-- .LP -->

-Note that the logical state of a device (as seen by client applications)

-may lag the physical state if device event processing is frozen.

-</para>

-<para>

-<!-- .LP -->

-A modifiers argument of 

-<symbol>AnyModifier</symbol>

-is equivalent to issuing the request for all

-possible modifier combinations (including the combination of no

-modifiers).  

-It is not required that all modifiers specified have

-currently assigned KeyCodes.

-A keycode argument of 

-<symbol>AnyKey</symbol>

-is equivalent to issuing

-the request for all possible KeyCodes.

-Otherwise, the specified keycode must be in

-the range specified by min_keycode and max_keycode in the connection

-setup, 

-or a

-<errorname>BadValue</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-If some other client has issued a 

-<function>XGrabKey</function>

-with the same key combination on the same window, a 

-<errorname>BadAccess</errorname>

-error results.

-When using

-<symbol>AnyModifier</symbol>

-or 

-<symbol>AnyKey</symbol>,

-the request fails completely,

-and a

-<errorname>BadAccess</errorname>

-error results (no grabs are established) 

-if there is a conflicting grab for any combination.

-</para>

-<para>

-<!-- .LP -->

-<function>XGrabKey</function>

-can generate

-<errorname>BadAccess</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To ungrab a key, use

-<function>XUngrabKey</function>.

-<indexterm><primary>Key</primary><secondary>ungrabbing</secondary></indexterm>

-<indexterm><primary>Ungrabbing</primary><secondary>keys</secondary></indexterm>

-<indexterm significance="preferred"><primary>XUngrabKey</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUngrabKey</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> keycode</parameter></paramdef>

-  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>

-  <paramdef>Window<parameter> grab_window</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keycode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeyCode or

-<symbol>AnyKey</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modifiers</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the set of keymasks or

-<symbol>AnyModifier</symbol>.

-The mask is the bitwise inclusive OR of the valid keymask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>grab_window</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the grab window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUngrabKey</function>

-function releases the key combination on the specified window if it was grabbed

-by this client.

-It has no effect on an active grab.

-A modifiers of

-<symbol>AnyModifier</symbol>

-is equivalent to issuing

-the request for all possible modifier combinations

-(including the combination of no modifiers).

-A keycode argument of

-<symbol>AnyKey</symbol>

-is equivalent to issuing the request for all possible key codes.

-</para>

-<para>

-<!-- .LP -->

-<function>XUngrabKey</function>

-can generate

-<errorname>BadValue</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Resuming_Event_Processing">

-<title>Resuming Event Processing</title>

-<!-- .XS -->

-<!-- (SN Resuming Event Processing -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The previous sections discussed grab mechanisms with which processing

-of events by the server can be temporarily suspended.  This section

-describes the mechanism for resuming event processing.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allow further events to be processed when the device has been frozen, use

-<function>XAllowEvents</function>.

-<indexterm significance="preferred"><primary>XAllowEvents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAllowEvents</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> event_mode</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mode.

-You can pass 

-<symbol>AsyncPointer</symbol>,

-<symbol>SyncPointer</symbol>,

-<symbol>AsyncKeyboard</symbol>,

-<symbol>SyncKeyboard</symbol>,

-<symbol>ReplayPointer</symbol>,

-<symbol>ReplayKeyboard</symbol>,

-<symbol>AsyncBoth</symbol>,

-or

-<symbol>SyncBoth</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAllowEvents</function>

-function releases some queued events if the client has caused a device 

-to freeze.

-It has no effect if the specified time is earlier than the last-grab

-time of the most recent active grab for the client or if the specified time

-is later than the current X server time.

-Depending on the event_mode argument, the following occurs:

-</para>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>AsyncPointer</symbol></entry>

-      <entry>If the pointer is frozen by the client,

-      pointer event processing continues as usual.

-      If the pointer is frozen twice by the client on behalf of two separate grabs,

-      <symbol>AsyncPointer</symbol>

-      thaws for both.

-      <symbol>AsyncPointer</symbol>

-      has no effect if the pointer is not frozen by the client,

-      but the pointer need not be grabbed by the client.</entry>

-    </row>

-    <row>

-      <entry><symbol>SyncPointer</symbol></entry>

-      <entry>If the pointer is frozen and actively grabbed by the client,

-      pointer event processing continues as usual until the next

-      <symbol>ButtonPress</symbol>

-      or

-      <symbol>ButtonRelease</symbol>

-      event is reported to the client.

-      At this time,

-      the pointer again appears to freeze.

-      However, if the reported event causes the pointer grab to be released,

-      the pointer does not freeze.

-      <symbol>SyncPointer</symbol>

-      has no effect if the pointer is not frozen by the client

-      or if the pointer is not grabbed by the client.</entry>

-    </row>

-    <row>

-      <entry><symbol>ReplayPointer</symbol></entry>

-      <entry>If the pointer is actively grabbed by the client and is frozen as the result of

-      an event having been sent to the client (either from the activation of an

-      <function>XGrabButton</function>

-      or from a previous

-      <function>XAllowEvents</function>

-      with mode

-      <symbol>SyncPointer</symbol>

-      but not from an 

-      <function>XGrabPointer</function>),

-      the pointer grab is released and that event is completely reprocessed.

-      This time, however, the function ignores any passive grabs at or above 

-      (toward the root of) the grab_window of the grab just released.

-      The request has no effect if the pointer is not grabbed by the client

-      or if the pointer is not frozen as the result of an event.</entry>

-    </row>

-    <row>

-      <entry><symbol>AsyncKeyboard</symbol></entry>

-      <entry>If the keyboard is frozen by the client,

-      keyboard event processing continues as usual.

-      If the keyboard is frozen twice by the client on behalf of two separate grabs,

-      <symbol>AsyncKeyboard</symbol>

-      thaws for both.

-      <symbol>AsyncKeyboard</symbol>

-      has no effect if the keyboard is not frozen by the client,

-      but the keyboard need not be grabbed by the client.</entry>

-    </row>

-    <row>

-      <entry><symbol>SyncKeyboard</symbol></entry>

-      <entry>If the keyboard is frozen and actively grabbed by the client,

-      keyboard event processing continues as usual until the next

-      <symbol>KeyPress</symbol>

-      or

-      <symbol>KeyRelease</symbol>

-      event is reported to the client.

-      At this time,

-      the keyboard again appears to freeze.

-      However, if the reported event causes the keyboard grab to be released,

-      the keyboard does not freeze.

-      <symbol>SyncKeyboard</symbol>

-      has no effect if the keyboard is not frozen by the client

-      or if the keyboard is not grabbed by the client.</entry>

-    </row>

-    <row>

-      <entry><symbol>ReplayKeyboard</symbol></entry>

-      <entry>If the keyboard is actively grabbed by the client and is frozen

-      as the result of an event having been sent to the client (either from the

-      activation of an

-      <function>XGrabKey</function>

-      or from a previous

-      <function>XAllowEvents</function>

-      with mode

-      <symbol>SyncKeyboard</symbol>

-      but not from an 

-      <function>XGrabKeyboard</function>),

-      the keyboard grab is released and that event is completely reprocessed.

-      This time, however, the function ignores any passive grabs at or above

-      (toward the root of)

-      the grab_window of the grab just released.

-      The request has no effect if the keyboard is not grabbed by the client

-      or if the keyboard is not frozen as the result of an event.</entry>

-    </row>

-    <row>

-      <entry><symbol>SyncBoth</symbol></entry>

-      <entry>If both pointer and keyboard are frozen by the client,

-      event processing for both devices continues as usual until the next

-      <symbol>ButtonPress</symbol>,

-      <symbol>ButtonRelease</symbol>,

-      <symbol>KeyPress</symbol>,

-      or 

-      <symbol>KeyRelease</symbol>

-      event is reported to the client for a grabbed device 

-      (button event for the pointer, key event for the keyboard), 

-      at which time the devices again appear to freeze.  

-      However, if the reported event causes the grab to be released,

-      then the devices do not freeze (but if the other device is still

-      grabbed, then a subsequent event for it will still cause both devices

-      to freeze).  

-      <symbol>SyncBoth</symbol>

-      has no effect unless both pointer and keyboard

-      are frozen by the client.

-      If the pointer or keyboard is frozen twice

-      by the client on behalf of two separate grabs, 

-      <symbol>SyncBoth</symbol>

-      thaws for both (but a subsequent freeze for 

-      <symbol>SyncBoth</symbol>

-      will only freeze each device once).</entry>

-    </row>

-    <row>

-      <entry><symbol>AsyncBoth</symbol></entry>

-      <entry>If the pointer and the keyboard are frozen by the

-      client, event processing for both devices continues as usual.

-      If a device is frozen twice by the client on behalf of two separate grabs,

-      <symbol>AsyncBoth</symbol>

-      thaws for both.

-      <symbol>AsyncBoth</symbol>

-      has no effect unless both

-      pointer and keyboard are frozen by the client.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-<symbol>AsyncPointer</symbol>,

-<symbol>SyncPointer</symbol>,

-and 

-<symbol>ReplayPointer</symbol>

-have no effect on the

-processing of keyboard events.

-<symbol>AsyncKeyboard</symbol>,

-<symbol>SyncKeyboard</symbol>,

-and 

-<symbol>ReplayKeyboard</symbol>

-have no effect on the

-processing of pointer events.

-It is possible for both a pointer grab and a keyboard grab (by the same 

-or different clients) to be active simultaneously.

-If a device is frozen on behalf of either grab,

-no event processing is performed for the device.

-It is possible for a single device to be frozen because of both grabs.

-In this case,

-the freeze must be released on behalf of both grabs before events can 

-again be processed.

-If a device is frozen twice by a single client,

-then a single

-<function>XAllowEvents</function>

-releases both.

-</para>

-<para>

-<!-- .LP -->

-<function>XAllowEvents</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Moving_the_Pointer">

-<title>Moving the Pointer</title>

-<!-- .XS -->

-<!-- (SN Moving the Pointer -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Although movement of the pointer normally should be left to the

-control of the end user, sometimes it is necessary to move the

-pointer to a new position under program control.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To move the pointer to an arbitrary point in a window, use

-<function>XWarpPointer</function>.

-<indexterm significance="preferred"><primary>XWarpPointer</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XWarpPointer</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>

-  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

-  <paramdef>unsignedintsrc_width,<parameter> src_height</parameter></paramdef>

-  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the source window or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the destination window or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify a rectangle in the source window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates within the destination window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If dest_w is

-<symbol>None</symbol>,

-<function>XWarpPointer</function>

-moves the pointer by the offsets (dest_x, dest_y) relative to the current

-position of the pointer.

-If dest_w is a window,

-<function>XWarpPointer</function>

-moves the pointer to the offsets (dest_x, dest_y) relative to the origin of

-dest_w.

-However, if src_w is a window,

-the move only takes place if the window src_w contains the pointer 

-and if the specified rectangle of src_w contains the pointer.

-</para>

-<para>

-<!-- .LP -->

-The src_x and src_y coordinates are relative to the origin of src_w.

-If src_height is zero,

-it is replaced with the current height of src_w minus src_y.

-If src_width is zero,

-it is replaced with the current width of src_w minus src_x.

-</para>

-<para>

-<!-- .LP -->

-There is seldom any reason for calling this function. 

-The pointer should normally be left to the user.

-If you do use this function, however, it generates events just as if the user

-had instantaneously moved the pointer from one position to another.

-Note that you cannot use

-<function>XWarpPointer</function>

-to move the pointer outside the confine_to window of an active pointer grab.

-An attempt to do so will only move the pointer as far as the closest edge of the

-confine_to window. 

-</para>

-<para>

-<!-- .LP -->

-<function>XWarpPointer</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Controlling_Input_Focus">

-<title>Controlling Input Focus</title>

-<!-- .XS -->

-<!-- (SN Controlling Input Focus  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and get the input focus.

-The input focus is a shared resource, and cooperation among clients is

-required for correct interaction.  See the

-<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis> 

-for input focus policy.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the input focus, use

-<function>XSetInputFocus</function>.

-<indexterm significance="preferred"><primary>XSetInputFocus</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetInputFocus</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> focus</parameter></paramdef>

-  <paramdef>int<parameter> revert_to</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>focus</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window,

-<symbol>PointerRoot</symbol>,

-or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>revert_to</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies where the input focus reverts to if the window becomes not

-viewable.

-You can pass 

-<symbol>RevertToParent</symbol>,

-<symbol>RevertToPointerRoot</symbol>,

-or 

-<symbol>RevertToNone</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetInputFocus</function>

-function changes the input focus and the last-focus-change time.

-It has no effect if the specified time is earlier than the current

-last-focus-change time or is later than the current X server time.

-Otherwise, the last-focus-change time is set to the specified time

-(<symbol>CurrentTime</symbol>

-is replaced by the current X server time).

-<function>XSetInputFocus</function>

-causes the X server to generate

-<symbol>FocusIn</symbol>

-and 

-<symbol>FocusOut</symbol>

-events.

-</para>

-<para>

-<!-- .LP -->

-Depending on the focus argument,

-the following occurs: 

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If focus is

-<symbol>None</symbol>,

-all keyboard events are discarded until a new focus window is set,

-and the revert_to argument is ignored.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If focus is a window, 

-it becomes the keyboard's focus window.

-If a generated keyboard event would normally be reported to this window

-or one of its inferiors, the event is reported as usual. 

-Otherwise, the event is reported relative to the focus window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If focus is

-<symbol>PointerRoot</symbol>,

-the focus window is dynamically taken to be the root window of whatever screen 

-the pointer is on at each keyboard event.  

-In this case, the revert_to argument is ignored.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The specified focus window must be viewable at the time 

-<function>XSetInputFocus</function>

-is called,

-or a

-<errorname>BadMatch</errorname>

-error results.

-If the focus window later becomes not viewable, 

-the X server

-evaluates the revert_to argument to determine the new focus window as follows: 

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If revert_to is

-<symbol>RevertToParent</symbol>,

-the focus reverts to the parent (or the closest viewable ancestor), 

-and the new revert_to value is taken to be

-<symbol>RevertToNone</symbol>.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If revert_to is

-<symbol>RevertToPointerRoot</symbol>

-or 

-<symbol>RevertToNone</symbol>,

-the focus reverts to

-<symbol>PointerRoot</symbol>

-or

-<symbol>None</symbol>,

-respectively.

-When the focus reverts,

-the X server generates

-<symbol>FocusIn</symbol>

-and

-<symbol>FocusOut</symbol>

-events, but the last-focus-change time is not affected.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-<function>XSetInputFocus</function>

-can generate

-<errorname>BadMatch</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the current input focus, use

-<function>XGetInputFocus</function>.

-<indexterm significance="preferred"><primary>XGetInputFocus</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGetInputFocus</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> *focus_return</parameter></paramdef>

-  <paramdef>int<parameter> *revert_to_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>focus_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the focus window,

-<symbol>PointerRoot</symbol>,

-or 

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>revert_to_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the current focus state

-(<symbol>RevertToParent</symbol>,

-<symbol>RevertToPointerRoot</symbol>,

-or 

-<symbol>RevertToNone</symbol>).

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetInputFocus</function>

-function returns the focus window and the current focus state.

-</para>

-</sect1>

-<sect1 id="Manipulating_the_Keyboard_and_Pointer_Settings">

-<title>Manipulating the Keyboard and Pointer Settings</title>

-<!-- .XS -->

-<!-- (SN Manipulating the Keyboard and Pointer Settings  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to

-change the keyboard control, obtain a list of the auto-repeat keys,

-turn keyboard auto-repeat on or off, ring the bell, 

-set or obtain the pointer button or keyboard mapping, 

-and obtain a bit vector for the keyboard.

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>Keyboard</primary><secondary>bell volume</secondary></indexterm>

-<indexterm><primary>Keyboard</primary><secondary>keyclick volume</secondary></indexterm>

-<indexterm><primary>Keyboard</primary><secondary>bit vector</secondary></indexterm>

-<indexterm><primary>Mouse</primary><secondary>programming</secondary></indexterm>

-This section discusses 

-the user-preference options of bell, key click,

-pointer behavior, and so on.

-The default values for many of these options are server dependent.

-Not all implementations will actually be able to control all of these

-parameters.

-</para>

-<para>

-<!-- .LP -->

-The

-<function>XChangeKeyboardControl</function>

-function changes control of a keyboard and operates on a

-<structname>XKeyboardControl</structname>

-structure:

-<!-- .sM -->

-</para>

-

-<literallayout class="monospaced">

-/* Mask bits for ChangeKeyboardControl */

-

-

-#define     KBBellPercent           (1L&lt;&lt;0)

-#define     KBBellPitch             (1L&lt;&lt;1)

-#define     KBBellDuration          (1L&lt;&lt;2)

-#define     KBLed                   (1L&lt;&lt;3)

-#define     KBLedMode               (1L&lt;&lt;4)

-#define     KBKey                   (1L&lt;&lt;5)

-#define     KBAutoRepeatMode        (1L&lt;&lt;6)

-

-

-/* Values */

-

-typedef struct {

-int key_click_percent;

-int bell_percent;

-int bell_pitch;

-int bell_duration;

-int led;

-int led_mode;                /* LedModeOn, LedModeOff */

-int key;

-int auto_repeat_mode;        /* AutoRepeatModeOff, AutoRepeatModeOn,

-                                AutoRepeatModeDefault */

-} XKeyboardControl;

-

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The key_click_percent member sets the volume for key clicks between 0 (off) 

-and 100 (loud) inclusive, if possible.  

-A setting of -1 restores the default.

-Other negative values generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-The bell_percent sets the base volume for the bell between 0 (off) and 100

-(loud) inclusive, if possible.  

-A setting of -1 restores the default.

-Other negative values generate a

-<errorname>BadValue</errorname>

-error.

-The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible.

-A setting of -1 restores the default.

-Other negative values generate a

-<errorname>BadValue</errorname>

-error.

-The bell_duration member sets the duration of the

-bell specified in milliseconds, if possible.  

-A setting of -1 restores the default.

-Other negative values generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-If both the led_mode and led members are specified,

-the state of that <acronym>LED</acronym> is changed, if possible.  

-The led_mode member can be set to

-<symbol>LedModeOn</symbol>

-or

-<symbol>LedModeOff</symbol>.

-If only led_mode is specified, the state of

-all LEDs are changed, if possible.  

-At most 32 LEDs numbered from one are supported. 

-No standard interpretation of LEDs is defined.

-If led is specified without led_mode, a

-<errorname>BadMatch</errorname>

-error results. 

-</para>

-<para>

-<!-- .LP -->

-If both the auto_repeat_mode and key members are specified, 

-the auto_repeat_mode of that key is changed (according to

-<symbol>AutoRepeatModeOn</symbol>,

-<symbol>AutoRepeatModeOff</symbol>,

-or

-<symbol>AutoRepeatModeDefault</symbol>),

-if possible.

-If only auto_repeat_mode is

-specified, the global auto_repeat_mode for the entire keyboard is

-changed, if possible, and does not affect the per-key settings.

-If a key is specified without an auto_repeat_mode, a

-<errorname>BadMatch</errorname>

-error results.

-Each key has an individual mode of whether or not it should auto-repeat

-and a default setting for the mode.

-In addition,

-there is a global mode of whether auto-repeat should be enabled or not

-and a default setting for that mode.

-When global mode is

-<symbol>AutoRepeatModeOn</symbol>,

-keys should obey their individual auto-repeat modes.

-When global mode is

-<symbol>AutoRepeatModeOff</symbol>,

-no keys should auto-repeat.

-An auto-repeating key generates alternating

-<symbol>KeyPress</symbol>

-and

-<symbol>KeyRelease</symbol>

-events.

-When a key is used as a modifier,

-it is desirable for the key not to auto-repeat,

-regardless of its auto-repeat setting.

-</para>

-<para>

-<!-- .LP -->

-A bell generator connected with the console but not directly on a

-keyboard is treated as if it were part of the keyboard.

-The order in which controls are verified and altered is server-dependent.

-If an error is generated, a subset of the controls may have been altered.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-<indexterm significance="preferred"><primary>XChangeKeyboardControl</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XChangeKeyboardControl</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> value_mask</parameter></paramdef>

-  <paramdef>XKeyboardControl<parameter> *values</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which controls to change.

-This mask is the bitwise inclusive OR of the valid control mask bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>values</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies one value for each bit set to 1 in the mask.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XChangeKeyboardControl</function>

-function controls the keyboard characteristics defined by the

-<structname>XKeyboardControl</structname>

-structure.

-The value_mask argument specifies which values are to be changed.

-</para>

-<para>

-<!-- .LP -->

-<function>XChangeKeyboardControl</function>

-can generate

-<errorname>BadMatch</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the current control values for the keyboard, use

-<function>XGetKeyboardControl</function>.

-<indexterm significance="preferred"><primary>XGetKeyboardControl</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGetKeyboardControl</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XKeyboardState<parameter> *values_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>values_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the current keyboard controls in the specified

-<structname>XKeyboardState</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetKeyboardControl</function>

-function returns the current control values for the keyboard to the

-<structname>XKeyboardState</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>XGetKeyboardControl</primary></indexterm>

-<indexterm significance="preferred"><primary>XKeyboardState</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i  -->

-<!-- .ta .5i -->

-typedef struct {

-	int key_click_percent;

-	int bell_percent;

-	unsigned int bell_pitch, bell_duration;

-	unsigned long led_mask;

-	int global_auto_repeat;

-	char auto_repeats[32];

-} XKeyboardState;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-For the LEDs, 

-the least significant bit of led_mask corresponds to <acronym>LED</acronym> one,

-and each bit set to 1 in led_mask indicates an <acronym>LED</acronym> that is lit.

-The global_auto_repeat member can be set to

-<symbol>AutoRepeatModeOn</symbol>

-or

-<symbol>AutoRepeatModeOff</symbol>.

-The auto_repeats member is a bit vector.

-Each bit set to 1 indicates that auto-repeat is enabled 

-for the corresponding key.

-The vector is represented as 32 bytes.  

-Byte N (from 0) contains the bits for keys 8N to 8N + 7

-with the least significant bit in the byte representing key 8N.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To turn on keyboard auto-repeat, use

-<function>XAutoRepeatOn</function>.

-<indexterm significance="preferred"><primary>XAutoRepeatOn</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAutoRepeatOn</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAutoRepeatOn</function>

-function turns on auto-repeat for the keyboard on the specified display.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To turn off keyboard auto-repeat, use

-<function>XAutoRepeatOff</function>.

-<indexterm significance="preferred"><primary>XAutoRepeatOff</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAutoRepeatOff</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAutoRepeatOff</function>

-function turns off auto-repeat for the keyboard on the specified display.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To ring the bell, use

-<function>XBell</function>.

-<indexterm significance="preferred"><primary>XBell</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XBell</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> percent</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>percent</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the volume for the bell,

-which can range from -100 to 100 inclusive. 

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XBell</function>

-function rings the bell on the keyboard on the specified display, if possible.

-The specified volume is relative to the base volume for the keyboard.

-If the value for the percent argument is not in the range -100 to 100

-inclusive, a

-<errorname>BadValue</errorname>

-error results.

-The volume at which the bell rings

-when the percent argument is nonnegative is:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-base - [(base * percent) / 100] + percent

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The volume at which the bell rings

-when the percent argument is negative is:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-base + [(base * percent) / 100]

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-To change the base volume of the bell, use

-<function>XChangeKeyboardControl</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XBell</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a bit vector that describes the state of the keyboard, use

-<function>XQueryKeymap</function>.

-<indexterm significance="preferred"><primary>XQueryKeymap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XQueryKeymap</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> keys_return[32]</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keys_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns an array of bytes that identifies which keys are pressed down.

-Each bit represents one key of the keyboard.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryKeymap</function>

-function returns a bit vector for the logical state of the keyboard, 

-where each bit set to 1 indicates that the corresponding key is currently 

-pressed down.

-The vector is represented as 32 bytes.

-Byte N (from 0) contains the bits for keys 8N to 8N + 7 

-with the least significant bit in the byte representing key 8N.

-</para>

-<para>

-<!-- .LP -->

-Note that the logical state of a device (as seen by client applications)

-may lag the physical state if device event processing is frozen.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the mapping of the pointer buttons, use

-<function>XSetPointerMapping</function>.

-<indexterm significance="preferred"><primary>XSetPointerMapping</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XSetPointerMapping</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedchar<parameter> map[]</parameter></paramdef>

-  <paramdef>int<parameter> nmap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>map</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the mapping list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of items in the mapping list.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetPointerMapping</function>

-function sets the mapping of the pointer.

-If it succeeds, the X server generates a

-<symbol>MappingNotify</symbol>

-event, and

-<function>XSetPointerMapping</function>

-returns

-<symbol>MappingSuccess</symbol>.

-Element map[i] defines the logical button number for the physical button

-i+1.

-The length of the list must be the same as

-<function>XGetPointerMapping</function>

-would return,

-or a

-<errorname>BadValue</errorname>

-error results.

-A zero element disables a button, and elements are not restricted in

-value by the number of physical buttons.

-However, no two elements can have the same nonzero value,

-or a

-<errorname>BadValue</errorname>

-error results.

-If any of the buttons to be altered are logically in the down state,

-<function>XSetPointerMapping</function>

-returns

-<symbol>MappingBusy</symbol>,

-and the mapping is not changed.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetPointerMapping</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the pointer mapping, use

-<function>XGetPointerMapping</function>.

-<indexterm significance="preferred"><primary>XGetPointerMapping</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XGetPointerMapping</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>unsignedchar<parameter> map_return[]</parameter></paramdef>

-  <paramdef>int<parameter> nmap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>map_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the mapping list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of items in the mapping list.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetPointerMapping</function>

-function returns the current mapping of the pointer.

-Pointer buttons are numbered starting from one.

-<function>XGetPointerMapping</function>

-returns the number of physical buttons actually on the pointer.

-The nominal mapping for a pointer is map[i]=i+1.

-The nmap argument specifies the length of the array where the pointer

-mapping is returned, and only the first nmap elements are returned 

-in map_return.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To control the pointer's interactive feel, use

-<function>XChangePointerControl</function>.

-<indexterm significance="preferred"><primary>XChangePointerControl</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XChangePointerControl</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Booldo_accel,<parameter> do_threshold</parameter></paramdef>

-  <paramdef>intaccel_numerator,<parameter> accel_denominator</parameter></paramdef>

-  <paramdef>int<parameter> threshold</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>do_accel</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that controls whether the values for 

-the accel_numerator or accel_denominator are used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>do_threshold</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that controls whether the value for the 

-threshold is used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>accel_numerator</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the numerator for the acceleration multiplier.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>accel_denominator</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the denominator for the acceleration multiplier.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>threshold</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the acceleration threshold.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XChangePointerControl</function>

-function defines how the pointing device moves.

-The acceleration, expressed as a fraction, is a

-multiplier for movement. 

-For example,

-specifying 3/1 means the pointer moves three times as fast as normal.

-The fraction may be rounded arbitrarily by the X server.  

-Acceleration

-only takes effect if the pointer moves more than threshold pixels at

-once and only applies to the amount beyond the value in the threshold argument.

-Setting a value to -1 restores the default.

-The values of the do_accel and do_threshold arguments must be 

-<symbol>True</symbol>

-for the pointer values to be set,

-or the parameters are unchanged.

-Negative values (other than -1) generate a

-<errorname>BadValue</errorname>

-error, as does a zero value

-for the accel_denominator argument.

-</para>

-<para>

-<!-- .LP -->

-<function>XChangePointerControl</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the current pointer parameters, use

-<function>XGetPointerControl</function>.

-<indexterm significance="preferred"><primary>XGetPointerControl</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGetPointerControl</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int*accel_numerator_return,<parameter> *accel_denominator_return</parameter></paramdef>

-  <paramdef>int<parameter> *threshold_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>accel_numerator_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the numerator for the acceleration multiplier.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>accel_denominator_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the denominator for the acceleration multiplier.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>threshold_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the acceleration threshold.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetPointerControl</function>

-function returns the pointer's current acceleration multiplier

-and acceleration threshold.

-</para>

-</sect1>

-<sect1 id="Manipulating_the_Keyboard_Encoding">

-<title>Manipulating the Keyboard Encoding</title>

-<!-- .XS -->

-<!-- (SN Manipulating the Keyboard Encoding  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A KeyCode represents a physical (or logical) key.  

-KeyCodes lie in the inclusive range [8,255].  

-A KeyCode value carries no intrinsic information,

-although server implementors may attempt to encode geometry 

-(for example, matrix) information in some fashion so that it can

-be interpreted in a server-dependent fashion.

-The mapping between keys and KeyCodes cannot be changed.

-</para>

-<para>

-<!-- .LP -->

-A KeySym is an encoding of a symbol on the cap of a key.  

-The set of defined KeySyms includes the ISO Latin character sets (1-4), 

-Katakana, Arabic, Cyrillic, Greek, Technical,

-Special, Publishing, APL, Hebrew, Thai, Korean

-and a miscellany of keys found

-on keyboards (Return, Help, Tab, and so on).  

-To the extent possible, these sets are derived from international

-standards. 

-In areas where no standards exist,

-some of these sets are derived from Digital Equipment Corporation standards.

-The list of defined symbols can be found in

-<filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename></secondary></indexterm>

-Unfortunately, some C preprocessors have

-limits on the number of defined symbols.

-If you must use KeySyms not

-in the Latin 1-4, Greek, and miscellaneous classes,

-you may have to define a symbol for those sets.

-Most applications usually only include 

-<filename class="headerfile">&lt;X11/keysym.h&gt;</filename>,

-<indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/keysym.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/keysym.h&gt;</filename></secondary></indexterm>

-which defines symbols for ISO Latin 1-4, Greek, and miscellaneous.

-</para>

-<para>

-<!-- .LP -->

-A list of KeySyms is associated with each KeyCode.

-The list is intended to convey the set of symbols on the corresponding key.

-If the list (ignoring trailing

-<symbol>NoSymbol</symbol>

-entries) is 

-a single KeySym ``<emphasis remap='I'>K</emphasis>'',

-then the list is treated as if it were the list 

-``<emphasis remap='I'>K</emphasis> NoSymbol <emphasis remap='I'>K</emphasis> NoSymbol''.

-If the list (ignoring trailing

-<symbol>NoSymbol</symbol>

-entries) is a pair of KeySyms ``<emphasis remap='I'>K1 K2</emphasis>'',

-then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K1 K2</emphasis>''.

-If the list (ignoring trailing

-<symbol>NoSymbol</symbol>

-entries) is a triple of KeySyms ``<emphasis remap='I'>K1 K2 K3</emphasis>'',

-then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K3</emphasis> NoSymbol''.

-When an explicit ``void'' element is desired in the list,

-the value

-<symbol>VoidSymbol</symbol>

-can be used.

-</para>

-<para>

-<!-- .LP -->

-The first four elements of the list are split into two groups of KeySyms.

-Group 1 contains the first and second KeySyms;

-Group 2 contains the third and fourth KeySyms.

-Within each group,

-if the second element of the group is

-<symbol>NoSymbol</symbol>,

-then the group should be treated as if the second element were 

-the same as the first element,

-except when the first element is an alphabetic KeySym ``<emphasis remap='I'>K</emphasis>'' 

-for which both lowercase and uppercase forms are defined.

-In that case,

-the group should be treated as if the first element were 

-the lowercase form of ``<emphasis remap='I'>K</emphasis>'' and the second element were 

-the uppercase form of ``<emphasis remap='I'>K</emphasis>''.

-</para>

-<para>

-<!-- .LP -->

-The standard rules for obtaining a KeySym from a

-<symbol>KeyPress</symbol>

-event make use of only the Group 1 and Group 2 KeySyms;

-no interpretation of other KeySyms in the list is given.

-Which group to use is determined by the modifier state.

-Switching between groups is controlled by the KeySym named MODE SWITCH,

-by attaching that KeySym to some KeyCode and attaching 

-that KeyCode to any one of the modifiers

-<symbol>Mod1</symbol>

-through

-<symbol>Mod5</symbol>.

-This modifier is called the <emphasis remap='I'>group modifier</emphasis>.

-For any KeyCode,

-Group 1 is used when the group modifier is off,

-and Group 2 is used when the group modifier is on.

-</para>

-<para>

-<!-- .LP -->

-The

-<symbol>Lock</symbol>

-modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock

-is attached to some KeyCode and that KeyCode is attached to the

-<symbol>Lock</symbol>

-modifier.  The

-<symbol>Lock</symbol>

-modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock

-is attached to some KeyCode and that KeyCode is attached to the

-<symbol>Lock</symbol>

-modifier.  If the

-<symbol>Lock</symbol>

-modifier could be interpreted as both

-CapsLock and ShiftLock, the CapsLock interpretation is used.

-</para>

-<para>

-<!-- .LP -->

-The operation of keypad keys is controlled by the KeySym named XK_Num_Lock,

-by attaching that KeySym to some KeyCode and attaching that KeyCode to any

-one of the modifiers

-<symbol>Mod1</symbol>

-through

-<symbol>Mod5</symbol>.

-This modifier is called the

-<emphasis remap='I'>numlock modifier</emphasis>.  The standard KeySyms with the prefix ``XK_KP_''

-in their

-name are called keypad KeySyms; these are KeySyms with numeric value in

-the hexadecimal range 0xFF80 to 0xFFBD inclusive.  In addition,

-vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF

-are also keypad KeySyms.

-</para>

-<para>

-<!-- .LP -->

-Within a group, the choice of KeySym is determined by applying the first

-rule that is satisfied from the following list:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The numlock modifier is on and the second KeySym is a keypad KeySym.  In

-this case, if the

-<symbol>Shift</symbol>

-modifier is on, or if the

-<symbol>Lock</symbol>

-modifier is on and

-is interpreted as ShiftLock, then the first KeySym is used, otherwise the

-second KeySym is used.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The

-<symbol>Shift</symbol>

-and

-<symbol>Lock</symbol>

-modifiers are both off.  In this case, the first

-KeySym is used.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The

-<symbol>Shift</symbol>

-modifier is off, and the

-<symbol>Lock</symbol>

-modifier is on and is

-interpreted as CapsLock.  In this case, the first KeySym is used, but if

-that KeySym is lowercase alphabetic, then the corresponding uppercase

-KeySym is used instead.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The

-<symbol>Shift</symbol>

-modifier is on, and the

-<symbol>Lock</symbol>

-modifier is on and is interpreted

-as CapsLock.  In this case, the second KeySym is used, but if that KeySym

-is lowercase alphabetic, then the corresponding uppercase KeySym is used

-instead.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The

-<symbol>Shift</symbol>

-modifier is on, or the

-<symbol>Lock</symbol>

-modifier is on and is interpreted

-as ShiftLock, or both.  In this case, the second KeySym is used.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-No spatial geometry of the symbols on the key is defined by

-their order in the KeySym list, 

-although a geometry might be defined on a

-server-specific basis.

-The X server does not use the mapping between KeyCodes and KeySyms.

-Rather, it merely stores it for reading and writing by clients.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the legal KeyCodes for a display, use

-<function>XDisplayKeycodes</function>.

-<indexterm significance="preferred"><primary>XDisplayKeycodes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDisplayKeycodes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int*min_keycodes_return,<parameter> *max_keycodes_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>min_keycodes_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the minimum number of KeyCodes.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>max_keycodes_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the maximum number of KeyCodes.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDisplayKeycodes</function>

-function returns the min-keycodes and max-keycodes supported by the

-specified display.

-The minimum number of KeyCodes returned is never less than 8,

-and the maximum number of KeyCodes returned is never greater than 255.

-Not all KeyCodes in this range are required to have corresponding keys.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the symbols for the specified KeyCodes, use

-<function>XGetKeyboardMapping</function>.

-<indexterm significance="preferred"><primary>XGetKeyboardMapping</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>KeySym *<function>XGetKeyboardMapping</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>KeyCode<parameter> first_keycode</parameter></paramdef>

-  <paramdef>int<parameter> keycode_count</parameter></paramdef>

-  <paramdef>int<parameter> *keysyms_per_keycode_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Kc returned -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>first_keycode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the first KeyCode that is to be (Kc.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keycode_count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of KeyCodes that are to be returned.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysyms_per_keycode_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of KeySyms per KeyCode.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetKeyboardMapping</function>

-function returns the symbols for the specified number of KeyCodes

-starting with first_keycode.

-The value specified in first_keycode must be greater than 

-or equal to min_keycode as returned by

-<function>XDisplayKeycodes</function>,

-or a

-<errorname>BadValue</errorname>

-error results.

-In addition, the following expression must be less than or equal 

-to max_keycode as returned by

-<function>XDisplayKeycodes</function>:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-first_keycode + keycode_count - 1

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-If this is not the case, a 

-<errorname>BadValue</errorname>

-error results. 

-The number of elements in the KeySyms list is:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-keycode_count * keysyms_per_keycode_return

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-KeySym number N, counting from zero, for KeyCode K has the following index

-in the list, counting from zero: 

-<literallayout class="monospaced">

-(K - first_code) * keysyms_per_code_return + N

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The X server arbitrarily chooses the keysyms_per_keycode_return value 

-to be large enough to report all requested symbols. 

-A special KeySym value of 

-<symbol>NoSymbol</symbol>

-is used to fill in unused elements for

-individual KeyCodes.

-To free the storage returned by 

-<function>XGetKeyboardMapping</function>,

-use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetKeyboardMapping</function>

-can generate a

-<errorname>BadValue</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change the keyboard mapping, use

-<function>XChangeKeyboardMapping</function>.

-<indexterm significance="preferred"><primary>XChangeKeyboardMapping</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XChangeKeyboardMapping</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> first_keycode</parameter></paramdef>

-  <paramdef>int<parameter> keysyms_per_keycode</parameter></paramdef>

-  <paramdef>KeySym<parameter> *keysyms</parameter></paramdef>

-  <paramdef>int<parameter> num_codes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Kc changed -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>first_keycode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the first KeyCode that is to be (Kc.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysyms_per_keycode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of KeySyms per KeyCode.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysyms</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of KeySyms.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_codes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of KeyCodes that are to be changed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XChangeKeyboardMapping</function>

-function defines the symbols for the specified number of KeyCodes

-starting with first_keycode.

-The symbols for KeyCodes outside this range remain unchanged.  

-The number of elements in keysyms must be:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-num_codes * keysyms_per_keycode

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The specified first_keycode must be greater than or equal to min_keycode 

-returned by

-<function>XDisplayKeycodes</function>,

-or a 

-<errorname>BadValue</errorname>

-error results.

-In addition, the following expression must be less than or equal to 

-max_keycode as returned by

-<function>XDisplayKeycodes</function>,

-or a

-<errorname>BadValue</errorname>

-error results:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-first_keycode + num_codes - 1

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-KeySym number N, counting from zero, for KeyCode K has the following index

-in keysyms, counting from zero: 

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-(K - first_keycode) * keysyms_per_keycode + N

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The specified keysyms_per_keycode can be chosen arbitrarily by the client

-to be large enough to hold all desired symbols. 

-A special KeySym value of 

-<symbol>NoSymbol</symbol>

-should be used to fill in unused elements 

-for individual KeyCodes.  

-It is legal for 

-<symbol>NoSymbol</symbol>

-to appear in nontrailing positions

-of the effective list for a KeyCode.

-<function>XChangeKeyboardMapping</function>

-generates a 

-<symbol>MappingNotify</symbol>

-event.

-</para>

-<para>

-<!-- .LP -->

-There is no requirement that the X server interpret this mapping. 

-It is merely stored for reading and writing by clients.

-</para>

-<para>

-<!-- .LP -->

-<function>XChangeKeyboardMapping</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-The next six functions make use of the 

-<structname>XModifierKeymap</structname>

-data structure, which contains:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XModifierKeymap</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	int max_keypermod;	/* This server's max number of keys per modifier */

-	KeyCode *modifiermap;	/* An 8 by max_keypermod array of the modifiers */

-} XModifierKeymap;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-To create an

-<structname>XModifierKeymap</structname>

-structure, use

-<function>XNewModifiermap</function>.

-<indexterm significance="preferred"><primary>XNewModifiermap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XModifierKeymap *<function>XNewModifiermap</function></funcdef>

-  <paramdef>int<parameter> max_keys_per_mod</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>max_keys_per_mod</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of KeyCode entries preallocated to the modifiers

-in the map.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XNewModifiermap</function>

-function returns a pointer to

-<structname>XModifierKeymap</structname>

-structure for later use.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To add a new entry to an 

-<structname>XModifierKeymap</structname>

-structure, use

-<function>XInsertModifiermapEntry</function>.

-<indexterm significance="preferred"><primary>XInsertModifiermapEntry</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XModifierKeymap *<function>XInsertModifiermapEntry</function></funcdef>

-  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>

-  <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>

-  <paramdef>int<parameter> modifier</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XModifierKeymap</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keycode_entry</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeyCode. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modifier</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the modifier.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XInsertModifiermapEntry</function>

-function adds the specified KeyCode to the set that controls the specified

-modifier and returns the resulting

-<structname>XModifierKeymap</structname>

-structure (expanded as needed).

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To delete an entry from an 

-<structname>XModifierKeymap</structname>

-structure, use

-<function>XDeleteModifiermapEntry</function>.

-<indexterm significance="preferred"><primary>XDeleteModifiermapEntry</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XModifierKeymap *<function>XDeleteModifiermapEntry</function></funcdef>

-  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>

-  <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>

-  <paramdef>int<parameter> modifier</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XModifierKeymap</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keycode_entry</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeyCode. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modifier</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the modifier.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDeleteModifiermapEntry</function>

-function deletes the specified KeyCode from the set that controls the

-specified modifier and returns a pointer to the resulting

-<structname>XModifierKeymap</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To destroy an

-<structname>XModifierKeymap</structname>

-structure, use

-<function>XFreeModifiermap</function>.

-<indexterm significance="preferred"><primary>XFreeModifiermap</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFreeModifiermap</function></funcdef>

-  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XModifierKeymap</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeModifiermap</function>

-function frees the specified

-<structname>XModifierKeymap</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the KeyCodes to be used as modifiers, use

-<function>XSetModifierMapping</function>.

-<indexterm significance="preferred"><primary>XSetModifierMapping</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XSetModifierMapping</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XModifierKeymap</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetModifierMapping</function>

-function specifies the KeyCodes of the keys (if any) that are to be used 

-as modifiers.

-If it succeeds,

-the X server generates a

-<symbol>MappingNotify</symbol>

-event, and

-<function>XSetModifierMapping</function>

-returns

-<symbol>MappingSuccess</symbol>.

-X permits at most 8 modifier keys.

-If more than 8 are specified in the

-<structname>XModifierKeymap</structname>

-structure, a

-<errorname>BadLength</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-The modifiermap member of the 

-<structname>XModifierKeymap</structname>

-structure contains 8 sets of max_keypermod KeyCodes, 

-one for each modifier in the order 

-<symbol>Shift</symbol>,

-<symbol>Lock</symbol>,

-<symbol>Control</symbol>,

-<symbol>Mod1</symbol>,

-<symbol>Mod2</symbol>,

-<symbol>Mod3</symbol>,

-<symbol>Mod4</symbol>,

-and 

-<symbol>Mod5</symbol>.

-Only nonzero KeyCodes have meaning in each set, 

-and zero KeyCodes are ignored.

-In addition, all of the nonzero KeyCodes must be in the range specified by 

-min_keycode and max_keycode in the 

-<type>Display</type>

-structure,

-or a 

-<errorname>BadValue</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-An X server can impose restrictions on how modifiers can be changed, 

-for example,

-if certain keys do not generate up transitions in hardware,

-if auto-repeat cannot be disabled on certain keys,

-or if multiple modifier keys are not supported.  

-If some such restriction is violated, 

-the status reply is

-<symbol>MappingFailed</symbol>,

-and none of the modifiers are changed.

-If the new KeyCodes specified for a modifier differ from those

-currently defined and any (current or new) keys for that modifier are

-in the logically down state, 

-<function>XSetModifierMapping</function>

-returns

-<symbol>MappingBusy</symbol>,

-and none of the modifiers is changed.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetModifierMapping</function>

-can generate

-<errorname>BadAlloc</errorname>

-and 

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the KeyCodes used as modifiers, use

-<function>XGetModifierMapping</function>.

-<indexterm significance="preferred"><primary>XGetModifierMapping</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XModifierKeymap *<function>XGetModifierMapping</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetModifierMapping</function>

-function returns a pointer to a newly created

-<structname>XModifierKeymap</structname>

-structure that contains the keys being used as modifiers.

-The structure should be freed after use by calling

-<function>XFreeModifiermap</function>.

-If only zero values appear in the set for any modifier, 

-that modifier is disabled.

-<!-- .bp -->

-

-

-</para>

-</sect1>

-</chapter>

+<?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="input_device_functions">
+<title>Input Device Functions</title>
+
+<para>
+You can use the Xlib input device functions to:
+</para>
+
+<itemizedlist>
+  <listitem><para>Grab the pointer and individual buttons on the pointer</para></listitem>
+  <listitem><para>Grab the keyboard and individual keys on the keyboard</para></listitem>
+  <listitem><para>Resume event processing</para></listitem>
+  <listitem><para>Move the pointer</para></listitem>
+  <listitem><para>Set the input focus</para></listitem>
+  <listitem><para>Manipulate the keyboard and pointer settings</para></listitem>
+  <listitem><para>Manipulate the keyboard encoding</para></listitem>
+</itemizedlist>
+
+<sect1 id="Pointer_Grabbing_">
+<title>Pointer Grabbing </title>
+<!-- .XS -->
+<!-- (SN Pointer Grabbing   -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to control input from the pointer,
+which usually is a mouse.
+Usually, as soon as keyboard and mouse events occur,
+the X server delivers them to the appropriate client,
+which is determined by the window and input focus.
+The X server provides sufficient control over event delivery to
+allow window managers to support mouse ahead and various other
+styles of user interface.
+Many of these user interfaces depend on synchronous delivery of events.
+The delivery of  pointer and keyboard events can be controlled
+independently.
+</para>
+<para>
+<!-- .LP -->
+When mouse buttons or keyboard keys are grabbed, events
+will be sent to the grabbing client rather than the normal
+client who would have received the event.
+If the keyboard or pointer is in asynchronous mode,
+further mouse and keyboard events will continue to be processed.
+If the keyboard or pointer is in synchronous mode, no
+further events are processed until the grabbing client
+allows them (see
+<function>XAllowEvents</function>).
+The keyboard or pointer is considered frozen during this
+interval.
+The event that triggered the grab can also be replayed.
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Active grab</primary></indexterm>
+There are two kinds of grabs:
+active and passive.
+An active grab occurs when a single client grabs the keyboard and/or pointer
+explicitly (see
+<function>XGrabPointer</function>
+and
+<function>XGrabKeyboard</function>).
+<indexterm><primary>Passive grab</primary></indexterm>
+A passive grab occurs when clients grab a particular keyboard key 
+or pointer button in a window,
+and the grab will activate when the key or button is actually pressed.
+Passive grabs are convenient for implementing reliable pop-up menus.
+For example, you can guarantee that the pop-up is mapped 
+before the up pointer button event occurs by
+grabbing a button requesting synchronous behavior.
+The down event will trigger the grab and freeze further
+processing of pointer events until you have the chance to
+map the pop-up window.
+You can then allow further event processing.
+The up event will then be correctly processed relative to the
+pop-up window.
+</para>
+<para>
+<!-- .LP -->
+For many operations,
+there are functions that take a time argument.
+The X server includes a timestamp in various events.
+One special time, called
+<indexterm significance="preferred"><primary>CurrentTime</primary></indexterm>
+<indexterm significance="preferred"><primary>Time</primary></indexterm>
+<symbol>CurrentTime</symbol>,
+represents the current server time.
+The X server maintains the time when the input focus was last changed,
+when the keyboard was last grabbed,
+when the pointer was last grabbed,
+or when a selection was last changed.
+Your
+application may be slow reacting to an event.
+You often need some way to specify that your
+request should not occur if another application has in the meanwhile
+taken control of the keyboard, pointer, or selection.
+By providing the timestamp from the event in the request, 
+you can arrange that the operation not take effect
+if someone else has performed an operation in the meanwhile.
+</para>
+<para>
+<!-- .LP -->
+A timestamp is a time value, expressed in milliseconds. 
+It typically is the time since the last server reset.
+Timestamp values wrap around (after about 49.7 days).
+The server, given its current time is represented by timestamp T, 
+always interprets timestamps from clients by treating half of the timestamp 
+space as being later in time than T.
+One timestamp value, named
+<symbol>CurrentTime</symbol>,
+is never generated by the server.
+This value is reserved for use in requests to represent the current server time.
+</para>
+<para>
+<!-- .LP -->
+For many functions in this section,
+you pass pointer event mask bits.
+The valid pointer event mask bits are:
+<symbol>ButtonPressMask</symbol>,
+<symbol>ButtonReleaseMask</symbol>,
+<symbol>EnterWindowMask</symbol>,
+<symbol>LeaveWindowMask</symbol>,
+<symbol>PointerMotionMask</symbol>,
+<symbol>PointerMotionHintMask</symbol>,
+<symbol>Button1MotionMask</symbol>,
+<symbol>Button2MotionMask</symbol>,
+<symbol>Button3MotionMask</symbol>,
+<symbol>Button4MotionMask</symbol>,
+<symbol>Button5MotionMask</symbol>,
+<symbol>ButtonMotionMask</symbol>,
+and
+<symbol>KeymapStateMask</symbol>.
+For other functions in this section,
+you pass keymask bits.
+The valid keymask bits are:
+<symbol>ShiftMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>Mod1Mask</symbol>,
+<symbol>Mod2Mask</symbol>,
+<symbol>Mod3Mask</symbol>,
+<symbol>Mod4Mask</symbol>,
+and
+<symbol>Mod5Mask</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab the pointer, use
+<function>XGrabPointer</function>.
+<indexterm><primary>Grabbing</primary><secondary>pointer</secondary></indexterm>
+<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgrabpointer'>
+<funcprototype>
+  <funcdef>int <function>XGrabPointer</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> grab_window</parameter></paramdef>
+  <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+  <paramdef>Window<parameter> confine_to</parameter></paramdef>
+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>grab_window</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the grab window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>owner_events</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether the pointer 
+events are to be reported as usual or reported with respect to the grab window 
+if selected by the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pointer_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies further processing of pointer events.
+You can pass 
+<symbol>GrabModeSync</symbol>
+or
+<symbol>GrabModeAsync</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keyboard_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies further processing of keyboard events.
+You can pass 
+<symbol>GrabModeSync</symbol>
+or
+<symbol>GrabModeAsync</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>confine_to</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window to confine the pointer in or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>cursor</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the cursor that is to be displayed during the grab or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabPointer</function>
+function actively grabs control of the pointer and returns
+<symbol>GrabSuccess</symbol>
+if the grab was successful.
+Further pointer events are reported only to the grabbing client.
+<function>XGrabPointer</function>
+overrides any active pointer grab by this client.
+If owner_events is 
+<symbol>False</symbol>,
+all generated pointer events
+are reported with respect to grab_window and are reported only if
+selected by event_mask.
+If owner_events is 
+<symbol>True</symbol>
+and if a generated
+pointer event would normally be reported to this client, 
+it is reported as usual. 
+Otherwise, the event is reported with respect to the
+grab_window and is reported only if selected by event_mask.
+For either value of owner_events, unreported events are discarded.
+</para>
+<para>
+<!-- .LP -->
+If the pointer_mode is 
+<symbol>GrabModeAsync</symbol>,
+pointer event processing continues as usual.
+If the pointer is currently frozen by this client, 
+the processing of events for the pointer is resumed.
+If the pointer_mode is 
+<symbol>GrabModeSync</symbol>,
+the state of the pointer, as seen by
+client applications,
+appears to freeze, and the X server generates no further pointer events
+until the grabbing client calls 
+<function>XAllowEvents</function>
+or until the pointer grab is released.
+Actual pointer changes are not lost while the pointer is frozen;
+they are simply queued in the server for later processing.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard_mode is 
+<symbol>GrabModeAsync</symbol>,
+keyboard event processing is unaffected by activation of the grab.
+If the keyboard_mode is 
+<symbol>GrabModeSync</symbol>,
+the state of the keyboard, as seen by
+client applications,
+appears to freeze, and the X server generates no further keyboard events
+until the grabbing client calls 
+<function>XAllowEvents</function>
+or until the pointer grab is released.
+Actual keyboard changes are not lost while the pointer is frozen;
+they are simply queued in the server for later processing.
+</para>
+<para>
+<!-- .LP -->
+If a cursor is specified, it is displayed regardless of what
+window the pointer is in.  
+If 
+<symbol>None</symbol>
+is specified,
+the normal cursor for that window is displayed
+when the pointer is in grab_window or one of its subwindows;
+otherwise, the cursor for grab_window is displayed.
+</para>
+<para>
+<!-- .LP -->
+If a confine_to window is specified,
+the pointer is restricted to stay contained in that window.
+The confine_to window need have no relationship to the grab_window.
+If the pointer is not initially in the confine_to window, 
+it is warped automatically to the closest edge 
+just before the grab activates and enter/leave events are generated as usual. 
+If the confine_to window is subsequently reconfigured, 
+the pointer is warped automatically, as necessary, 
+to keep it contained in the window.
+</para>
+<para>
+<!-- .LP -->
+The time argument allows you to avoid certain circumstances that come up
+if applications take a long time to respond or if there are long network
+delays.
+Consider a situation where you have two applications, both
+of which normally grab the pointer when clicked on.
+If both applications specify the timestamp from the event, 
+the second application may wake up faster and successfully grab the pointer
+before the first application. 
+The first application then will get an indication that the other application 
+grabbed the pointer before its request was processed.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabPointer</function>
+generates
+<symbol>EnterNotify</symbol>
+and
+<symbol>LeaveNotify</symbol>
+events.
+</para>
+<para>
+<!-- .LP -->
+Either if grab_window or confine_to window is not viewable
+or if the confine_to window lies completely outside the boundaries of the root
+window,
+<function>XGrabPointer</function>
+fails and returns
+<symbol>GrabNotViewable</symbol>.
+If the pointer is actively grabbed by some other client,
+it fails and returns
+<symbol>AlreadyGrabbed</symbol>.
+If the pointer is frozen by an active grab of another client,
+it fails and returns
+<symbol>GrabFrozen</symbol>.
+If the specified time is earlier than the last-pointer-grab time or later 
+than the current X server time, it fails and returns
+<symbol>GrabInvalidTime</symbol>.
+Otherwise, the last-pointer-grab time is set to the specified time
+(<symbol>CurrentTime</symbol>
+is replaced by the current X server time).
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabPointer</function>
+can generate
+<errorname>BadCursor</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the pointer, use
+<function>XUngrabPointer</function>.
+<indexterm><primary>Ungrabbing</primary><secondary>pointer</secondary></indexterm>
+<indexterm><primary>Pointer</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xungrabpointer'>
+<funcprototype>
+  <funcdef><function>XUngrabPointer</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabPointer</function>
+function releases the pointer and any queued events
+if this client has actively grabbed the pointer from
+<function>XGrabPointer</function>,
+<function>XGrabButton</function>,
+or from a normal button press.
+<function>XUngrabPointer</function>
+does not release the pointer if the specified
+time is earlier than the last-pointer-grab time or is later than the
+current X server time.
+It also generates 
+<symbol>EnterNotify</symbol>
+and 
+<symbol>LeaveNotify</symbol>
+events.
+The X server performs an 
+<systemitem>UngrabPointer</systemitem>
+request automatically if the event window or confine_to window 
+for an active pointer grab becomes not viewable
+or if window reconfiguration causes the confine_to window to lie completely
+outside the boundaries of the root window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change an active pointer grab, use
+<function>XChangeActivePointerGrab</function>.
+<indexterm><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>
+<indexterm ><primary>Changing</primary><secondary>pointer grab</secondary></indexterm>
+<indexterm significance="preferred"><primary>XChangeActivePointerGrab</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchangeactivepointergrab'>
+<funcprototype>
+  <funcdef><function>XChangeActivePointerGrab</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>cursor</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the cursor that is to be displayed or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeActivePointerGrab</function>
+function changes the specified dynamic parameters if the pointer is actively
+grabbed by the client and if the specified time is no earlier than the
+last-pointer-grab time and no later than the current X server time.
+This function has no effect on the passive parameters of an
+<function>XGrabButton</function>.
+The interpretation of event_mask and cursor is the same as described in
+<function>XGrabPointer</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeActivePointerGrab</function>
+can generate
+<errorname>BadCursor</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab a pointer button, use
+<function>XGrabButton</function>.
+<indexterm><primary>Grabbing</primary><secondary>buttons</secondary></indexterm>
+<indexterm><primary>Button</primary><secondary>grabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabButton</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgrabbutton'>
+<funcprototype>
+  <funcdef><function>XGrabButton</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedint<parameter> button</parameter></paramdef>
+  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+  <paramdef>Window<parameter> grab_window</parameter></paramdef>
+  <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+  <paramdef>unsignedint<parameter> event_mask</parameter></paramdef>
+  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+  <paramdef>Window<parameter> confine_to</parameter></paramdef>
+  <paramdef>Cursor<parameter> cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Bu grabbed -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>button</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the pointer button that is to be (Bu or
+<symbol>AnyButton</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modifiers</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the set of keymasks or
+<symbol>AnyModifier</symbol>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>grab_window</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the grab window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>owner_events</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether the pointer 
+events are to be reported as usual or reported with respect to the grab window 
+if selected by the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pointer_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies further processing of pointer events.
+You can pass 
+<symbol>GrabModeSync</symbol>
+or
+<symbol>GrabModeAsync</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keyboard_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies further processing of keyboard events.
+You can pass 
+<symbol>GrabModeSync</symbol>
+or
+<symbol>GrabModeAsync</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>confine_to</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window to confine the pointer in or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>cursor</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the cursor that is to be displayed or
+<symbol>None</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabButton</function>
+function establishes a passive grab.
+In the future,
+the pointer is actively grabbed (as for
+<function>XGrabPointer</function>),
+the last-pointer-grab time is set to the time at which the button was pressed
+(as transmitted in the
+<symbol>ButtonPress</symbol>
+event), and the
+<symbol>ButtonPress</symbol>
+event is reported if all of the following conditions are true:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The pointer is not grabbed, and the specified button is logically pressed
+when the specified modifier keys are logically down,
+and no other buttons or modifier keys are logically down.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The grab_window contains the pointer.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The confine_to window (if any) is viewable.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A passive grab on the same button/key combination does not exist
+on any ancestor of grab_window.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The interpretation of the remaining arguments is as for
+<function>XGrabPointer</function>.
+The active grab is terminated automatically when the logical state of the
+pointer has all buttons released
+(independent of the state of the logical modifier keys).
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+This request overrides all previous grabs by the same client on the same
+button/key combinations on the same window.
+A modifiers of 
+<symbol>AnyModifier</symbol>
+is equivalent to issuing the grab request for all
+possible modifier combinations (including the combination of no modifiers).  
+It is not required that all modifiers specified have currently assigned 
+KeyCodes.
+A button of 
+<symbol>AnyButton</symbol>
+is equivalent to
+issuing the request for all possible buttons.
+Otherwise, it is not required that the specified button currently be assigned
+to a physical button.
+</para>
+<para>
+<!-- .LP -->
+If some other client has already issued an
+<function>XGrabButton</function>
+with the same button/key combination on the same window, a
+<errorname>BadAccess</errorname>
+error results.
+When using 
+<symbol>AnyModifier</symbol>
+or 
+<symbol>AnyButton</symbol>,
+the request fails completely,
+and a
+<errorname>BadAccess</errorname>
+error results (no grabs are
+established) if there is a conflicting grab for any combination.
+<function>XGrabButton</function>
+has no effect on an active grab.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabButton</function>
+can generate
+<errorname>BadCursor</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab a pointer button, use
+<function>XUngrabButton</function>.
+<indexterm><primary>Ungrabbing</primary><secondary>buttons</secondary></indexterm>
+<indexterm><primary>Button</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabButton</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xungrabbutton'>
+<funcprototype>
+  <funcdef><function>XUngrabButton</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedint<parameter> button</parameter></paramdef>
+  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+  <paramdef>Window<parameter> grab_window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Bu released -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>button</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the pointer button that is to be (Bu or
+<symbol>AnyButton</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modifiers</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the set of keymasks or
+<symbol>AnyModifier</symbol>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>grab_window</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the grab window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabButton</function>
+function releases the passive button/key combination on the specified window if
+it was grabbed by this client.
+A modifiers of 
+<symbol>AnyModifier</symbol>
+is
+equivalent to issuing 
+the ungrab request for all possible modifier combinations, including 
+the combination of no modifiers.
+A button of 
+<symbol>AnyButton</symbol>
+is equivalent to issuing the
+request for all possible buttons.
+<function>XUngrabButton</function>
+has no effect on an active grab.
+</para>
+<para>
+<!-- .LP -->
+<function>XUngrabButton</function>
+can generate
+<errorname>BadValue</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Keyboard_Grabbing_">
+<title>Keyboard Grabbing </title>
+<!-- .XS -->
+<!-- (SN Keyboard Grabbing  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to grab or ungrab the keyboard
+as well as allow events.
+</para>
+<para>
+<!-- .LP -->
+For many functions in this section,
+you pass keymask bits.
+The valid keymask bits are:
+<symbol>ShiftMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>Mod1Mask</symbol>,
+<symbol>Mod2Mask</symbol>,
+<symbol>Mod3Mask</symbol>,
+<symbol>Mod4Mask</symbol>,
+and
+<symbol>Mod5Mask</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab the keyboard, use
+<function>XGrabKeyboard</function>.
+<indexterm><primary>Keyboard</primary><secondary>grabbing</secondary></indexterm>
+<indexterm><primary>Grabbing</primary><secondary>keyboard</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabKeyboard</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgrabkeyboard'>
+<funcprototype>
+  <funcdef>int <function>XGrabKeyboard</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> grab_window</parameter></paramdef>
+  <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>grab_window</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the grab window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>owner_events</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether the keyboard events 
+are to be reported as usual.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pointer_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies further processing of pointer events.
+You can pass 
+<symbol>GrabModeSync</symbol>
+or
+<symbol>GrabModeAsync</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keyboard_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies further processing of keyboard events.
+You can pass 
+<symbol>GrabModeSync</symbol>
+or
+<symbol>GrabModeAsync</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabKeyboard</function>
+function actively grabs control of the keyboard and generates
+<symbol>FocusIn</symbol>
+and
+<symbol>FocusOut</symbol>
+events.
+Further key events are reported only to the
+grabbing client.
+<function>XGrabKeyboard</function>
+overrides any active keyboard grab by this client.
+If owner_events is 
+<symbol>False</symbol>,
+all generated key events are reported with
+respect to grab_window.  
+If owner_events is 
+<symbol>True</symbol>
+and if a generated
+key event would normally be reported to this client, it is reported
+normally; otherwise, the event is reported with respect to the
+grab_window.  
+Both 
+<symbol>KeyPress</symbol>
+and 
+<symbol>KeyRelease</symbol>
+events are always reported,
+independent of any event selection made by the client.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard_mode argument is 
+<symbol>GrabModeAsync</symbol>,
+keyboard event processing continues
+as usual. 
+If the keyboard is currently frozen by this client, 
+then processing of keyboard events is resumed.
+If the keyboard_mode  argument is
+<symbol>GrabModeSync</symbol>,
+the state of the keyboard (as seen by client applications) appears to freeze,
+and the X server generates no further keyboard events until the
+grabbing client issues a releasing 
+<function>XAllowEvents</function>
+call or until the keyboard grab is released.
+Actual keyboard changes are not lost while the keyboard is frozen; 
+they are simply queued in the server for later processing.
+</para>
+<para>
+<!-- .LP -->
+If pointer_mode is 
+<symbol>GrabModeAsync</symbol>,
+pointer event processing is unaffected
+by activation of the grab.  
+If pointer_mode is 
+<symbol>GrabModeSync</symbol>,
+the state of the pointer (as seen by client applications) appears to freeze, 
+and the X server generates no further pointer events 
+until the grabbing client issues a releasing 
+<function>XAllowEvents</function>
+call or until the keyboard grab is released.
+Actual pointer changes are not lost while the pointer is frozen; 
+they are simply queued in the server for later processing.
+</para>
+<para>
+<!-- .LP -->
+If the keyboard is actively grabbed by some other client,
+<function>XGrabKeyboard</function>
+fails and returns
+<symbol>AlreadyGrabbed</symbol>.
+If grab_window is not viewable,
+it fails and returns
+<symbol>GrabNotViewable</symbol>.
+If the keyboard is frozen by an active grab of another client,
+it fails and returns
+<symbol>GrabFrozen</symbol>.
+If the specified time is earlier than the last-keyboard-grab time 
+or later than the current X server time,
+it fails and returns
+<symbol>GrabInvalidTime</symbol>.
+Otherwise, the last-keyboard-grab time is set to the specified time
+(<symbol>CurrentTime</symbol>
+is replaced by the current X server time).
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabKeyboard</function>
+can generate
+<errorname>BadValue</errorname>
+and 
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the keyboard, use
+<function>XUngrabKeyboard</function>.
+<indexterm><primary>Keyboard</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm><primary>Ungrabbing</primary><secondary>keyboard</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabKeyboard</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xungrabkeyboard'>
+<funcprototype>
+  <funcdef><function>XUngrabKeyboard</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabKeyboard</function>
+function
+releases the keyboard and any queued events if this client has it actively grabbed from
+either
+<function>XGrabKeyboard</function>
+or
+<function>XGrabKey</function>.
+<function>XUngrabKeyboard</function>
+does not release the keyboard and any queued events
+if the specified time is earlier than
+the last-keyboard-grab time or is later than the current X server time.
+It also generates
+<symbol>FocusIn</symbol>
+and 
+<symbol>FocusOut</symbol>
+events.
+The X server automatically performs an 
+<systemitem>UngrabKeyboard</systemitem>
+request if the event window for an
+active keyboard grab becomes not viewable.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To passively grab a single key of the keyboard, use
+<function>XGrabKey</function>.
+<indexterm><primary>Key</primary><secondary>grabbing</secondary></indexterm>
+<indexterm><primary>Grabbing</primary><secondary>keys</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGrabKey</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgrabkey'>
+<funcprototype>
+  <funcdef><function>XGrabKey</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> keycode</parameter></paramdef>
+  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+  <paramdef>Window<parameter> grab_window</parameter></paramdef>
+  <paramdef>Bool<parameter> owner_events</parameter></paramdef>
+  <paramdef>intpointer_mode,<parameter> keyboard_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keycode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeyCode or
+<symbol>AnyKey</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modifiers</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the set of keymasks or
+<symbol>AnyModifier</symbol>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>grab_window</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the grab window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>owner_events</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether the keyboard events 
+are to be reported as usual.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pointer_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies further processing of pointer events.
+You can pass 
+<symbol>GrabModeSync</symbol>
+or
+<symbol>GrabModeAsync</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keyboard_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies further processing of keyboard events.
+You can pass 
+<symbol>GrabModeSync</symbol>
+or
+<symbol>GrabModeAsync</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGrabKey</function>
+function establishes a passive grab on the keyboard.
+In the future,
+the keyboard is actively grabbed (as for
+<function>XGrabKeyboard</function>),
+the last-keyboard-grab time is set to the time at which the key was pressed
+(as transmitted in the
+<symbol>KeyPress</symbol>
+event), and the
+<symbol>KeyPress</symbol>
+event is reported if all of the following conditions are true:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The keyboard is not grabbed and the specified key
+(which can itself be a modifier key) is logically pressed
+when the specified modifier keys are logically down,
+and no other modifier keys are logically down.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Either the grab_window is an ancestor of (or is) the focus window,
+or the grab_window is a descendant of the focus window and contains the pointer.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A passive grab on the same key combination does not exist
+on any ancestor of grab_window.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The interpretation of the remaining arguments is as for 
+<function>XGrabKeyboard</function>.
+The active grab is terminated automatically when the logical state of the
+keyboard has the specified key released
+(independent of the logical state of the modifier keys).
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+A modifiers argument of 
+<symbol>AnyModifier</symbol>
+is equivalent to issuing the request for all
+possible modifier combinations (including the combination of no
+modifiers).  
+It is not required that all modifiers specified have
+currently assigned KeyCodes.
+A keycode argument of 
+<symbol>AnyKey</symbol>
+is equivalent to issuing
+the request for all possible KeyCodes.
+Otherwise, the specified keycode must be in
+the range specified by min_keycode and max_keycode in the connection
+setup, 
+or a
+<errorname>BadValue</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+If some other client has issued a 
+<function>XGrabKey</function>
+with the same key combination on the same window, a 
+<errorname>BadAccess</errorname>
+error results.
+When using
+<symbol>AnyModifier</symbol>
+or 
+<symbol>AnyKey</symbol>,
+the request fails completely,
+and a
+<errorname>BadAccess</errorname>
+error results (no grabs are established) 
+if there is a conflicting grab for any combination.
+</para>
+<para>
+<!-- .LP -->
+<function>XGrabKey</function>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab a key, use
+<function>XUngrabKey</function>.
+<indexterm><primary>Key</primary><secondary>ungrabbing</secondary></indexterm>
+<indexterm><primary>Ungrabbing</primary><secondary>keys</secondary></indexterm>
+<indexterm significance="preferred"><primary>XUngrabKey</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xungrabkey'>
+<funcprototype>
+  <funcdef><function>XUngrabKey</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> keycode</parameter></paramdef>
+  <paramdef>unsignedint<parameter> modifiers</parameter></paramdef>
+  <paramdef>Window<parameter> grab_window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keycode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeyCode or
+<symbol>AnyKey</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modifiers</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the set of keymasks or
+<symbol>AnyModifier</symbol>.
+The mask is the bitwise inclusive OR of the valid keymask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>grab_window</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the grab window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUngrabKey</function>
+function releases the key combination on the specified window if it was grabbed
+by this client.
+It has no effect on an active grab.
+A modifiers of
+<symbol>AnyModifier</symbol>
+is equivalent to issuing
+the request for all possible modifier combinations
+(including the combination of no modifiers).
+A keycode argument of
+<symbol>AnyKey</symbol>
+is equivalent to issuing the request for all possible key codes.
+</para>
+<para>
+<!-- .LP -->
+<function>XUngrabKey</function>
+can generate
+<errorname>BadValue</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Resuming_Event_Processing">
+<title>Resuming Event Processing</title>
+<!-- .XS -->
+<!-- (SN Resuming Event Processing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The previous sections discussed grab mechanisms with which processing
+of events by the server can be temporarily suspended.  This section
+describes the mechanism for resuming event processing.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allow further events to be processed when the device has been frozen, use
+<function>XAllowEvents</function>.
+<indexterm significance="preferred"><primary>XAllowEvents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xallowevents'>
+<funcprototype>
+  <funcdef><function>XAllowEvents</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> event_mode</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mode.
+You can pass 
+<symbol>AsyncPointer</symbol>,
+<symbol>SyncPointer</symbol>,
+<symbol>AsyncKeyboard</symbol>,
+<symbol>SyncKeyboard</symbol>,
+<symbol>ReplayPointer</symbol>,
+<symbol>ReplayKeyboard</symbol>,
+<symbol>AsyncBoth</symbol>,
+or
+<symbol>SyncBoth</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllowEvents</function>
+function releases some queued events if the client has caused a device 
+to freeze.
+It has no effect if the specified time is earlier than the last-grab
+time of the most recent active grab for the client or if the specified time
+is later than the current X server time.
+Depending on the event_mode argument, the following occurs:
+</para>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>AsyncPointer</symbol></entry>
+      <entry>If the pointer is frozen by the client,
+      pointer event processing continues as usual.
+      If the pointer is frozen twice by the client on behalf of two separate grabs,
+      <symbol>AsyncPointer</symbol>
+      thaws for both.
+      <symbol>AsyncPointer</symbol>
+      has no effect if the pointer is not frozen by the client,
+      but the pointer need not be grabbed by the client.</entry>
+    </row>
+    <row>
+      <entry><symbol>SyncPointer</symbol></entry>
+      <entry>If the pointer is frozen and actively grabbed by the client,
+      pointer event processing continues as usual until the next
+      <symbol>ButtonPress</symbol>
+      or
+      <symbol>ButtonRelease</symbol>
+      event is reported to the client.
+      At this time,
+      the pointer again appears to freeze.
+      However, if the reported event causes the pointer grab to be released,
+      the pointer does not freeze.
+      <symbol>SyncPointer</symbol>
+      has no effect if the pointer is not frozen by the client
+      or if the pointer is not grabbed by the client.</entry>
+    </row>
+    <row>
+      <entry><symbol>ReplayPointer</symbol></entry>
+      <entry>If the pointer is actively grabbed by the client and is frozen as the result of
+      an event having been sent to the client (either from the activation of an
+      <function>XGrabButton</function>
+      or from a previous
+      <function>XAllowEvents</function>
+      with mode
+      <symbol>SyncPointer</symbol>
+      but not from an 
+      <function>XGrabPointer</function>),
+      the pointer grab is released and that event is completely reprocessed.
+      This time, however, the function ignores any passive grabs at or above 
+      (toward the root of) the grab_window of the grab just released.
+      The request has no effect if the pointer is not grabbed by the client
+      or if the pointer is not frozen as the result of an event.</entry>
+    </row>
+    <row>
+      <entry><symbol>AsyncKeyboard</symbol></entry>
+      <entry>If the keyboard is frozen by the client,
+      keyboard event processing continues as usual.
+      If the keyboard is frozen twice by the client on behalf of two separate grabs,
+      <symbol>AsyncKeyboard</symbol>
+      thaws for both.
+      <symbol>AsyncKeyboard</symbol>
+      has no effect if the keyboard is not frozen by the client,
+      but the keyboard need not be grabbed by the client.</entry>
+    </row>
+    <row>
+      <entry><symbol>SyncKeyboard</symbol></entry>
+      <entry>If the keyboard is frozen and actively grabbed by the client,
+      keyboard event processing continues as usual until the next
+      <symbol>KeyPress</symbol>
+      or
+      <symbol>KeyRelease</symbol>
+      event is reported to the client.
+      At this time,
+      the keyboard again appears to freeze.
+      However, if the reported event causes the keyboard grab to be released,
+      the keyboard does not freeze.
+      <symbol>SyncKeyboard</symbol>
+      has no effect if the keyboard is not frozen by the client
+      or if the keyboard is not grabbed by the client.</entry>
+    </row>
+    <row>
+      <entry><symbol>ReplayKeyboard</symbol></entry>
+      <entry>If the keyboard is actively grabbed by the client and is frozen
+      as the result of an event having been sent to the client (either from the
+      activation of an
+      <function>XGrabKey</function>
+      or from a previous
+      <function>XAllowEvents</function>
+      with mode
+      <symbol>SyncKeyboard</symbol>
+      but not from an 
+      <function>XGrabKeyboard</function>),
+      the keyboard grab is released and that event is completely reprocessed.
+      This time, however, the function ignores any passive grabs at or above
+      (toward the root of)
+      the grab_window of the grab just released.
+      The request has no effect if the keyboard is not grabbed by the client
+      or if the keyboard is not frozen as the result of an event.</entry>
+    </row>
+    <row>
+      <entry><symbol>SyncBoth</symbol></entry>
+      <entry>If both pointer and keyboard are frozen by the client,
+      event processing for both devices continues as usual until the next
+      <symbol>ButtonPress</symbol>,
+      <symbol>ButtonRelease</symbol>,
+      <symbol>KeyPress</symbol>,
+      or 
+      <symbol>KeyRelease</symbol>
+      event is reported to the client for a grabbed device 
+      (button event for the pointer, key event for the keyboard), 
+      at which time the devices again appear to freeze.  
+      However, if the reported event causes the grab to be released,
+      then the devices do not freeze (but if the other device is still
+      grabbed, then a subsequent event for it will still cause both devices
+      to freeze).  
+      <symbol>SyncBoth</symbol>
+      has no effect unless both pointer and keyboard
+      are frozen by the client.
+      If the pointer or keyboard is frozen twice
+      by the client on behalf of two separate grabs, 
+      <symbol>SyncBoth</symbol>
+      thaws for both (but a subsequent freeze for 
+      <symbol>SyncBoth</symbol>
+      will only freeze each device once).</entry>
+    </row>
+    <row>
+      <entry><symbol>AsyncBoth</symbol></entry>
+      <entry>If the pointer and the keyboard are frozen by the
+      client, event processing for both devices continues as usual.
+      If a device is frozen twice by the client on behalf of two separate grabs,
+      <symbol>AsyncBoth</symbol>
+      thaws for both.
+      <symbol>AsyncBoth</symbol>
+      has no effect unless both
+      pointer and keyboard are frozen by the client.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+<symbol>AsyncPointer</symbol>,
+<symbol>SyncPointer</symbol>,
+and 
+<symbol>ReplayPointer</symbol>
+have no effect on the
+processing of keyboard events.
+<symbol>AsyncKeyboard</symbol>,
+<symbol>SyncKeyboard</symbol>,
+and 
+<symbol>ReplayKeyboard</symbol>
+have no effect on the
+processing of pointer events.
+It is possible for both a pointer grab and a keyboard grab (by the same 
+or different clients) to be active simultaneously.
+If a device is frozen on behalf of either grab,
+no event processing is performed for the device.
+It is possible for a single device to be frozen because of both grabs.
+In this case,
+the freeze must be released on behalf of both grabs before events can 
+again be processed.
+If a device is frozen twice by a single client,
+then a single
+<function>XAllowEvents</function>
+releases both.
+</para>
+<para>
+<!-- .LP -->
+<function>XAllowEvents</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Moving_the_Pointer">
+<title>Moving the Pointer</title>
+<!-- .XS -->
+<!-- (SN Moving the Pointer -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Although movement of the pointer normally should be left to the
+control of the end user, sometimes it is necessary to move the
+pointer to a new position under program control.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To move the pointer to an arbitrary point in a window, use
+<function>XWarpPointer</function>.
+<indexterm significance="preferred"><primary>XWarpPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xwarppointer'>
+<funcprototype>
+  <funcdef><function>XWarpPointer</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>
+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+  <paramdef>unsignedintsrc_width,<parameter> src_height</parameter></paramdef>
+  <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the source window or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the destination window or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify a rectangle in the source window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates within the destination window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If dest_w is
+<symbol>None</symbol>,
+<function>XWarpPointer</function>
+moves the pointer by the offsets (dest_x, dest_y) relative to the current
+position of the pointer.
+If dest_w is a window,
+<function>XWarpPointer</function>
+moves the pointer to the offsets (dest_x, dest_y) relative to the origin of
+dest_w.
+However, if src_w is a window,
+the move only takes place if the window src_w contains the pointer 
+and if the specified rectangle of src_w contains the pointer.
+</para>
+<para>
+<!-- .LP -->
+The src_x and src_y coordinates are relative to the origin of src_w.
+If src_height is zero,
+it is replaced with the current height of src_w minus src_y.
+If src_width is zero,
+it is replaced with the current width of src_w minus src_x.
+</para>
+<para>
+<!-- .LP -->
+There is seldom any reason for calling this function. 
+The pointer should normally be left to the user.
+If you do use this function, however, it generates events just as if the user
+had instantaneously moved the pointer from one position to another.
+Note that you cannot use
+<function>XWarpPointer</function>
+to move the pointer outside the confine_to window of an active pointer grab.
+An attempt to do so will only move the pointer as far as the closest edge of the
+confine_to window. 
+</para>
+<para>
+<!-- .LP -->
+<function>XWarpPointer</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Controlling_Input_Focus">
+<title>Controlling Input Focus</title>
+<!-- .XS -->
+<!-- (SN Controlling Input Focus  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and get the input focus.
+The input focus is a shared resource, and cooperation among clients is
+required for correct interaction.  See the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis> 
+for input focus policy.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the input focus, use
+<function>XSetInputFocus</function>.
+<indexterm significance="preferred"><primary>XSetInputFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetinputfocus'>
+<funcprototype>
+  <funcdef><function>XSetInputFocus</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> focus</parameter></paramdef>
+  <paramdef>int<parameter> revert_to</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>focus</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window,
+<symbol>PointerRoot</symbol>,
+or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>revert_to</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies where the input focus reverts to if the window becomes not
+viewable.
+You can pass 
+<symbol>RevertToParent</symbol>,
+<symbol>RevertToPointerRoot</symbol>,
+or 
+<symbol>RevertToNone</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetInputFocus</function>
+function changes the input focus and the last-focus-change time.
+It has no effect if the specified time is earlier than the current
+last-focus-change time or is later than the current X server time.
+Otherwise, the last-focus-change time is set to the specified time
+(<symbol>CurrentTime</symbol>
+is replaced by the current X server time).
+<function>XSetInputFocus</function>
+causes the X server to generate
+<symbol>FocusIn</symbol>
+and 
+<symbol>FocusOut</symbol>
+events.
+</para>
+<para>
+<!-- .LP -->
+Depending on the focus argument,
+the following occurs: 
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If focus is
+<symbol>None</symbol>,
+all keyboard events are discarded until a new focus window is set,
+and the revert_to argument is ignored.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If focus is a window, 
+it becomes the keyboard's focus window.
+If a generated keyboard event would normally be reported to this window
+or one of its inferiors, the event is reported as usual. 
+Otherwise, the event is reported relative to the focus window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If focus is
+<symbol>PointerRoot</symbol>,
+the focus window is dynamically taken to be the root window of whatever screen 
+the pointer is on at each keyboard event.  
+In this case, the revert_to argument is ignored.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The specified focus window must be viewable at the time 
+<function>XSetInputFocus</function>
+is called,
+or a
+<errorname>BadMatch</errorname>
+error results.
+If the focus window later becomes not viewable, 
+the X server
+evaluates the revert_to argument to determine the new focus window as follows: 
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If revert_to is
+<symbol>RevertToParent</symbol>,
+the focus reverts to the parent (or the closest viewable ancestor), 
+and the new revert_to value is taken to be
+<symbol>RevertToNone</symbol>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If revert_to is
+<symbol>RevertToPointerRoot</symbol>
+or 
+<symbol>RevertToNone</symbol>,
+the focus reverts to
+<symbol>PointerRoot</symbol>
+or
+<symbol>None</symbol>,
+respectively.
+When the focus reverts,
+the X server generates
+<symbol>FocusIn</symbol>
+and
+<symbol>FocusOut</symbol>
+events, but the last-focus-change time is not affected.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XSetInputFocus</function>
+can generate
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current input focus, use
+<function>XGetInputFocus</function>.
+<indexterm significance="preferred"><primary>XGetInputFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetinputfocus'>
+<funcprototype>
+  <funcdef><function>XGetInputFocus</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> *focus_return</parameter></paramdef>
+  <paramdef>int<parameter> *revert_to_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>focus_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the focus window,
+<symbol>PointerRoot</symbol>,
+or 
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>revert_to_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the current focus state
+(<symbol>RevertToParent</symbol>,
+<symbol>RevertToPointerRoot</symbol>,
+or 
+<symbol>RevertToNone</symbol>).
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetInputFocus</function>
+function returns the focus window and the current focus state.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Keyboard_and_Pointer_Settings">
+<title>Manipulating the Keyboard and Pointer Settings</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Keyboard and Pointer Settings  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to
+change the keyboard control, obtain a list of the auto-repeat keys,
+turn keyboard auto-repeat on or off, ring the bell, 
+set or obtain the pointer button or keyboard mapping, 
+and obtain a bit vector for the keyboard.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Keyboard</primary><secondary>bell volume</secondary></indexterm>
+<indexterm><primary>Keyboard</primary><secondary>keyclick volume</secondary></indexterm>
+<indexterm><primary>Keyboard</primary><secondary>bit vector</secondary></indexterm>
+<indexterm><primary>Mouse</primary><secondary>programming</secondary></indexterm>
+This section discusses 
+the user-preference options of bell, key click,
+pointer behavior, and so on.
+The default values for many of these options are server dependent.
+Not all implementations will actually be able to control all of these
+parameters.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XChangeKeyboardControl</function>
+function changes control of a keyboard and operates on a
+<structname>XKeyboardControl</structname>
+structure:
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+/* Mask bits for ChangeKeyboardControl */
+
+
+#define     KBBellPercent           (1L&lt;&lt;0)
+#define     KBBellPitch             (1L&lt;&lt;1)
+#define     KBBellDuration          (1L&lt;&lt;2)
+#define     KBLed                   (1L&lt;&lt;3)
+#define     KBLedMode               (1L&lt;&lt;4)
+#define     KBKey                   (1L&lt;&lt;5)
+#define     KBAutoRepeatMode        (1L&lt;&lt;6)
+
+
+/* Values */
+
+typedef struct {
+int key_click_percent;
+int bell_percent;
+int bell_pitch;
+int bell_duration;
+int led;
+int led_mode;                /* LedModeOn, LedModeOff */
+int key;
+int auto_repeat_mode;        /* AutoRepeatModeOff, AutoRepeatModeOn,
+                                AutoRepeatModeDefault */
+} XKeyboardControl;
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The key_click_percent member sets the volume for key clicks between 0 (off) 
+and 100 (loud) inclusive, if possible.  
+A setting of -1 restores the default.
+Other negative values generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+The bell_percent sets the base volume for the bell between 0 (off) and 100
+(loud) inclusive, if possible.  
+A setting of -1 restores the default.
+Other negative values generate a
+<errorname>BadValue</errorname>
+error.
+The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible.
+A setting of -1 restores the default.
+Other negative values generate a
+<errorname>BadValue</errorname>
+error.
+The bell_duration member sets the duration of the
+bell specified in milliseconds, if possible.  
+A setting of -1 restores the default.
+Other negative values generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+If both the led_mode and led members are specified,
+the state of that <acronym>LED</acronym> is changed, if possible.  
+The led_mode member can be set to
+<symbol>LedModeOn</symbol>
+or
+<symbol>LedModeOff</symbol>.
+If only led_mode is specified, the state of
+all LEDs are changed, if possible.  
+At most 32 LEDs numbered from one are supported. 
+No standard interpretation of LEDs is defined.
+If led is specified without led_mode, a
+<errorname>BadMatch</errorname>
+error results. 
+</para>
+<para>
+<!-- .LP -->
+If both the auto_repeat_mode and key members are specified, 
+the auto_repeat_mode of that key is changed (according to
+<symbol>AutoRepeatModeOn</symbol>,
+<symbol>AutoRepeatModeOff</symbol>,
+or
+<symbol>AutoRepeatModeDefault</symbol>),
+if possible.
+If only auto_repeat_mode is
+specified, the global auto_repeat_mode for the entire keyboard is
+changed, if possible, and does not affect the per-key settings.
+If a key is specified without an auto_repeat_mode, a
+<errorname>BadMatch</errorname>
+error results.
+Each key has an individual mode of whether or not it should auto-repeat
+and a default setting for the mode.
+In addition,
+there is a global mode of whether auto-repeat should be enabled or not
+and a default setting for that mode.
+When global mode is
+<symbol>AutoRepeatModeOn</symbol>,
+keys should obey their individual auto-repeat modes.
+When global mode is
+<symbol>AutoRepeatModeOff</symbol>,
+no keys should auto-repeat.
+An auto-repeating key generates alternating
+<symbol>KeyPress</symbol>
+and
+<symbol>KeyRelease</symbol>
+events.
+When a key is used as a modifier,
+it is desirable for the key not to auto-repeat,
+regardless of its auto-repeat setting.
+</para>
+<para>
+<!-- .LP -->
+A bell generator connected with the console but not directly on a
+keyboard is treated as if it were part of the keyboard.
+The order in which controls are verified and altered is server-dependent.
+If an error is generated, a subset of the controls may have been altered.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XChangeKeyboardControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchangekeyboardcontrol'>
+<funcprototype>
+  <funcdef><function>XChangeKeyboardControl</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> value_mask</parameter></paramdef>
+  <paramdef>XKeyboardControl<parameter> *values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which controls to change.
+This mask is the bitwise inclusive OR of the valid control mask bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>values</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies one value for each bit set to 1 in the mask.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeKeyboardControl</function>
+function controls the keyboard characteristics defined by the
+<structname>XKeyboardControl</structname>
+structure.
+The value_mask argument specifies which values are to be changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeKeyboardControl</function>
+can generate
+<errorname>BadMatch</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current control values for the keyboard, use
+<function>XGetKeyboardControl</function>.
+<indexterm significance="preferred"><primary>XGetKeyboardControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetkeyboardcontrol'>
+<funcprototype>
+  <funcdef><function>XGetKeyboardControl</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XKeyboardState<parameter> *values_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>values_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the current keyboard controls in the specified
+<structname>XKeyboardState</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetKeyboardControl</function>
+function returns the current control values for the keyboard to the
+<structname>XKeyboardState</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>XGetKeyboardControl</primary></indexterm>
+<indexterm significance="preferred"><primary>XKeyboardState</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i  -->
+<!-- .ta .5i -->
+typedef struct {
+	int key_click_percent;
+	int bell_percent;
+	unsigned int bell_pitch, bell_duration;
+	unsigned long led_mask;
+	int global_auto_repeat;
+	char auto_repeats[32];
+} XKeyboardState;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For the LEDs, 
+the least significant bit of led_mask corresponds to <acronym>LED</acronym> one,
+and each bit set to 1 in led_mask indicates an <acronym>LED</acronym> that is lit.
+The global_auto_repeat member can be set to
+<symbol>AutoRepeatModeOn</symbol>
+or
+<symbol>AutoRepeatModeOff</symbol>.
+The auto_repeats member is a bit vector.
+Each bit set to 1 indicates that auto-repeat is enabled 
+for the corresponding key.
+The vector is represented as 32 bytes.  
+Byte N (from 0) contains the bits for keys 8N to 8N + 7
+with the least significant bit in the byte representing key 8N.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To turn on keyboard auto-repeat, use
+<function>XAutoRepeatOn</function>.
+<indexterm significance="preferred"><primary>XAutoRepeatOn</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xautorepeaton'>
+<funcprototype>
+  <funcdef><function>XAutoRepeatOn</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAutoRepeatOn</function>
+function turns on auto-repeat for the keyboard on the specified display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To turn off keyboard auto-repeat, use
+<function>XAutoRepeatOff</function>.
+<indexterm significance="preferred"><primary>XAutoRepeatOff</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xautorepeatoff'>
+<funcprototype>
+  <funcdef><function>XAutoRepeatOff</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAutoRepeatOff</function>
+function turns off auto-repeat for the keyboard on the specified display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ring the bell, use
+<function>XBell</function>.
+<indexterm significance="preferred"><primary>XBell</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xbell'>
+<funcprototype>
+  <funcdef><function>XBell</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> percent</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>percent</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the volume for the bell,
+which can range from -100 to 100 inclusive. 
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XBell</function>
+function rings the bell on the keyboard on the specified display, if possible.
+The specified volume is relative to the base volume for the keyboard.
+If the value for the percent argument is not in the range -100 to 100
+inclusive, a
+<errorname>BadValue</errorname>
+error results.
+The volume at which the bell rings
+when the percent argument is nonnegative is:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+base - [(base * percent) / 100] + percent
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The volume at which the bell rings
+when the percent argument is negative is:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+base + [(base * percent) / 100]
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To change the base volume of the bell, use
+<function>XChangeKeyboardControl</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XBell</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a bit vector that describes the state of the keyboard, use
+<function>XQueryKeymap</function>.
+<indexterm significance="preferred"><primary>XQueryKeymap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xquerykeymap'>
+<funcprototype>
+  <funcdef><function>XQueryKeymap</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> keys_return[32]</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keys_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns an array of bytes that identifies which keys are pressed down.
+Each bit represents one key of the keyboard.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryKeymap</function>
+function returns a bit vector for the logical state of the keyboard, 
+where each bit set to 1 indicates that the corresponding key is currently 
+pressed down.
+The vector is represented as 32 bytes.
+Byte N (from 0) contains the bits for keys 8N to 8N + 7 
+with the least significant bit in the byte representing key 8N.
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the mapping of the pointer buttons, use
+<function>XSetPointerMapping</function>.
+<indexterm significance="preferred"><primary>XSetPointerMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetpointermapping'>
+<funcprototype>
+  <funcdef>int <function>XSetPointerMapping</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedchar<parameter> map[]</parameter></paramdef>
+  <paramdef>int<parameter> nmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>map</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the mapping list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of items in the mapping list.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetPointerMapping</function>
+function sets the mapping of the pointer.
+If it succeeds, the X server generates a
+<symbol>MappingNotify</symbol>
+event, and
+<function>XSetPointerMapping</function>
+returns
+<symbol>MappingSuccess</symbol>.
+Element map[i] defines the logical button number for the physical button
+i+1.
+The length of the list must be the same as
+<function>XGetPointerMapping</function>
+would return,
+or a
+<errorname>BadValue</errorname>
+error results.
+A zero element disables a button, and elements are not restricted in
+value by the number of physical buttons.
+However, no two elements can have the same nonzero value,
+or a
+<errorname>BadValue</errorname>
+error results.
+If any of the buttons to be altered are logically in the down state,
+<function>XSetPointerMapping</function>
+returns
+<symbol>MappingBusy</symbol>,
+and the mapping is not changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetPointerMapping</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the pointer mapping, use
+<function>XGetPointerMapping</function>.
+<indexterm significance="preferred"><primary>XGetPointerMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetpointermapping'>
+<funcprototype>
+  <funcdef>int <function>XGetPointerMapping</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>unsignedchar<parameter> map_return[]</parameter></paramdef>
+  <paramdef>int<parameter> nmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>map_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the mapping list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of items in the mapping list.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetPointerMapping</function>
+function returns the current mapping of the pointer.
+Pointer buttons are numbered starting from one.
+<function>XGetPointerMapping</function>
+returns the number of physical buttons actually on the pointer.
+The nominal mapping for a pointer is map[i]=i+1.
+The nmap argument specifies the length of the array where the pointer
+mapping is returned, and only the first nmap elements are returned 
+in map_return.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To control the pointer's interactive feel, use
+<function>XChangePointerControl</function>.
+<indexterm significance="preferred"><primary>XChangePointerControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchangepointercontrol'>
+<funcprototype>
+  <funcdef><function>XChangePointerControl</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Booldo_accel,<parameter> do_threshold</parameter></paramdef>
+  <paramdef>intaccel_numerator,<parameter> accel_denominator</parameter></paramdef>
+  <paramdef>int<parameter> threshold</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>do_accel</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that controls whether the values for 
+the accel_numerator or accel_denominator are used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>do_threshold</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that controls whether the value for the 
+threshold is used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>accel_numerator</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the numerator for the acceleration multiplier.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>accel_denominator</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the denominator for the acceleration multiplier.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>threshold</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the acceleration threshold.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangePointerControl</function>
+function defines how the pointing device moves.
+The acceleration, expressed as a fraction, is a
+multiplier for movement. 
+For example,
+specifying 3/1 means the pointer moves three times as fast as normal.
+The fraction may be rounded arbitrarily by the X server.  
+Acceleration
+only takes effect if the pointer moves more than threshold pixels at
+once and only applies to the amount beyond the value in the threshold argument.
+Setting a value to -1 restores the default.
+The values of the do_accel and do_threshold arguments must be 
+<symbol>True</symbol>
+for the pointer values to be set,
+or the parameters are unchanged.
+Negative values (other than -1) generate a
+<errorname>BadValue</errorname>
+error, as does a zero value
+for the accel_denominator argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangePointerControl</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the current pointer parameters, use
+<function>XGetPointerControl</function>.
+<indexterm significance="preferred"><primary>XGetPointerControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetpointercontrol'>
+<funcprototype>
+  <funcdef><function>XGetPointerControl</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int*accel_numerator_return,<parameter> *accel_denominator_return</parameter></paramdef>
+  <paramdef>int<parameter> *threshold_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>accel_numerator_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the numerator for the acceleration multiplier.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>accel_denominator_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the denominator for the acceleration multiplier.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>threshold_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the acceleration threshold.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetPointerControl</function>
+function returns the pointer's current acceleration multiplier
+and acceleration threshold.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Keyboard_Encoding">
+<title>Manipulating the Keyboard Encoding</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Keyboard Encoding  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A KeyCode represents a physical (or logical) key.  
+KeyCodes lie in the inclusive range [8,255].  
+A KeyCode value carries no intrinsic information,
+although server implementors may attempt to encode geometry 
+(for example, matrix) information in some fashion so that it can
+be interpreted in a server-dependent fashion.
+The mapping between keys and KeyCodes cannot be changed.
+</para>
+<para>
+<!-- .LP -->
+A KeySym is an encoding of a symbol on the cap of a key.  
+The set of defined KeySyms includes the ISO Latin character sets (1-4), 
+Katakana, Arabic, Cyrillic, Greek, Technical,
+Special, Publishing, APL, Hebrew, Thai, Korean
+and a miscellany of keys found
+on keyboards (Return, Help, Tab, and so on).  
+To the extent possible, these sets are derived from international
+standards. 
+In areas where no standards exist,
+some of these sets are derived from Digital Equipment Corporation standards.
+The list of defined symbols can be found in
+<filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename></secondary></indexterm>
+Unfortunately, some C preprocessors have
+limits on the number of defined symbols.
+If you must use KeySyms not
+in the Latin 1-4, Greek, and miscellaneous classes,
+you may have to define a symbol for those sets.
+Most applications usually only include 
+<filename class="headerfile">&lt;X11/keysym.h&gt;</filename>,
+<indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/keysym.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/keysym.h&gt;</filename></secondary></indexterm>
+which defines symbols for ISO Latin 1-4, Greek, and miscellaneous.
+</para>
+<para>
+<!-- .LP -->
+A list of KeySyms is associated with each KeyCode.
+The list is intended to convey the set of symbols on the corresponding key.
+If the list (ignoring trailing
+<symbol>NoSymbol</symbol>
+entries) is 
+a single KeySym ``<emphasis remap='I'>K</emphasis>'',
+then the list is treated as if it were the list 
+``<emphasis remap='I'>K</emphasis> NoSymbol <emphasis remap='I'>K</emphasis> NoSymbol''.
+If the list (ignoring trailing
+<symbol>NoSymbol</symbol>
+entries) is a pair of KeySyms ``<emphasis remap='I'>K1 K2</emphasis>'',
+then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K1 K2</emphasis>''.
+If the list (ignoring trailing
+<symbol>NoSymbol</symbol>
+entries) is a triple of KeySyms ``<emphasis remap='I'>K1 K2 K3</emphasis>'',
+then the list is treated as if it were the list ``<emphasis remap='I'>K1 K2 K3</emphasis> NoSymbol''.
+When an explicit ``void'' element is desired in the list,
+the value
+<symbol>VoidSymbol</symbol>
+can be used.
+</para>
+<para>
+<!-- .LP -->
+The first four elements of the list are split into two groups of KeySyms.
+Group 1 contains the first and second KeySyms;
+Group 2 contains the third and fourth KeySyms.
+Within each group,
+if the second element of the group is
+<symbol>NoSymbol</symbol>,
+then the group should be treated as if the second element were 
+the same as the first element,
+except when the first element is an alphabetic KeySym ``<emphasis remap='I'>K</emphasis>'' 
+for which both lowercase and uppercase forms are defined.
+In that case,
+the group should be treated as if the first element were 
+the lowercase form of ``<emphasis remap='I'>K</emphasis>'' and the second element were 
+the uppercase form of ``<emphasis remap='I'>K</emphasis>''.
+</para>
+<para>
+<!-- .LP -->
+The standard rules for obtaining a KeySym from a
+<symbol>KeyPress</symbol>
+event make use of only the Group 1 and Group 2 KeySyms;
+no interpretation of other KeySyms in the list is given.
+Which group to use is determined by the modifier state.
+Switching between groups is controlled by the KeySym named MODE SWITCH,
+by attaching that KeySym to some KeyCode and attaching 
+that KeyCode to any one of the modifiers
+<symbol>Mod1</symbol>
+through
+<symbol>Mod5</symbol>.
+This modifier is called the <emphasis remap='I'>group modifier</emphasis>.
+For any KeyCode,
+Group 1 is used when the group modifier is off,
+and Group 2 is used when the group modifier is on.
+</para>
+<para>
+<!-- .LP -->
+The
+<symbol>Lock</symbol>
+modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
+is attached to some KeyCode and that KeyCode is attached to the
+<symbol>Lock</symbol>
+modifier.  The
+<symbol>Lock</symbol>
+modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock
+is attached to some KeyCode and that KeyCode is attached to the
+<symbol>Lock</symbol>
+modifier.  If the
+<symbol>Lock</symbol>
+modifier could be interpreted as both
+CapsLock and ShiftLock, the CapsLock interpretation is used.
+</para>
+<para>
+<!-- .LP -->
+The operation of keypad keys is controlled by the KeySym named XK_Num_Lock,
+by attaching that KeySym to some KeyCode and attaching that KeyCode to any
+one of the modifiers
+<symbol>Mod1</symbol>
+through
+<symbol>Mod5</symbol>.
+This modifier is called the
+<emphasis remap='I'>numlock modifier</emphasis>.  The standard KeySyms with the prefix ``XK_KP_''
+in their
+name are called keypad KeySyms; these are KeySyms with numeric value in
+the hexadecimal range 0xFF80 to 0xFFBD inclusive.  In addition,
+vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF
+are also keypad KeySyms.
+</para>
+<para>
+<!-- .LP -->
+Within a group, the choice of KeySym is determined by applying the first
+rule that is satisfied from the following list:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The numlock modifier is on and the second KeySym is a keypad KeySym.  In
+this case, if the
+<symbol>Shift</symbol>
+modifier is on, or if the
+<symbol>Lock</symbol>
+modifier is on and
+is interpreted as ShiftLock, then the first KeySym is used, otherwise the
+second KeySym is used.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The
+<symbol>Shift</symbol>
+and
+<symbol>Lock</symbol>
+modifiers are both off.  In this case, the first
+KeySym is used.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The
+<symbol>Shift</symbol>
+modifier is off, and the
+<symbol>Lock</symbol>
+modifier is on and is
+interpreted as CapsLock.  In this case, the first KeySym is used, but if
+that KeySym is lowercase alphabetic, then the corresponding uppercase
+KeySym is used instead.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The
+<symbol>Shift</symbol>
+modifier is on, and the
+<symbol>Lock</symbol>
+modifier is on and is interpreted
+as CapsLock.  In this case, the second KeySym is used, but if that KeySym
+is lowercase alphabetic, then the corresponding uppercase KeySym is used
+instead.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The
+<symbol>Shift</symbol>
+modifier is on, or the
+<symbol>Lock</symbol>
+modifier is on and is interpreted
+as ShiftLock, or both.  In this case, the second KeySym is used.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+No spatial geometry of the symbols on the key is defined by
+their order in the KeySym list, 
+although a geometry might be defined on a
+server-specific basis.
+The X server does not use the mapping between KeyCodes and KeySyms.
+Rather, it merely stores it for reading and writing by clients.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the legal KeyCodes for a display, use
+<function>XDisplayKeycodes</function>.
+<indexterm significance="preferred"><primary>XDisplayKeycodes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplaykeycodes'>
+<funcprototype>
+  <funcdef><function>XDisplayKeycodes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int*min_keycodes_return,<parameter> *max_keycodes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>min_keycodes_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the minimum number of KeyCodes.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>max_keycodes_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the maximum number of KeyCodes.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayKeycodes</function>
+function returns the min-keycodes and max-keycodes supported by the
+specified display.
+The minimum number of KeyCodes returned is never less than 8,
+and the maximum number of KeyCodes returned is never greater than 255.
+Not all KeyCodes in this range are required to have corresponding keys.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the symbols for the specified KeyCodes, use
+<function>XGetKeyboardMapping</function>.
+<indexterm significance="preferred"><primary>XGetKeyboardMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetkeyboardmapping'>
+<funcprototype>
+  <funcdef>KeySym *<function>XGetKeyboardMapping</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>KeyCode<parameter> first_keycode</parameter></paramdef>
+  <paramdef>int<parameter> keycode_count</parameter></paramdef>
+  <paramdef>int<parameter> *keysyms_per_keycode_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Kc returned -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>first_keycode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the first KeyCode that is to be (Kc.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keycode_count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of KeyCodes that are to be returned.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysyms_per_keycode_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of KeySyms per KeyCode.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetKeyboardMapping</function>
+function returns the symbols for the specified number of KeyCodes
+starting with first_keycode.
+The value specified in first_keycode must be greater than 
+or equal to min_keycode as returned by
+<function>XDisplayKeycodes</function>,
+or a
+<errorname>BadValue</errorname>
+error results.
+In addition, the following expression must be less than or equal 
+to max_keycode as returned by
+<function>XDisplayKeycodes</function>:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+first_keycode + keycode_count - 1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If this is not the case, a 
+<errorname>BadValue</errorname>
+error results. 
+The number of elements in the KeySyms list is:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+keycode_count * keysyms_per_keycode_return
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+KeySym number N, counting from zero, for KeyCode K has the following index
+in the list, counting from zero: 
+<literallayout class="monospaced">
+(K - first_code) * keysyms_per_code_return + N
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The X server arbitrarily chooses the keysyms_per_keycode_return value 
+to be large enough to report all requested symbols. 
+A special KeySym value of 
+<symbol>NoSymbol</symbol>
+is used to fill in unused elements for
+individual KeyCodes.
+To free the storage returned by 
+<function>XGetKeyboardMapping</function>,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetKeyboardMapping</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the keyboard mapping, use
+<function>XChangeKeyboardMapping</function>.
+<indexterm significance="preferred"><primary>XChangeKeyboardMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchangekeyboardmapping'>
+<funcprototype>
+  <funcdef><function>XChangeKeyboardMapping</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> first_keycode</parameter></paramdef>
+  <paramdef>int<parameter> keysyms_per_keycode</parameter></paramdef>
+  <paramdef>KeySym<parameter> *keysyms</parameter></paramdef>
+  <paramdef>int<parameter> num_codes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Kc changed -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>first_keycode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the first KeyCode that is to be (Kc.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysyms_per_keycode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of KeySyms per KeyCode.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysyms</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of KeySyms.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_codes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of KeyCodes that are to be changed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeKeyboardMapping</function>
+function defines the symbols for the specified number of KeyCodes
+starting with first_keycode.
+The symbols for KeyCodes outside this range remain unchanged.  
+The number of elements in keysyms must be:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+num_codes * keysyms_per_keycode
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The specified first_keycode must be greater than or equal to min_keycode 
+returned by
+<function>XDisplayKeycodes</function>,
+or a 
+<errorname>BadValue</errorname>
+error results.
+In addition, the following expression must be less than or equal to 
+max_keycode as returned by
+<function>XDisplayKeycodes</function>,
+or a
+<errorname>BadValue</errorname>
+error results:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+first_keycode + num_codes - 1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+KeySym number N, counting from zero, for KeyCode K has the following index
+in keysyms, counting from zero: 
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(K - first_keycode) * keysyms_per_keycode + N
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The specified keysyms_per_keycode can be chosen arbitrarily by the client
+to be large enough to hold all desired symbols. 
+A special KeySym value of 
+<symbol>NoSymbol</symbol>
+should be used to fill in unused elements 
+for individual KeyCodes.  
+It is legal for 
+<symbol>NoSymbol</symbol>
+to appear in nontrailing positions
+of the effective list for a KeyCode.
+<function>XChangeKeyboardMapping</function>
+generates a 
+<symbol>MappingNotify</symbol>
+event.
+</para>
+<para>
+<!-- .LP -->
+There is no requirement that the X server interpret this mapping. 
+It is merely stored for reading and writing by clients.
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeKeyboardMapping</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+The next six functions make use of the 
+<structname>XModifierKeymap</structname>
+data structure, which contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XModifierKeymap</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	int max_keypermod;	/* This server's max number of keys per modifier */
+	KeyCode *modifiermap;	/* An 8 by max_keypermod array of the modifiers */
+} XModifierKeymap;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To create an
+<structname>XModifierKeymap</structname>
+structure, use
+<function>XNewModifiermap</function>.
+<indexterm significance="preferred"><primary>XNewModifiermap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xnewmodifiermap'>
+<funcprototype>
+  <funcdef>XModifierKeymap *<function>XNewModifiermap</function></funcdef>
+  <paramdef>int<parameter> max_keys_per_mod</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>max_keys_per_mod</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of KeyCode entries preallocated to the modifiers
+in the map.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNewModifiermap</function>
+function returns a pointer to
+<structname>XModifierKeymap</structname>
+structure for later use.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a new entry to an 
+<structname>XModifierKeymap</structname>
+structure, use
+<function>XInsertModifiermapEntry</function>.
+<indexterm significance="preferred"><primary>XInsertModifiermapEntry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xinsertmodifiermapentry'>
+<funcprototype>
+  <funcdef>XModifierKeymap *<function>XInsertModifiermapEntry</function></funcdef>
+  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+  <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>
+  <paramdef>int<parameter> modifier</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XModifierKeymap</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keycode_entry</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeyCode. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modifier</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the modifier.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInsertModifiermapEntry</function>
+function adds the specified KeyCode to the set that controls the specified
+modifier and returns the resulting
+<structname>XModifierKeymap</structname>
+structure (expanded as needed).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete an entry from an 
+<structname>XModifierKeymap</structname>
+structure, use
+<function>XDeleteModifiermapEntry</function>.
+<indexterm significance="preferred"><primary>XDeleteModifiermapEntry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdeletemodifiermapentry'>
+<funcprototype>
+  <funcdef>XModifierKeymap *<function>XDeleteModifiermapEntry</function></funcdef>
+  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+  <paramdef>KeyCode<parameter> keycode_entry</parameter></paramdef>
+  <paramdef>int<parameter> modifier</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XModifierKeymap</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keycode_entry</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeyCode. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modifier</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the modifier.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteModifiermapEntry</function>
+function deletes the specified KeyCode from the set that controls the
+specified modifier and returns a pointer to the resulting
+<structname>XModifierKeymap</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy an
+<structname>XModifierKeymap</structname>
+structure, use
+<function>XFreeModifiermap</function>.
+<indexterm significance="preferred"><primary>XFreeModifiermap</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreemodifiermap'>
+<funcprototype>
+  <funcdef><function>XFreeModifiermap</function></funcdef>
+  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XModifierKeymap</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeModifiermap</function>
+function frees the specified
+<structname>XModifierKeymap</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the KeyCodes to be used as modifiers, use
+<function>XSetModifierMapping</function>.
+<indexterm significance="preferred"><primary>XSetModifierMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetmodifiermapping'>
+<funcprototype>
+  <funcdef>int <function>XSetModifierMapping</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XModifierKeymap</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetModifierMapping</function>
+function specifies the KeyCodes of the keys (if any) that are to be used 
+as modifiers.
+If it succeeds,
+the X server generates a
+<symbol>MappingNotify</symbol>
+event, and
+<function>XSetModifierMapping</function>
+returns
+<symbol>MappingSuccess</symbol>.
+X permits at most 8 modifier keys.
+If more than 8 are specified in the
+<structname>XModifierKeymap</structname>
+structure, a
+<errorname>BadLength</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+The modifiermap member of the 
+<structname>XModifierKeymap</structname>
+structure contains 8 sets of max_keypermod KeyCodes, 
+one for each modifier in the order 
+<symbol>Shift</symbol>,
+<symbol>Lock</symbol>,
+<symbol>Control</symbol>,
+<symbol>Mod1</symbol>,
+<symbol>Mod2</symbol>,
+<symbol>Mod3</symbol>,
+<symbol>Mod4</symbol>,
+and 
+<symbol>Mod5</symbol>.
+Only nonzero KeyCodes have meaning in each set, 
+and zero KeyCodes are ignored.
+In addition, all of the nonzero KeyCodes must be in the range specified by 
+min_keycode and max_keycode in the 
+<type>Display</type>
+structure,
+or a 
+<errorname>BadValue</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+An X server can impose restrictions on how modifiers can be changed, 
+for example,
+if certain keys do not generate up transitions in hardware,
+if auto-repeat cannot be disabled on certain keys,
+or if multiple modifier keys are not supported.  
+If some such restriction is violated, 
+the status reply is
+<symbol>MappingFailed</symbol>,
+and none of the modifiers are changed.
+If the new KeyCodes specified for a modifier differ from those
+currently defined and any (current or new) keys for that modifier are
+in the logically down state, 
+<function>XSetModifierMapping</function>
+returns
+<symbol>MappingBusy</symbol>,
+and none of the modifiers is changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetModifierMapping</function>
+can generate
+<errorname>BadAlloc</errorname>
+and 
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the KeyCodes used as modifiers, use
+<function>XGetModifierMapping</function>.
+<indexterm significance="preferred"><primary>XGetModifierMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetmodifiermapping'>
+<funcprototype>
+  <funcdef>XModifierKeymap *<function>XGetModifierMapping</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetModifierMapping</function>
+function returns a pointer to a newly created
+<structname>XModifierKeymap</structname>
+structure that contains the keys being used as modifiers.
+The structure should be freed after use by calling
+<function>XFreeModifiermap</function>.
+If only zero values appear in the set for any modifier, 
+that modifier is disabled.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH13.xml b/libX11/specs/libX11/CH13.xml
index e28b1b0f3..4219fa981 100644
--- a/libX11/specs/libX11/CH13.xml
+++ b/libX11/specs/libX11/CH13.xml
@@ -1,10353 +1,10353 @@
-<?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="locales_and_internationalized_text_functions">

-<title>Locales and Internationalized Text Functions</title>

-

-<para>

-An internationalized application is one that is adaptable to the requirements of different native

-languages, local customs, and character string encodings. The process of adapting the operation

-to a particular native language, local custom, or string encoding is called localization. A goal of

-internationalization is to permit localization without program source modifications or recompilation.

-</para>

-<para>

-As one of the localization mechanisms, Xlib provides an X Input Method (<acronym>XIM</acronym>)

-functional interface for internationalized text input and an X Output Method

-(<acronym>XOM</acronym>) functional interface for internationalized text output.

-</para>

-<para>

-Internationalization in X is based on the concept of a locale. A locale defines the localized

-behavior of a program at run time. Locales affect Xlib in its:

-</para>

-

-<itemizedlist>

-  <listitem><para>Encoding and processing of input method text</para></listitem>

-  <listitem><para>Encoding of resource files and values</para></listitem>

-  <listitem><para>Encoding and imaging of text strings</para></listitem>

-  <listitem><para>Encoding and decoding for inter-client text communication</para></listitem>

-</itemizedlist>

-

-

-<para>

-•

-Encoding and decoding for inter-client text communication

-Characters from various languages are represented in a computer using an encoding.

-Different languages have different encodings, and there are even different

-encodings for the same characters in the same language.

-</para>

-<para>

-This chapter defines support for localized text imaging and text input and describes the locale

-mechanism that controls all locale-dependent Xlib functions. Sets of functions are provided for

-multibyte (char *) text as well as wide character (wchar_t) text in the form supported by the host

-C language environment. The multibyte and wide character functions are equivalent except for

-the form of the text argument.

-</para>

-<para>

-The Xlib internationalization functions are not meant to provide support for

-multilingual applications (mixing multiple languages within a single piece of text),

-but they make it possible to implement applications that work in limited

-fashion with more than one language in independent contexts.

-</para>

-<para>

-The remainder of this chapter discusses:

-</para>

-

-<itemizedlist>

-  <listitem><para>X locale management</para></listitem>

-  <listitem><para>Locale and modifier dependencies</para></listitem>

-  <listitem><para>Variable argument lists</para></listitem>

-  <listitem><para>Output methods</para></listitem>

-  <listitem><para>Input methods</para></listitem>

-  <listitem><para>String constants</para></listitem>

-</itemizedlist>

-

-

-<sect1 id="X_Locale_Management">

-<title>X Locale Management</title>

-<!-- .XS -->

-<!-- (SN X Locale Management -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-X supports one or more of the locales defined by the host environment.

-On implementations that conform to the ANSI C library,

-the locale announcement method is

-<function>setlocale</function>.

-This function configures the locale operation of both

-the host C library and Xlib.

-The operation of Xlib is governed by the LC_CTYPE category;

-this is called the <emphasis remap='I'>current locale</emphasis>.

-An implementation is permitted to provide implementation-dependent

-mechanisms for announcing the locale in addition to

-<function>setlocale</function>.

-</para>

-<para>

-<!-- .LP -->

-On implementations that do not conform to the ANSI C library, 

-the locale announcement method is Xlib implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-The mechanism by which the semantic operation of Xlib is defined

-for a specific locale is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-X is not required to support all the locales supported by the host.

-To determine if the current locale is supported by X, use

-<function>XSupportsLocale</function>.

-</para>

-

-<para>Bool XSupportsLocale()</para>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XSupportsLocale</function>

-function returns 

-<symbol>True</symbol>

-if Xlib functions are capable of operating under the current locale.

-If it returns 

-<symbol>False</symbol>,

-Xlib locale-dependent functions for which the 

-<symbol>XLocaleNotSupported</symbol>

-return status is defined will return 

-<symbol>XLocaleNotSupported</symbol>.

-Other Xlib locale-dependent routines will operate in the ``C'' locale.

-</para>

-<para>

-<!-- .LP -->

-The client is responsible for selecting its locale and X modifiers.

-Clients should provide a means for the user to override the clients'

-locale selection at client invocation.

-Most single-display X clients operate in a single locale 

-for both X and the host processing environment.

-They will configure the locale by calling three functions: 

-the host locale configuration function,

-<function>XSupportsLocale</function>,

-and 

-<function>XSetLocaleModifiers</function>.

-</para>

-<para>

-<!-- .LP -->

-The semantics of certain categories of X internationalization capabilities

-can be configured by setting modifiers.

-Modifiers are named by implementation-dependent and locale-specific strings.

-The only standard use for this capability at present

-is selecting one of several styles of keyboard input method.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To configure Xlib locale modifiers for the current locale, use

-<function>XSetLocaleModifiers</function>.

-<indexterm significance="preferred"><primary>XSetLocaleModifiers</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XSetLocaleModifiers</function></funcdef>

-  <paramdef>char<parameter> *modifier_list</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>modifier_list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the modifiers.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetLocaleModifiers</function>

-function sets the X modifiers for the current locale setting.

-The modifier_list argument is a null-terminated string of the form

-``{@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>}'', that is,

-having zero or more concatenated ``@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>''

-entries, where <emphasis remap='I'>category</emphasis> is a category name 

-and <emphasis remap='I'>value</emphasis> is the (possibly empty) setting for that category.

-The values are encoded in the current locale.

-Category names are restricted to the <acronym>POSIX</acronym> Portable Filename Character Set.

-</para>

-<para>

-<!-- .LP -->

-The local host X locale modifiers announcer (on <acronym>POSIX</acronym>-compliant systems,

-the XMODIFIERS environment variable) is appended to the modifier_list to

-provide default values on the local host.

-If a given category appears more than once in the list,

-the first setting in the list is used.

-If a given category is not included in the full modifier list,

-the category is set to an implementation-dependent default

-for the current locale.

-An empty value for a category explicitly specifies the

-implementation-dependent default.

-</para>

-<para>

-<!-- .LP -->

-If the function is successful, it returns a pointer to a string.

-The contents of the string are such that a subsequent call with that string

-(in the same locale) will restore the modifiers to the same settings.

-If modifier_list is a NULL pointer,

-<function>XSetLocaleModifiers</function>

-also returns a pointer to such a string,

-and the current locale modifiers are not changed.

-</para>

-<para>

-<!-- .LP -->

-If invalid values are given for one or more modifier categories supported by

-the locale, a NULL pointer is returned, and none of the

-current modifiers are changed.

-</para>

-<para>

-<!-- .LP -->

-At program startup,

-the modifiers that are in effect are unspecified until

-the first successful call to set them.  Whenever the locale is changed, the

-modifiers that are in effect become unspecified until the next successful call

-to set them.

-Clients should always call

-<function>XSetLocaleModifiers</function>

-with a non-NULL modifier_list after setting the locale

-before they call any locale-dependent Xlib routine.

-</para>

-<para>

-<!-- .LP -->

-The only standard modifier category currently defined is ``im'',

-which identifies the desired input method.

-The values for input method are not standardized.

-A single locale may use multiple input methods,

-switching input method under user control.

-The modifier may specify the initial input method in effect

-or an ordered list of input methods.

-Multiple input methods may be specified in a single im value string

-in an implementation-dependent manner.

-</para>

-<para>

-<!-- .LP -->

-The returned modifiers string is owned by Xlib and should not be modified or

-freed by the client.

-It may be freed by Xlib after the current locale or modifiers are changed.

-Until freed, it will not be modified by Xlib.

-</para>

-<para>

-<!-- .LP -->

-The recommended procedure for clients initializing their locale and modifiers

-is to obtain locale and modifier announcers separately from

-one of the following prioritized sources:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-A command line option

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A resource

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The empty string ("")

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The first of these that is defined should be used.

-Note that when a locale command line option or locale resource is defined,

-the effect should be to set all categories to the specified locale,

-overriding any category-specific settings in the local host environment.

-</para>

-</sect1>

-<sect1 id="Locale_and_Modifier_Dependencies">

-<title>Locale and Modifier Dependencies</title>

-<!-- .XS -->

-<!-- (SN Locale and Modifier Dependencies -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The internationalized Xlib functions operate in the current locale

-configured by the host environment and X locale modifiers set by

-<function>XSetLocaleModifiers</function>

-or in the locale and modifiers configured at the time

-some object supplied to the function was created.

-For each locale-dependent function,

-the following table describes the locale (and modifiers) dependency:

-</para>

-

-<informaltable>

-  <tgroup cols='3' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <thead>

-    <row>

-      <entry>Locale from</entry>

-      <entry>Affects the Function</entry>

-      <entry>In</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry></entry>

-      <entry>Locale Query/Configuration:</entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry><function>XSupportsLocale</function></entry>

-      <entry>Locale queried</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XSetLocaleModifiers</function></entry>

-      <entry>Locale modified</entry>

-    </row>

-    <row>

-      <entry></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>Resources:</entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry><function>XrmGetFileDatabase</function></entry>

-      <entry>Locale of <type>XrmDatabase</type></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XrmGetStringDatabase</function></entry>

-    </row>

-    <row>

-      <entry><type>XrmDatabase</type></entry>

-      <entry><function>XrmPutFileDatabase</function></entry>

-      <entry>Locale of <type>XrmDatabase</type></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XrmLocaleOfDatabase</function></entry>

-    </row>

-    <row>

-      <entry></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>Setting Standard Properties:</entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry><function>XmbSetWMProperties</function></entry>

-      <entry>Encoding of supplied/returned

-      text (some WM_ property

-      text in environment locale)</entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry><function>XmbTextPropertyToTextList</function></entry>

-      <entry>Encoding of supplied/returned text</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XwcTextPropertyToTextList</function></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XmbTextListToTextProperty</function></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XwcTextListToTextProperty</function></entry>

-    </row>

-    <row>

-      <entry></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>Text Input:</entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry><function>XOpenIM</function></entry>

-      <entry><acronym>XIM</acronym> input method selection</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XRegisterIMInstantiateCallback</function></entry>

-      <entry><acronym>XIM</acronym> selection</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XUnregisterIMInstantiateCallback</function></entry>

-      <entry><acronym>XIM</acronym> selection</entry>

-    </row>

-    <row>

-      <entry><type>XIM</type></entry>

-      <entry><function>XCreateIC</function></entry>

-      <entry><acronym>XIC</acronym> input method configuration</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XLocaleOfIM</function>,  and so on</entry>

-      <entry>Queried locale</entry>

-    </row>

-    <row>

-      <entry><type>XIC</type></entry>

-      <entry><function>XmbLookupString</function></entry>

-      <entry>Keyboard layout</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XwcLookupString</function></entry>

-      <entry>Encoding of returned text</entry>

-    </row>

-    <row>

-      <entry></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>Text Drawing:</entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry><function>XOpenOM</function></entry>

-      <entry><acronym>XOM</acronym> output method selection</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XCreateFontSet</function></entry>

-      <entry>Charsets of fonts in XFontSet</entry>

-    </row>

-    <row>

-      <entry><type>XOM</type></entry>

-      <entry><function>XCreateOC</function></entry>

-      <entry><acronym>XOC</acronym> output method configuration</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XLocaleOfOM</function>,  and so on</entry>

-      <entry>Queried locale</entry>

-    </row>

-    <row>

-      <entry><type>XFontSet</type></entry>

-      <entry><function>XmbDrawText</function>,</entry>

-      <entry>Locale of supplied text</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XwcDrawText</function>, and so on</entry>

-      <entry>Locale of supplied text</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XExtentsOfFontSet</function>, and so on</entry>

-      <entry>Locale-dependent metrics</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XmbTextExtents</function>,</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XwcTextExtents</function>,  and so on</entry>

-    </row>

-    <row>

-      <entry></entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>Xlib Errors:</entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry><function>XGetErrorDatabaseText</function></entry>

-      <entry>Locale of error message</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry><function>XGetErrorText</function></entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-Clients may assume that a locale-encoded text string returned 

-by an X function can be passed to a C library routine, or vice versa,

-if the locale is the same at the two calls.

-</para>

-<para>

-<!-- .LP -->

-All text strings processed by internationalized Xlib functions are assumed

-to begin in the initial state of the encoding of the locale, if the encoding

-is state-dependent.

-</para>

-<para>

-<!-- .LP -->

-All Xlib functions behave as if they do not change the current locale

-or X modifier setting.

-(This means that if they do change locale or call 

-<function>XSetLocaleModifiers</function>

-with a non-NULL argument, they must save and restore the current state on

-entry and exit.)

-Also, Xlib functions on implementations that conform to the ANSI C library do

-not alter the global state associated with the ANSI C functions 

-<function>mblen</function>,

-<function>mbtowc</function>,

-<function>wctomb</function>,

-and 

-<function>strtok</function>.

-</para>

-</sect1>

-<sect1 id="Variable_Argument_Lists">

-<title>Variable Argument Lists</title>

-<!-- .XS -->

-<!-- (SN Variable Argument Lists -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Various functions in this chapter have arguments that conform

-to the ANSI C variable argument list calling convention.

-Each function denoted with an argument of the form ``...'' takes 

-a variable-length list of name and value pairs,

-where each name is a string and each value is of type 

-<type>XPointer</type>.

-A name argument that is NULL identifies the end of the list. 

-</para>

-<para>

-<!-- .LP -->

-A variable-length argument list may contain a nested list.

-If the name 

-<symbol>XNVaNestedList</symbol>

-is specified in place of an argument name,

-then the following value is interpreted as an 

-<type>XVaNestedList</type>

-value that specifies a list of values logically inserted into the

-original list at the point of declaration.

-A NULL identifies the end of a nested list.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate a nested variable argument list dynamically, use

-<function>XVaCreateNestedList</function>.

-<indexterm significance="preferred"><primary>XVaCreateNestedList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XVaNestedList <function>XVaCreateNestedList</function></funcdef>

-  <paramdef>int<parameter> dummy</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dummy</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an unused argument (required by ANSI C).

-<!-- .ds Al -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XVaCreateNestedList</function>

-function allocates memory and copies its arguments into

-a single list pointer,

-which may be used as a value for arguments requiring a list value.

-Any entries are copied as specified.

-Data passed by reference is not copied;

-the caller must ensure data remains valid for the lifetime

-of the nested list.

-The list should be freed using

-<function>XFree</function>

-when it is no longer needed.

-</para>

-</sect1>

-<sect1 id="Output_Methods">

-<title>Output Methods</title>

-<!-- .XS -->

-<!-- (SN Output Methods -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section provides discussions of the following X Output Method

-(<acronym>XOM</acronym>) topics:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Output method overview

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Output method functions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Output method values

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Output context functions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Output context values

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Creating and freeing a font set

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Obtaining font set metrics

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Drawing text using font sets

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Output_Method_Overview">

-<title>Output Method Overview</title>

-<!-- .XS -->

-<!-- (SN Output Method Overview -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Locale-dependent text may include one or more text components, each of

-which may require different fonts and character set encodings.

-In some languages, each component might have a different

-drawing direction, and some components might contain

-context-dependent characters that change shape based on

-relationships with neighboring characters.

-</para>

-<para>

-<!-- .LP -->

-When drawing such locale-dependent text, some locale-specific

-knowledge is required;

-for example, what fonts are required to draw the text,

-how the text can be separated into components, and which

-fonts are selected to draw each component.

-Further, when bidirectional text must be drawn,

-the internal representation order of the text must be changed

-into the visual representation order to be drawn.

-</para>

-<para>

-<!-- .LP -->

-An X Output Method provides a functional interface so that clients

-do not have to deal directly with such locale-dependent details.

-Output methods provide the following capabilities:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Creating a set of fonts required to draw locale-dependent text.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Drawing locale-dependent text with a font set without the caller

-needing to be aware of locale dependencies.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Obtaining the escapement and extents in pixels of locale-dependent text.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Determining if bidirectional or context-dependent drawing is required

-in a specific locale with a specific font set.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Two different abstractions are used in the representation of

-the output method for clients.

-</para>

-<para>

-<!-- .LP -->

-The abstraction used to communicate with an output method

-is an opaque data structure represented by the 

-<type>XOM</type>

-data type.

-The abstraction for representing the state of a particular output thread

-is called an <emphasis remap='I'>output context</emphasis>.

-The Xlib representation of an output context is an 

-<type>XOC</type>,

-which is compatible with 

-<type>XFontSet</type>

-in terms of its functional interface, but is 

-a broader, more generalized abstraction.

-</para>

-</sect2>

-<sect2 id="Output_Method_Functions">

-<title>Output Method Functions</title>

-<!-- .XS -->

-<!-- (SN Output Method Functions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To open an output method, use

-<function>XOpenOM</function>.

-<indexterm significance="preferred"><primary>XOpenOM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XOM <function>XOpenOM</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>

-  <paramdef>char<parameter> *res_name</parameter></paramdef>

-  <paramdef>char<parameter> *res_class</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>res_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the full resource name of the application.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>res_class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the full class name of the application.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XOpenOM</function>

-function opens an output method

-matching the current locale and modifiers specification.

-The current locale and modifiers are bound to the output method

-when

-<function>XOpenOM</function>

-is called.

-The locale associated with an output method cannot be changed.

-</para>

-<para>

-<!-- .LP -->

-The specific output method to which this call will be routed

-is identified on the basis of the current locale and modifiers.

-<function>XOpenOM</function>

-will identify a default output method corresponding to the

-current locale.

-That default can be modified using 

-<function>XSetLocaleModifiers</function>

-to set the output method modifier.

-</para>

-<para>

-<!-- .LP -->

-The db argument is the resource database to be used by the output method

-for looking up resources that are private to the output method.

-It is not intended that this database be used to look

-up values that can be set as OC values in an output context.

-If db is NULL,

-no database is passed to the output method.

-</para>

-<para>

-<!-- .LP -->

-The res_name and res_class arguments specify the resource name 

-and class of the application. 

-They are intended to be used as prefixes by the output method

-when looking up resources that are common to all output contexts

-that may be created for this output method.

-The characters used for resource names and classes must be in the

-X Portable Character Set.

-The resources looked up are not fully specified

-if res_name or res_class is NULL.

-</para>

-<para>

-<!-- .LP -->

-The res_name and res_class arguments are not assumed to exist beyond

-the call to

-<function>XOpenOM</function>.

-The specified resource database is assumed to exist for the lifetime

-of the output method.

-</para>

-<para>

-<!-- .LP -->

-<function>XOpenOM</function>

-returns NULL if no output method could be opened.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To close an output method, use

-<function>XCloseOM</function>.

-<indexterm significance="preferred"><primary>XCloseOM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XCloseOM</function></funcdef>

-  <paramdef>XOM<parameter> om</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>om</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output method.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCloseOM</function>

-function closes the specified output method.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set output method attributes, use 

-<function>XSetOMValues</function>.

-<indexterm significance="preferred"><primary>XSetOMValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XSetOMValues</function></funcdef>

-  <paramdef>XOM<parameter> om</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>om</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output method.

-<!-- .ds Al \ to set <acronym>XOM</acronym> values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable-length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetOMValues</function>

-function presents a variable argument list programming interface

-for setting properties or features of the specified output method.

-This function returns NULL if it succeeds;

-otherwise,

-it returns the name of the first argument that could not be obtained.

-</para>

-<para>

-<!-- .LP -->

-No standard arguments are currently defined by Xlib.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To query an output method, use 

-<function>XGetOMValues</function>.

-<indexterm significance="preferred"><primary>XGetOMValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XGetOMValues</function></funcdef>

-  <paramdef>XOM<parameter> om</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>om</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output method.

-<!-- .ds Al \ to get XOM values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable-length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetOMValues</function>

-function presents a variable argument list programming interface

-for querying properties or features of the specified output method.

-This function returns NULL if it succeeds;

-otherwise,

-it returns the name of the first argument that could not be obtained.

-</para>

-<para>

-<!-- .LP -->

-To obtain the display associated with an output method, use

-<function>XDisplayOfOM</function>.

-<indexterm significance="preferred"><primary>XDisplayOfOM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Display *<function>XDisplayOfOM</function></funcdef>

-  <paramdef>XOM<parameter> om</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>om</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output method.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDisplayOfOM</function>

-function returns the display associated with the specified output method.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the locale associated with an output method, use

-<function>XLocaleOfOM</function>.

-<indexterm significance="preferred"><primary>XLocaleOfOM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XLocaleOfOM</function></funcdef>

-  <paramdef>XOM<parameter> om</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>om</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output method.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLocaleOfOM</function>

-returns the locale associated with the specified output method.

-</para>

-</sect2>

-<sect2 id="X_Output_Method_Values">

-<title>X Output Method Values</title>

-<!-- .XS -->

-<!-- (SN X Output Method Values -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The following table describes how <acronym>XOM</acronym> values are interpreted by an

-output method.

-The first column lists the <acronym>XOM</acronym> values.  The second column indicates

-how each of the <acronym>XOM</acronym> values are treated by a particular output style.

-</para>

-<para>

-<!-- .LP -->

-</para>

-<para>

-<!-- .LP -->

-The following key applies to this table.

-</para>

-

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry>Key</entry>

-      <entry>Explanation</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>G</entry>

-      <entry>This value may be read using <function>XGetOMValues</function>.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry><acronym>XOM</acronym> Value</entry>

-      <entry>Key</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry><symbol>XNRequiredCharSet</symbol></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNQueryOrientation</symbol></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNDirectionalDependentDrawing</symbol></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNContextualDrawing</symbol></entry>

-      <entry>G</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-</para>

-<sect3 id="Required_Char_Set">

-<title>Required Char Set</title>

-<!-- .XS -->

-<!-- (SN Required Char Set -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNRequiredCharSet</symbol>

-argument returns the list of charsets that are required for loading the fonts

-needed for the locale.

-The value of the argument is a pointer to a structure of type

-<structname>XOMCharSetList</structname>.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XOMCharSetList</structname>

-structure is defined as follows:

-<indexterm significance="preferred"><primary>XOMCharSetList</primary></indexterm>

-<!-- .sM -->

-</para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-     int    charset_count;

-     char   **charset_list;

-} XOMCharSetList;

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The charset_list member is a list of one or more null-terminated

-charset names, and the charset_count member is the number of

-charset names.

-</para>

-<para>

-<!-- .LP -->

-The required charset list is owned by Xlib and should not be modified or

-freed by the client.

-It will be freed by a call to 

-<function>XCloseOM</function>

-with the associated 

-<type>XOM</type>.

-Until freed, its contents will not be modified by Xlib.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Query_Orientation">

-<title>Query Orientation</title>

-<!-- .XS -->

-<!-- (SN Query Orientation -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNQueryOrientation</symbol>

-argument returns the global orientation of text when drawn.

-Other than

-<constant>XOMOrientation_LTR_TTB</constant>,

-the set of orientations supported is locale-dependent.

-The value of the argument is a pointer to a structure of type

-<structname>XOMOrientation</structname>.

-Clients are responsible for freeing the

-<structname>XOMOrientation</structname>

-structure by using

-<function>XFree</function>;

-this also frees the contents of the structure.

-</para>

-

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-     int          num_orientation;

-     XOrientation *orientation;     /* Input Text description */

-} XOMOrientation;

-

-typedef enum {

-     XOMOrientation_LTR_TTB,

-     XOMOrientation_RTL_TTB,     

-     XOMOrientation_TTB_LTR,

-     XOMOrientation_TTB_RTL,

-     XOMOrientation_Context

-} XOrientation;

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The possible value for XOrientation may be:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-<constant>XOMOrientation_LTR_TTB</constant>

-left-to-right, top-to-bottom global orientation

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<constant>XOMOrientation_RTL_TTB</constant>

-right-to-left, top-to-bottom global orientation

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<constant>XOMOrientation_TTB_LTR</constant>

-top-to-bottom, left-to-right global orientation

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<constant>XOMOrientation_TTB_RTL</constant>

-top-to-bottom, right-to-left global orientation

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<constant>XOMOrientation_Context</constant>

-contextual global orientation

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Directional_Dependent_Drawing">

-<title>Directional Dependent Drawing</title>

-<!-- .XS -->

-<!-- (SN Directional Dependent Drawing -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNDirectionalDependentDrawing</symbol>

-argument indicates whether the text rendering functions

-implement implicit handling of directional text.  If this value

-is

-<symbol>True</symbol>,

-the output method has knowledge of directional

-dependencies and reorders text as necessary when

-rendering text.  If this value is

-<symbol>False</symbol>,

-the output method does not implement any directional text

-handling, and all character directions are assumed to be left-to-right.

-</para>

-<para>

-<!-- .LP -->

-Regardless of the rendering order of characters,

-the origins of all characters are on the primary draw direction side

-of the drawing origin.

-</para>

-<para>

-<!-- .LP -->

-This OM value presents functionality identical to the

-<function>XDirectionalDependentDrawing</function>

-function.

-</para>

-</sect3>

-<sect3 id="Context_Dependent_Drawing">

-<title>Context Dependent Drawing</title>

-<!-- .XS -->

-<!-- (SN Context Dependent Drawing -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNContextualDrawing</symbol>

-argument indicates whether the text rendering functions

-implement implicit context-dependent drawing.  If this value is

-<symbol>True</symbol>,

-the output method has knowledge of context dependencies and

-performs character shape editing, combining glyphs to present

-a single character as necessary.  The actual shape editing is

-dependent on the locale implementation and the font set used.

-</para>

-<para>

-<!-- .LP -->

-This OM value presents functionality identical to the

-<function>XContextualDrawing</function>

-function.

-</para>

-</sect3>

-</sect2>

-<sect2 id="Output_Context_Functions">

-<title>Output Context Functions</title>

-<!-- .XS -->

-<!-- (SN Output Context Functions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-An output context is an abstraction that contains both the data

-required by an output method and the information required

-to display that data.

-There can be multiple output contexts for one output method.

-The programming interfaces for creating, reading, or modifying

-an output context use a variable argument list.

-The name elements of the argument lists are referred to as <acronym>XOC</acronym> values.

-It is intended that output methods be controlled by these <acronym>XOC</acronym> values.

-As new <acronym>XOC</acronym> values are created,

-they should be registered with the X Consortium.

-An

-<type>XOC</type>

-can be used anywhere an

-<type>XFontSet</type>

-can be used, and vice versa;

-<type>XFontSet</type>

-is retained for compatibility with previous releases.

-The concepts of output methods and output contexts include broader,

-more generalized abstraction than font set,

-supporting complex and more intelligent text display, and dealing not only

-with multiple fonts but also with context dependencies.

-However,

-<type>XFontSet</type>

-is widely used in several interfaces, so

-<type>XOC</type>

-is defined as an upward compatible type of

-<type>XFontSet</type>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create an output context, use

-<function>XCreateOC</function>.

-<indexterm significance="preferred"><primary>XCreateOC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XOC <function>XCreateOC</function></funcdef>

-  <paramdef>XOM<parameter> om</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>om</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output method.

-<!-- .ds Al \ to set <acronym>XOC</acronym> values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable-length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateOC</function>

-function creates an output context within the specified output method.

-</para>

-<para>

-<!-- .LP -->

-The base font names argument is mandatory at creation time, and

-the output context will not be created unless it is provided.

-All other output context values can be set later.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateOC</function>

-returns NULL if no output context could be created.

-NULL can be returned for any of the following reasons:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-A required argument was not set.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A read-only argument was set.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-An argument name is not recognized.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The output method encountered an output method implementation-dependent error.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-<function>XCreateOC</function>

-can generate a

-<errorname>BadAtom</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To destroy an output context, use

-<function>XDestroyOC</function>.

-<indexterm significance="preferred"><primary>XDestroyOC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XDestroyOC</function></funcdef>

-  <paramdef>XOC<parameter> oc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>oc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output context.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDestroyOC</function>

-function destroys the specified output context.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the output method associated with an output context, use

-<function>XOMOfOC</function>.

-<indexterm significance="preferred"><primary>XOMOfOC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XOM <function>XOMOfOC</function></funcdef>

-  <paramdef>XOC<parameter> oc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>oc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output context.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XOMOfOC</function>

-function returns the output method associated with the

-specified output context.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-Xlib provides two functions for setting and reading output context values,

-respectively,

-<function>XSetOCValues</function>

-and

-<function>XGetOCValues</function>.

-Both functions have a variable-length argument list.

-In that argument list, any <acronym>XOC</acronym> value's name must be denoted

-with a character string using the X Portable Character Set.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set <acronym>XOC</acronym> values, use

-<function>XSetOCValues</function>.

-<indexterm significance="preferred"><primary>XSetOCValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XSetOCValues</function></funcdef>

-  <paramdef>XOC<parameter> oc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>oc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output context.

-<!-- .ds Al \ to set <acronym>XOC</acronym> values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable-length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetOCValues</function>

-function returns NULL if no error occurred; 

-otherwise,

-it returns the name of the first argument that could not be set.

-An argument might not be set for any of the following reasons:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The argument is read-only.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The argument name is not recognized.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-An implementation-dependent error occurs.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Each value to be set must be an appropriate datum,

-matching the data type imposed by the semantics of the argument.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetOCValues</function>

-can generate a

-<errorname>BadAtom</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain <acronym>XOC</acronym> values, use

-<function>XGetOCValues</function>.

-<indexterm significance="preferred"><primary>XGetOCValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XGetOCValues</function></funcdef>

-  <paramdef>XOC<parameter> oc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>oc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the output context.

-<!-- .ds Al \ to get XOC values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable-length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetOCValues</function>

-function returns NULL if no error occurred; otherwise,

-it returns the name of the first argument that could not be obtained.

-An argument might not be obtained for any of the following reasons:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The argument name is not recognized.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-An implementation-dependent error occurs.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Each argument value

-following a name must point to a location where the value is to be stored.

-</para>

-</sect2>

-

-<sect2 id="Output_Context_Values">

-<title>Output Context Values</title>

-<!-- .XS -->

-<!-- (SN Output Context Values -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The following table describes how <acronym>XOC</acronym> values are interpreted

-by an output method.

-The first column lists the <acronym>XOC</acronym> values.

-The second column indicates the alternative interfaces that function

-identically and are provided for compatibility with previous releases.

-The third column indicates how each of the <acronym>XOC</acronym> values is treated.

-</para>

-<!-- .LP -->

-<para>

-The following keys apply to this table.

-</para>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry>Key</entry>

-      <entry>Explanation</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>C</entry>

-      <entry>This value must be set with <function>XCreateOC</function>.</entry>

-    </row>

-    <row>

-      <entry>D</entry>

-      <entry>This value may be set using <function>XCreateOC</function>.

-      If it is not set,a default is provided.</entry>

-    </row>

-    <row>

-      <entry>G</entry>

-      <entry>This value may be read using <function>XGetOCValues</function>.</entry>

-    </row>

-    <row>

-      <entry>S</entry>

-      <entry>This value must be set using <function>XSetOCValues</function>.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<!-- .LP -->

-<informaltable>

-  <tgroup cols='3' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <thead>

-    <row>

-      <entry><acronym>XOC</acronym> Value</entry>

-      <entry>Alternative Interface</entry>

-      <entry>Key</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>BaseFontName</entry>

-      <entry><function>XCreateFontSet</function></entry>

-      <entry>C-G</entry>

-    </row>

-    <row>

-      <entry>MissingCharSet</entry>

-      <entry><function>XCreateFontSet</function></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry>DefaultString</entry>

-      <entry><function>XCreateFontSet</function></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry>Orientation</entry>

-      <entry>-</entry>

-      <entry>D-S-G</entry>

-    </row>

-    <row>

-      <entry>ResourceName</entry>

-      <entry>-</entry>

-      <entry>S-G</entry>

-    </row>

-    <row>

-      <entry>ResourceClass</entry>

-      <entry>-</entry>

-      <entry>S-G</entry>

-    </row>

-    <row>

-      <entry>FontInfo</entry>

-      <entry><function>XFontsOfFontSet</function></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry>OMAutomatic</entry>

-      <entry>-</entry>

-      <entry>G</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-</para>

-<sect3 id="Base_Font_Name">

-<title>Base Font Name</title>

-<!-- .XS -->

-<!-- (SN Base Font Name -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNBaseFontName</symbol>

-argument is a list of base font names that Xlib uses

-to load the fonts needed for the locale.

-The base font names are a comma-separated list.  The string is null-terminated

-and is assumed to be in the Host Portable Character Encoding;

-otherwise, the result is implementation-dependent.

-White space immediately on either side of a separating comma is ignored.

-</para>

-<para>

-<!-- .LP -->

-Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a

-variety of locales from a single locale-independent base font name.

-The single base font name should name a family of fonts whose members

-are encoded in the various charsets needed by the locales of interest.

-</para>

-<para>

-<!-- .LP -->

-An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.

-This allows the user to specify an exact font for use with a charset required

-by a locale, fully controlling the font selection.

-</para>

-<para>

-<!-- .LP -->

-If a base font name is not an <acronym>XLFD</acronym> name,

-Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties

-for the font.

-If Xlib is successful, the

-<function>XGetOCValues</function>

-function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.

-</para>

-<para>

-<!-- .LP -->

-This argument must be set at creation time

-and cannot be changed.

-If no fonts exist for any of the required charsets,

-or if the locale definition in Xlib requires that a font exist

-for a particular charset and a font is not found for that charset,

-<function>XCreateOC</function>

-returns NULL.

-</para>

-<para>

-<!-- .LP -->

-When querying for the

-<symbol>XNBaseFontName</symbol>

-<acronym>XOC</acronym> value,

-<function>XGetOCValues</function>

-returns a null-terminated string identifying the base font names that

-Xlib used to load the fonts needed for the locale.

-This string is owned by Xlib and should not be modified or freed by

-the client.

-The string will be freed by a call to

-<function>XDestroyOC</function>

-with the associated

-<type>XOC</type>.

-Until freed, the string contents will not be modified by Xlib.

-</para>

-</sect3>

-<sect3 id="Missing_CharSet">

-<title>Missing CharSet</title>

-<!-- .XS -->

-<!-- (SN Missing CharSet -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNMissingCharSet</symbol>

-argument returns the list of required charsets that are missing from the

-font set.

-The value of the argument is a pointer to a structure of type

-<structname>XOMCharSetList</structname>.

-</para>

-<para>

-<!-- .LP -->

-If fonts exist for all of the charsets required by the current locale,

-charset_list is set to NULL and charset_count is set to zero.

-If no fonts exist for one or more of the required charsets,

-charset_list is set to a list of one or more null-terminated charset names

-for which no fonts exist, and charset_count is set to the number of

-missing charsets.

-The charsets are from the list of the required charsets for

-the encoding of the locale and do not include any charsets to which Xlib

-may be able to remap a required charset.

-</para>

-<para>

-<!-- .LP -->

-The missing charset list is owned by Xlib and should not be modified or

-freed by the client.

-It will be freed by a call to 

-<function>XDestroyOC</function>

-with the associated

-<type>XOC</type>.

-Until freed, its contents will not be modified by Xlib.

-</para>

-</sect3>

-<sect3 id="Default_String">

-<title>Default String</title>

-<!-- .XS -->

-<!-- (SN Default String -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-When a drawing or measuring function is called with an

-<type>XOC</type>

-that has missing charsets, some characters in the locale will not be

-drawable.

-The

-<symbol>XNDefaultString</symbol>

-argument returns a pointer to a string that represents the glyphs

-that are drawn with this

-<type>XOC</type>

-when the charsets of the available fonts do not include all glyphs

-required to draw a character.

-The string does not necessarily consist of valid characters

-in the current locale and is not necessarily drawn with

-the fonts loaded for the font set,

-but the client can draw or measure the default glyphs

-by including this string in a string being drawn or measured with the

-<type>XOC</type>.

-</para>

-<para>

-<!-- .LP -->

-If the

-<symbol>XNDefaultString</symbol>

-argument returned the empty string (""),

-no glyphs are drawn and the escapement is zero.

-The returned string is null-terminated.

-It is owned by Xlib and should not be modified or freed by the client.

-It will be freed by a call to

-<function>XDestroyOC</function>

-with the associated

-<type>XOC</type>.

-Until freed, its contents will not be modified by Xlib.

-</para>

-</sect3>

-<sect3 id="Orientation">

-<title>Orientation</title>

-<!-- .XS -->

-<!-- (SN Orientation -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNOrientation</symbol>

-argument specifies the current orientation of text when drawn.  The value of

-this argument is one of the values returned by the

-<function>XGetOMValues</function>

-function with the

-<symbol>XNQueryOrientation</symbol>

-argument specified in the

-<type>XOrientation</type>

-list.

-The value of the argument is of type

-<type>XOrientation</type>.

-When

-<symbol>XNOrientation</symbol>

-is queried, the value specifies the current orientation.  

-When

-<symbol>XNOrientation</symbol>

-is set, a value is used to set the current orientation.

-</para>

-<para>

-<!-- .LP -->

-When 

-<constant>XOMOrientation_Context</constant>

-is set, the text orientation of the 

-text is determined according to an implementation-defined method

-(for example, ISO 6429 control sequences), and the initial text orientation for

-locale-dependent Xlib functions is assumed to 

-be

-<constant>XOMOrientation_LTR_TTB</constant>.

-</para>

-<para>

-<!-- .LP -->

-The

-<symbol>XNOrientation</symbol>

-value does not change the prime drawing direction 

-for Xlib drawing functions.  

-</para>

-</sect3>

-<sect3 id="Resource_Name_and_Class">

-<title>Resource Name and Class</title>

-<!-- .XS -->

-<!-- (SN Resource Name and Class -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNResourceName</symbol>

-and

-<symbol>XNResourceClass</symbol>

-arguments are strings that specify the full name and class

-used by the client to obtain resources for the display of the output context.

-These values should be used as prefixes for name and class

-when looking up resources that may vary according to the output context.

-If these values are not set,

-the resources will not be fully specified.

-</para>

-<para>

-<!-- .LP -->

-It is not intended that values that can be set as <acronym>XOM</acronym> values be

-set as resources.

-</para>

-<para>

-<!-- .LP -->

-When querying for the

-<symbol>XNResourceName</symbol>

-or

-<symbol>XNResourceClass</symbol>

-<acronym>XOC</acronym> value,

-<function>XGetOCValues</function>

-returns a null-terminated string.

-This string is owned by Xlib and should not be modified or freed by

-the client.

-The string will be freed by a call to

-<function>XDestroyOC</function>

-with the associated

-<type>XOC</type>

-or when the associated value is changed via

-<function>XSetOCValues</function>.

-Until freed, the string contents will not be modified by Xlib.

-</para>

-</sect3>

-<sect3 id="Font_Info">

-<title>Font Info</title>

-<!-- .XS -->

-<!-- (SN Font Info -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNFontInfo</symbol>

-argument specifies a list of one or more 

-<structname>XFontStruct</structname>

-structures

-and font names for the fonts used for drawing by the given output context.

-The value of the argument is a pointer to a structure of type

-<structname>XOMFontInfo</structname>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-     int         num_font;

-     XFontStruct **font_struct_list;

-     char        **font_name_list;

-} XOMFontInfo;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-A list of pointers to the

-<structname>XFontStruct</structname>

-structures is returned to font_struct_list.

-A list of pointers to null-terminated, fully-specified font name strings

-in the locale of the output context is returned to font_name_list.

-The font_name_list order corresponds to the font_struct_list order.

-The number of

-<structname>XFontStruct</structname>

-structures and font names is returned to num_font.

-</para>

-<para>

-<!-- .LP -->

-Because it is not guaranteed that a given character will be imaged using a

-single font glyph,

-there is no provision for mapping a character or default string 

-to the font properties, font ID, or direction hint for the font 

-for the character.

-The client may access the 

-<structname>XFontStruct</structname>

-list to obtain these values for all the fonts currently in use.

-</para>

-<para>

-<!-- .LP -->

-Xlib does not guarantee that fonts are loaded from the server

-at the creation of an 

-<type>XOC</type>.

-Xlib may choose to cache font data, loading it only as needed to draw text 

-or compute text dimensions.

-Therefore, existence of the per_char metrics in the 

-<structname>XFontStruct</structname>

-structures in the

-<structname>XFontStructSet</structname>

-is undefined.

-Also, note that all properties in the 

-<structname>XFontStruct</structname>

-structures are in the STRING encoding.

-</para>

-<para>

-<!-- .LP -->

-The client must not free the 

-<structname>XOMFontInfo</structname>

-struct itself; it will be freed when the

-<type>XOC</type>

-is closed.

-</para>

-</sect3>

-<sect3 id="OM_Automatic">

-<title>OM Automatic</title>

-<!-- .XS -->

-<!-- (SN OM Automatic -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNOMAutomatic</symbol>

-argument returns whether the associated output context was created by

-<function>XCreateFontSet</function>

-or not.  Because the

-<function>XFreeFontSet</function>

-function not only destroys the output context but also closes the implicit

-output method associated with it,

-<function>XFreeFontSet</function>

-should be used with any output context created by 

-<function>XCreateFontSet</function>.

-However, it is possible that a client does not know how the output context

-was created.

-Before a client destroys the output context,

-it can query whether

-<symbol>XNOMAutomatic</symbol>

-is set to determine whether 

-<function>XFreeFontSet</function>

-or 

-<function>XDestroyOC</function>

-should be used to destroy the output context.

-</para>

-</sect3>

-</sect2>

-<sect2 id="Creating_and_Freeing_a_Font_Set">

-<title>Creating and Freeing a Font Set</title>

-<!-- .XS -->

-<!-- (SN Creating and Freeing a Font Set -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib international text drawing is done using a set of one or more fonts,

-as needed for the locale of the text.

-Fonts are loaded according to a list of base font names 

-supplied by the client and the charsets required by the locale.

-The

-<type>XFontSet</type>

-is an opaque type representing the state of a particular output thread

-and is equivalent to the type

-<type>XOC</type>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-The 

-<function>XCreateFontSet</function>

-function is a convenience function for creating an output context using

-only default values.  The returned

-<type>XFontSet</type>

-has an implicitly created

-<type>XOM</type>.

-This

-<type>XOM</type>

-has an OM value

-<symbol>XNOMAutomatic</symbol>

-automatically set to

-<symbol>True</symbol>

-so that the output context self indicates whether it was created by

-<function>XCreateOC</function>

-or

-<function>XCreateFontSet</function>.

-<indexterm significance="preferred"><primary>XCreateFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XFontSet <function>XCreateFontSet</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *base_font_name_list</parameter></paramdef>

-  <paramdef>char<parameter> ***missing_charset_list_return</parameter></paramdef>

-  <paramdef>int<parameter> *missing_charset_count_return</parameter></paramdef>

-  <paramdef>char<parameter> **def_string_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>base_font_name_list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the base font names.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>missing_charset_list_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the missing charsets.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>missing_charset_count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of missing charsets.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>def_string_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the string drawn for missing charsets.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XCreateFontSet</function>

-function creates a font set for the specified display.

-The font set is bound to the current locale when 

-<function>XCreateFontSet</function>

-is called.

-The font set may be used in subsequent calls to obtain font

-and character information and to image text in the locale of the font set.

-</para>

-<para>

-<!-- .LP -->

-The base_font_name_list argument is a list of base font names

-that Xlib uses to load the fonts needed for the locale.

-The base font names are a comma-separated list.

-The string is null-terminated

-and is assumed to be in the Host Portable Character Encoding; 

-otherwise, the result is implementation-dependent.

-White space immediately on either side of a separating comma is ignored.

-</para>

-<para>

-<!-- .LP -->

-Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a

-variety of locales from a single locale-independent base font name.

-The single base font name should name a family of fonts whose members

-are encoded in the various charsets needed by the locales of interest.

-</para>

-<para>

-<!-- .LP -->

-An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.

-This allows the user to specify an exact font for use with a charset required

-by a locale, fully controlling the font selection.

-</para>

-<para>

-<!-- .LP -->

-If a base font name is not an <acronym>XLFD</acronym> name,

-Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties

-for the font.

-If this action is successful in obtaining an <acronym>XLFD</acronym> name, the

-<function>XBaseFontNameListOfFontSet</function>

-function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.

-</para>

-<para>

-<!-- .LP -->

-Xlib uses the following algorithm to select the fonts

-that will be used to display text with the 

-<type>XFontSet</type>.

-</para>

-<para>

-<!-- .LP -->

-For each font charset required by the locale,

-the base font name list is searched for the first appearance of one 

-of the following cases that names a set of fonts that exist at the server:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The first <acronym>XLFD</acronym>-conforming base font name that specifies the required

-charset or a superset of the required charset in its 

-<structfield>CharSetRegistry</structfield>

-and 

-<structfield>CharSetEncoding</structfield>

-fields.

-The implementation may use a base font name whose specified charset

-is a superset of the required charset, for example,

-an ISO8859-1 font for an ASCII charset.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The first set of one or more <acronym>XLFD</acronym>-conforming base font names

-that specify one or more charsets that can be remapped to support the

-required charset.

-The Xlib implementation may recognize various mappings 

-from a required charset to one or more other charsets

-and use the fonts for those charsets.

-For example, JIS Roman is ASCII with tilde and backslash replaced 

-by yen and overbar;

-Xlib may load an ISO8859-1 font to support this character set

-if a JIS Roman font is not available.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The first <acronym>XLFD</acronym>-conforming font name or the first non-<acronym>XLFD</acronym> font name

-for which an <acronym>XLFD</acronym> font name can be obtained, combined with the

-required charset (replacing the 

-<structfield>CharSetRegistry</structfield>

-and

-<structfield>CharSetEncoding</structfield>

-fields in the <acronym>XLFD</acronym> font name).

-As in case 1,

-the implementation may use a charset that is a superset

-of the required charset.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The first font name that can be mapped in some implementation-dependent

-manner to one or more fonts that support imaging text in the charset.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-For example, assume that a locale required the charsets:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-ISO8859-1

-JISX0208.1983

-JISX0201.1976

-GB2312-1980.0

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The user could supply a base_font_name_list that explicitly specifies the

-charsets, ensuring that specific fonts are used if they exist.

-For example:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\

--JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\

--GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\

--Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Alternatively, the user could supply a base_font_name_list

-that omits the charsets,

-letting Xlib select font charsets required for the locale.

-For example:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\

--JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\

--GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\

--Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Alternatively, the user could simply supply a single base font name

-that allows Xlib to select from all available fonts

-that meet certain minimum <acronym>XLFD</acronym> property requirements.

-For example:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-"-*-*-*-R-Normal--*-180-100-100-*-*"

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-If 

-<function>XCreateFontSet</function>

-is unable to create the font set, 

-either because there is insufficient memory or because the current locale

-is not supported,

-<function>XCreateFontSet</function>

-returns NULL, missing_charset_list_return is set to NULL,

-and missing_charset_count_return

-is set to zero.

-If fonts exist for all of the charsets required by the current locale,

-<function>XCreateFontSet</function>

-returns a valid

-<type>XFontSet</type>,

-missing_charset_list_return is set to NULL,

-and missing_charset_count_return is set to zero.

-</para>

-<para>

-<!-- .LP -->

-If no font exists for one or more of the required charsets,

-<function>XCreateFontSet</function>

-sets missing_charset_list_return to a

-list of one or more null-terminated charset names for which no font exists

-and sets missing_charset_count_return to the number of missing fonts.

-The charsets are from the list of the required charsets for

-the encoding of the locale and do not include any charsets to which Xlib

-may be able to remap a required charset.

-</para>

-<para>

-<!-- .LP -->

-If no font exists for any of the required charsets

-or if the locale definition in Xlib requires that a font exist

-for a particular charset and a font is not found for that charset, 

-<function>XCreateFontSet</function>

-returns NULL.

-Otherwise, 

-<function>XCreateFontSet</function>

-returns a valid 

-<type>XFontSet</type>

-to font_set.

-</para>

-<para>

-<!-- .LP -->

-When an Xmb/wc drawing or measuring function is called with an

-<type>XFontSet</type>

-that has missing charsets, some characters in the locale will not be

-drawable.

-If def_string_return is non-NULL,

-<function>XCreateFontSet</function>

-returns a pointer to a string that represents the glyphs

-that are drawn with this 

-<type>XFontSet</type>

-when the charsets of the available fonts do not include all font glyphs

-required to draw a codepoint.

-The string does not necessarily consist of valid characters 

-in the current locale and is not necessarily drawn with

-the fonts loaded for the font set,

-but the client can draw and measure the default glyphs

-by including this string in a string being drawn or measured with the 

-<type>XFontSet</type>.

-</para>

-<para>

-<!-- .LP -->

-If the string returned to def_string_return is the empty string (""),

-no glyphs are drawn, and the escapement is zero.

-The returned string is null-terminated.

-It is owned by Xlib and should not be modified or freed by the client.

-It will be freed by a call to 

-<function>XFreeFontSet</function>

-with the associated 

-<type>XFontSet</type>.

-Until freed, its contents will not be modified by Xlib.

-</para>

-<para>

-<!-- .LP -->

-The client is responsible for constructing an error message from the

-missing charset and default string information and may choose to continue

-operation in the case that some fonts did not exist.

-</para>

-<para>

-<!-- .LP -->

-The returned 

-<type>XFontSet</type>

-and missing charset list should be freed with 

-<function>XFreeFontSet</function>

-and

-<function>XFreeStringList</function>,

-respectively.

-The client-supplied base_font_name_list may be freed 

-by the client after calling 

-<function>XCreateFontSet</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a list of 

-<structname>XFontStruct</structname>

-structures and full font names given an 

-<type>XFontSet</type>,

-use

-<function>XFontsOfFontSet</function>.

-<indexterm significance="preferred"><primary>XFontsOfFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XFontsOfFontSet</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>XFontStruct<parameter> ***font_struct_list_return</parameter></paramdef>

-  <paramdef>char<parameter> ***font_name_list_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_struct_list_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the list of font structs.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_name_list_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the list of font names.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFontsOfFontSet</function>

-function returns a list of one or more 

-<structname>XFontStruct</structname>s

-and font names for the fonts used by the Xmb and Xwc layers

-for the given font set.

-A list of pointers to the

-<structname>XFontStruct</structname>

-structures is returned to font_struct_list_return.

-A list of pointers to null-terminated, fully specified font name strings

-in the locale of the font set is returned to font_name_list_return.

-The font_name_list order corresponds to the font_struct_list order.

-The number of

-<structname>XFontStruct</structname>

-structures and font names is returned as the value of the function.

-</para>

-<para>

-<!-- .LP -->

-Because it is not guaranteed that a given character will be imaged using a

-single font glyph,

-there is no provision for mapping a character or default string 

-to the font properties, font ID, or direction hint for the font 

-for the character.

-The client may access the 

-<structname>XFontStruct</structname>

-list to obtain these values for all the fonts currently in use.

-</para>

-<para>

-<!-- .LP -->

-Xlib does not guarantee that fonts are loaded from the server

-at the creation of an 

-<type>XFontSet</type>.

-Xlib may choose to cache font data, loading it only as needed to draw text 

-or compute text dimensions.

-Therefore, existence of the per_char metrics in the 

-<structname>XFontStruct</structname>

-structures in the

-<structname>XFontStructSet</structname>

-is undefined.

-Also, note that all properties in the 

-<structname>XFontStruct</structname>

-structures are in the STRING encoding.

-</para>

-<para>

-<!-- .LP -->

-The 

-<structname>XFontStruct</structname>

-and font name lists are owned by Xlib 

-and should not be modified or freed by the client.

-They will be freed by a call to

-<function>XFreeFontSet</function>

-with the associated

-<type>XFontSet</type>.

-Until freed, their contents will not be modified by Xlib.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the base font name list and the selected font name list given an

-<type>XFontSet</type>,

-use

-<function>XBaseFontNameListOfFontSet</function>.

-<indexterm significance="preferred"><primary>XBaseFontNameListOfFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XBaseFontNameListOfFontSet</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XBaseFontNameListOfFontSet</function>

-function returns the original base font name list supplied

-by the client when the 

-<type>XFontSet</type>

-was created.

-A null-terminated string containing a list of

-comma-separated font names is returned

-as the value of the function.

-White space may appear immediately on either side of separating commas.

-</para>

-<para>

-<!-- .LP -->

-If 

-<function>XCreateFontSet</function>

-obtained an <acronym>XLFD</acronym> name from the font properties for the font specified

-by a non-<acronym>XLFD</acronym> base name, the

-<function>XBaseFontNameListOfFontSet</function>

-function will return the <acronym>XLFD</acronym> name instead of the non-<acronym>XLFD</acronym> base name.

-</para>

-<para>

-<!-- .LP -->

-The base font name list is owned by Xlib and should not be modified or

-freed by the client.

-It will be freed by a call to 

-<function>XFreeFontSet</function>

-with the associated 

-<type>XFontSet</type>.

-Until freed, its contents will not be modified by Xlib.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the locale name given an 

-<type>XFontSet</type>,

-use

-<function>XLocaleOfFontSet</function>.

-<indexterm significance="preferred"><primary>XLocaleOfFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XLocaleOfFontSet</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLocaleOfFontSet</function>

-function

-returns the name of the locale bound to the specified

-<type>XFontSet</type>,

-as a null-terminated string.

-</para>

-<para>

-<!-- .LP -->

-The returned locale name string is owned by Xlib

-and should not be modified or freed by the client.

-It may be freed by a call to

-<function>XFreeFontSet</function>

-with the associated 

-<type>XFontSet</type>.

-Until freed, it will not be modified by Xlib.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-The 

-<function>XFreeFontSet</function>

-function is a convenience function for freeing an output context.

-<function>XFreeFontSet</function>

-also frees its associated 

-<type>XOM</type>

-if the output context was created by

-<function>XCreateFontSet</function>.

-<indexterm significance="preferred"><primary>XFreeFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XFreeFontSet</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFreeFontSet</function>

-function frees the specified font set.

-The associated base font name list, font name list, 

-<structname>XFontStruct</structname>

-list, and 

-<structname>XFontSetExtents</structname>,

-if any, are freed.

-</para>

-</sect2>

-<sect2 id="Obtaining_Font_Set_Metrics">

-<title>Obtaining Font Set Metrics</title>

-<!-- .XS -->

-<!-- (SN Obtaining Font Set Metrics -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Metrics for the internationalized text drawing functions 

-are defined in terms of a primary draw direction, 

-which is the default direction in which the character origin advances

-for each succeeding character in the string.

-The Xlib interface is currently defined to support only a left-to-right

-primary draw direction.

-The drawing origin is the position passed to the drawing function 

-when the text is drawn.

-The baseline is a line drawn through the drawing origin parallel

-to the primary draw direction.

-Character ink is the pixels painted in the foreground color 

-and does not include interline or intercharacter spacing 

-or image text background pixels.

-</para>

-<para>

-<!-- .LP -->

-The drawing functions are allowed to implement implicit text

-directionality control, reversing the order in which characters are

-rendered along the primary draw direction in response to locale-specific

-lexical analysis of the string.

-</para>

-<para>

-<!-- .LP -->

-Regardless of the character rendering order,

-the origins of all characters are on the primary draw direction side

-of the drawing origin.

-The screen location of a particular character image may be determined with

-<function>XmbTextPerCharExtents</function>

-or

-<function>XwcTextPerCharExtents</function>.

-</para>

-<para>

-<!-- .LP -->

-The drawing functions are allowed to implement context-dependent

-rendering, where the glyphs drawn for a string are not simply a

-concatenation of the glyphs that represent each individual character.

-A string of two characters drawn with 

-<function>XmbDrawString</function>

-may render differently than if the two characters 

-were drawn with separate calls to

-<function>XmbDrawString</function>.

-If the client appends or inserts a character 

-in a previously drawn string,

-the client may need to redraw some adjacent characters 

-to obtain proper rendering.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To find out about direction-dependent rendering, use

-<function>XDirectionalDependentDrawing</function>.

-<indexterm significance="preferred"><primary>XDirectionalDependentDrawing</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XDirectionalDependentDrawing</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDirectionalDependentDrawing</function>

-function returns

-<symbol>True</symbol>

-if the drawing functions implement implicit text directionality;

-otherwise, it returns

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To find out about context-dependent rendering, use

-<function>XContextualDrawing</function>.

-<indexterm significance="preferred"><primary>XContextualDrawing</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XContextualDrawing</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XContextualDrawing</function>

-function returns

-<symbol>True</symbol>

-if text drawn with the font set might include context-dependent drawing;

-otherwise, it returns

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To find out about context-dependent or direction-dependent rendering, use

-<function>XContextDependentDrawing</function>.

-<indexterm significance="preferred"><primary>XContextDependentDrawing</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XContextDependentDrawing</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XContextDependentDrawing</function>

-function returns

-<symbol>True</symbol>

-if the drawing functions implement implicit text directionality or

-if text drawn with the font_set might include context-dependent drawing;

-otherwise, it returns

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-The drawing functions do not interpret newline, tab, or other control

-characters.

-The behavior when nonprinting characters other than space are drawn

-is implementation-dependent.

-It is the client's responsibility to interpret control characters

-in a text stream.

-</para>

-<para>

-<!-- .LP -->

-The maximum character extents for the fonts that are used by the text

-drawing layers can be accessed by the 

-<structname>XFontSetExtents</structname>

-structure:

-<indexterm significance="preferred"><primary>XFontSetExtents</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     XRectangle max_ink_extent;     /* over all drawable characters */

-     XRectangle max_logical_extent; /* over all drawable characters */

-} XFontSetExtents;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-The 

-<structname>XRectangle</structname>

-structures used to return font set metrics are the usual Xlib screen-oriented 

-rectangles

-with x, y giving the upper left corner, and width and height always positive.

-</para>

-<para>

-<!-- .LP -->

-The max_ink_extent member gives the maximum extent, over all drawable characters, of

-the rectangles that bound the character glyph image drawn in the

-foreground color, relative to a constant origin.

-See 

-<function>XmbTextExtents</function>

-and

-<function>XwcTextExtents</function>

-for detailed semantics.

-</para>

-<para>

-<!-- .LP -->

-The max_logical_extent member gives the maximum extent,

-over all drawable characters, of the rectangles 

-that specify minimum spacing to other graphical features,

-relative to a constant origin.

-Other graphical features drawn by the client, for example,

-a border surrounding the text, should not intersect this rectangle.

-The max_logical_extent member should be used to compute minimum 

-interline spacing and the minimum area that must be allowed

-in a text field to draw a given number of arbitrary characters.

-</para>

-<para>

-<!-- .LP -->

-Due to context-dependent rendering,

-appending a given character to a string may change 

-the string's extent by an amount other than that character's

-individual extent.

-</para>

-<para>

-<!-- .LP -->

-The rectangles for a given character in a string can be obtained from

-<function>XmbTextPerCharExtents</function>

-or

-<function>XwcTextPerCharExtents</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the maximum extents structure given an

-<type>XFontSet</type>,

-use

-<function>XExtentsOfFontSet</function>.

-<indexterm significance="preferred"><primary>XExtentsOfFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XFontSetExtents *<function>XExtentsOfFontSet</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XExtentsOfFontSet</function>

-function returns an

-<structname>XFontSetExtents</structname>

-structure for the fonts used by the Xmb and Xwc layers

-for the given font set.

-</para>

-<para>

-<!-- .LP -->

-The 

-<structname>XFontSetExtents</structname>

-structure is owned by Xlib and should not be modified

-or freed by the client.

-It will be freed by a call to 

-<function>XFreeFontSet</function>

-with the associated 

-<type>XFontSet</type>.

-Until freed, its contents will not be modified by Xlib.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the escapement in pixels of the specified text as a value,

-use

-<function>XmbTextEscapement</function>

-or 

-<function>XwcTextEscapement</function>.

-<indexterm significance="preferred"><primary>XmbTextEscapement</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcTextEscapement</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XmbTextEscapement</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_bytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XwcTextEscapement</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_wchars</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_bytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes in the string argument.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_wchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbTextEscapement</function>

-and

-<function>XwcTextEscapement</function>

-functions return the escapement in pixels of the specified string as a value,

-using the fonts loaded for the specified font set.

-The escapement is the distance in pixels in the primary draw

-direction from the drawing origin to the origin of the next character to

-be drawn, assuming that the rendering of the next character is not

-dependent on the supplied string.

-</para>

-<para>

-<!-- .LP -->

-Regardless of the character rendering order,

-the escapement is always positive.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the overall_ink_return and overall_logical_return arguments,

-the overall bounding box of the string's image, and a logical bounding box,

-use

-<function>XmbTextExtents</function>

- or

-<function>XwcTextExtents</function>.

-<indexterm significance="preferred"><primary>XmbTextExtents</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcTextExtents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XmbTextExtents</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_bytes</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XwcTextExtents</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_wchars</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_bytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes in the string argument.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_wchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-<!-- .ds Ov dimensions -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>overall_ink_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the overall ink dimensions.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>overall_logical_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the overall logical dimensions.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbTextExtents</function>

-and

-<function>XwcTextExtents</function>

-functions set the components of the specified overall_ink_return and

-overall_logical_return

-arguments to the overall bounding box of the string's image

-and a logical bounding box for spacing purposes, respectively.

-They return the value returned by 

-<function>XmbTextEscapement</function>

-or

-<function>XwcTextEscapement</function>.

-These metrics are relative to the drawing origin of the string,

-using the fonts loaded for the specified font set.

-</para>

-<para>

-<!-- .LP -->

-If the overall_ink_return argument is non-NULL,

-it is set to the bounding box of the string's character ink.

-The overall_ink_return for a nondescending, horizontally drawn

-Latin character is conventionally entirely above the baseline;

-that is, overall_ink_return.height &lt;= -overall_ink_return.y.

-The overall_ink_return for a nonkerned character

-is entirely at, and to the right of, the origin;

-that is, overall_ink_return.x &gt;= 0.

-A character consisting of a single pixel at the origin would set

-overall_ink_return fields y = 0, x = 0, width = 1, and height = 1.

-</para>

-<para>

-<!-- .LP -->

-If the overall_logical_return argument is non-NULL,

-it is set to the bounding box that provides minimum spacing

-to other graphical features for the string.

-Other graphical features, for example, a border surrounding the text,

-should not intersect this rectangle.

-</para>

-<para>

-<!-- .LP -->

-When the 

-<type>XFontSet</type>

-has missing charsets,

-metrics for each unavailable character are taken 

-from the default string returned by 

-<function>XCreateFontSet</function>

-so that the metrics represent the text as it will actually be drawn.

-The behavior for an invalid codepoint is undefined.

-</para>

-<para>

-<!-- .LP -->

-To determine the effective drawing origin for a character in a drawn string,

-the client should call 

-<function>XmbTextPerCharExtents</function>

-on the entire string, then on the character,

-and subtract the x values of the returned 

-rectangles for the character.

-This is useful to redraw portions of a line of text

-or to justify words, but for context-dependent rendering,

-the client should not assume that it can redraw the character by itself

-and get the same rendering.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain per-character information for a text string,

-use

-<function>XmbTextPerCharExtents</function>

-or

-<function>XwcTextPerCharExtents</function>.

-<indexterm significance="preferred"><primary>XmbTextPerCharExtents</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcTextPerCharExtents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XmbTextPerCharExtents</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_bytes</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>

-  <paramdef>int<parameter> array_size</parameter></paramdef>

-  <paramdef>int<parameter> *num_chars_return</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XwcTextPerCharExtents</function></funcdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_wchars</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>

-  <paramdef>int<parameter> array_size</parameter></paramdef>

-  <paramdef>int<parameter> *num_chars_return</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_bytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes in the string argument.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_wchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ink_array_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the ink dimensions for each character.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>logical_array_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the logical dimensions for each character.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>array_size</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size of ink_array_return and logical_array_return.

-The caller must pass in arrays of this size.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_chars_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of characters in the string argument.

-<!-- .ds Ov extents of the entire string -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>overall_ink_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the overall ink dimensions.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>overall_logical_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the overall logical dimensions.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbTextPerCharExtents</function>

-and

-<function>XwcTextPerCharExtents</function>

-functions return the text dimensions of each character of the specified text,

-using the fonts loaded for the specified font set.

-Each successive element of ink_array_return and logical_array_return

-is set to the successive character's drawn metrics,

-relative to the drawing origin of the string and one 

-rectangle

-for each character in the supplied text string.

-The number of elements of ink_array_return and logical_array_return

-that have been set is returned to num_chars_return.

-</para>

-<para>

-<!-- .LP -->

-Each element of ink_array_return is set to the bounding box 

-of the corresponding character's drawn foreground color.

-Each element of logical_array_return is set to the bounding box 

-that provides minimum spacing to other graphical features

-for the corresponding character.

-Other graphical features should not intersect any of the

-logical_array_return rectangles.

-</para>

-<para>

-<!-- .LP -->

-Note that an 

-<structname>XRectangle</structname>

-represents the effective drawing dimensions of the character,

-regardless of the number of font glyphs that are used to draw

-the character or the direction in which the character is drawn.

-If multiple characters map to a single character glyph,

-the dimensions of all the 

-<structname>XRectangle</structname>s

-of those characters are the same.

-</para>

-<para>

-<!-- .LP -->

-When the 

-<type>XFontSet</type>

-has missing charsets, metrics for each unavailable

-character are taken from the default string returned by 

-<function>XCreateFontSet</function>

-so that the metrics represent the text as it will actually be drawn.

-The behavior for an invalid codepoint is undefined.

-</para>

-<para>

-<!-- .LP -->

-If the array_size is too small for the number of characters in the

-supplied text, the functions return zero

-and num_chars_return is set to the number of rectangles required.

-Otherwise, the functions return a nonzero value.

-</para>

-<para>

-<!-- .LP -->

-If the overall_ink_return or overall_logical_return argument is non-NULL,

-<function>XmbTextPerCharExtents</function>

-and 

-<function>XwcTextPerCharExtents</function>

-return the maximum extent of the string's metrics to overall_ink_return

-or overall_logical_return, as returned by 

-<function>XmbTextExtents</function>

-or 

-<function>XwcTextExtents</function>.

-</para>

-</sect2>

-<sect2 id="Drawing_Text_Using_Font_Sets">

-<title>Drawing Text Using Font Sets</title>

-<!-- .XS -->

-<!-- (SN Drawing Text Using Font Sets -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The functions defined in this section

-draw text at a specified location in a drawable.

-They are similar to the functions

-<function>XDrawText</function>,

-<function>XDrawString</function>,

-and

-<function>XDrawImageString</function>

-except that they work with font sets instead of single fonts

-and interpret the text based on the locale of the font set

-instead of treating the bytes of the string as direct font indexes.

-See section 8.6 for details of the use of Graphics Contexts (GCs)

-and possible protocol errors.

-If a 

-<errorname>BadFont</errorname>

-error is generated,

-characters prior to the offending character may have been drawn.

-</para>

-<para>

-<!-- .LP -->

-The text is drawn using the fonts loaded for the specified font set;

-the font in the GC is ignored and may be modified by the functions.

-No validation that all fonts conform to some width rule is performed.

-</para>

-<para>

-<!-- .LP -->

-The text functions

-<function>XmbDrawText</function>

-and

-<function>XwcDrawText</function>

-use the following structures:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XmbTextItem</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-     char     *chars;    /* pointer to string */

-     int      nchars;    /* number of bytes */

-     int      delta;     /* pixel delta between strings */

-     XFontSet font_set;  /* fonts, None means don't change */

-} XmbTextItem;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XwcTextItem</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-     wchar_t *chars;     /* pointer to wide char string */

-     int nchars;     /* number of wide characters */

-     int delta;     /* pixel delta between strings */

-     XFontSet font_set;     /* fonts, None means don't change */

-} XwcTextItem;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To draw text using multiple font sets in a given drawable, use

-<function>XmbDrawText</function>

-or

-<function>XwcDrawText</function>.

-<indexterm significance="preferred"><primary>XmbDrawText</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcDrawText</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XmbDrawText</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>XmbTextItem<parameter> *items</parameter></paramdef>

-  <paramdef>int<parameter> nitems</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XwcDrawText</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>XwcTextItem<parameter> *items</parameter></paramdef>

-  <paramdef>int<parameter> nitems</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>items</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of text items.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nitems</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of text items in the array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbDrawText</function>

-and 

-<function>XwcDrawText</function>

-functions allow complex spacing and font set shifts between text strings.

-Each text item is processed in turn, with the origin of a text

-element advanced in the primary draw direction by the escapement of the

-previous text item.

-A text item delta specifies an additional escapement of the text item

-drawing origin in the primary draw direction.

-A font_set member other than 

-<symbol>None</symbol>

-in an item causes the font set to be used for this and subsequent text items

-in the text_items list.

-Leading text items with a font_set member set to

-<symbol>None</symbol>

-will not be drawn.

-</para>

-<para>

-<!-- .LP -->

-<function>XmbDrawText</function>

-and

-<function>XwcDrawText</function>

-do not perform any context-dependent rendering between text segments.

-Clients may compute the drawing metrics by passing each text segment to

-<function>XmbTextExtents</function>

-and

-<function>XwcTextExtents</function>

-or 

-<function>XmbTextPerCharExtents</function>

-and

-<function>XwcTextPerCharExtents</function>.

-When the 

-<type>XFontSet</type>

-has missing charsets, each unavailable character is drawn 

-with the default string returned by 

-<function>XCreateFontSet</function>.

-The behavior for an invalid codepoint is undefined.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To draw text using a single font set in a given drawable, use

-<function>XmbDrawString</function>

-or

-<function>XwcDrawString</function>.

-<indexterm significance="preferred"><primary>XmbDrawString</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcDrawString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XmbDrawString</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_bytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XwcDrawString</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_wchars</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_bytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes in the string argument.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_wchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbDrawString</function>

-and

-<function>XwcDrawString</function>

-functions draw the specified text with the foreground pixel.

-When the 

-<type>XFontSet</type>

-has missing charsets, each unavailable character is drawn 

-with the default string returned by 

-<function>XCreateFontSet</function>.

-The behavior for an invalid codepoint is undefined.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To draw image text using a single font set in a given drawable, use

-<function>XmbDrawImageString</function>

-or

-<function>XwcDrawImageString</function>.

-<indexterm significance="preferred"><primary>XmbDrawImageString</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcDrawImageString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XmbDrawImageString</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_bytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XwcDrawImageString</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>wchar_t<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_wchars</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>font_set</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the font set.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-<!-- .ds Xy -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_bytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes in the string argument.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_wchars</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of characters in the string argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbDrawImageString</function>

-and

-<function>XwcDrawImageString</function>

-functions fill a destination rectangle with the background pixel defined

-in the GC and then paint the text with the foreground pixel.

-The filled rectangle is the rectangle returned to overall_logical_return by

-<function>XmbTextExtents</function>

-or 

-<function>XwcTextExtents</function>

-for the same text and 

-<type>XFontSet</type>.

-</para>

-<para>

-<!-- .LP -->

-When the 

-<type>XFontSet</type>

-has missing charsets, each unavailable character is drawn 

-with the default string returned by 

-<function>XCreateFontSet</function>.

-The behavior for an invalid codepoint is undefined.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Input_Methods">

-<title>Input Methods</title>

-<!-- .XS -->

-<!-- (SN Input Methods -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section provides discussions of the following X Input Method

-(<acronym>XIM</acronym>) topics:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Input method overview

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Input method management

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Input method functions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Input method values

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Input context functions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Input context values

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Input method callback semantics

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Event filtering

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Getting keyboard input

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Input method conventions

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Input_Method_Overview">

-<title>Input Method Overview</title>

-<!-- .XS -->

-<!-- (SN Input Method Overview -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section provides definitions for terms and concepts used

-for internationalized text input and a brief overview of the

-intended use of the mechanisms provided by Xlib.

-</para>

-<para>

-<!-- .LP -->

-A large number of languages in the world use alphabets

-consisting of a small set of symbols (letters) to form words.

-To enter text into a computer in an alphabetic language,

-a user usually has a keyboard on which there exist key symbols corresponding

-to the alphabet.

-Sometimes, a few characters of an alphabetic language are missing

-on the keyboard.

-Many computer users who speak a Latin-alphabet-based language 

-only have an English-based keyboard.

-They need to hit a combination of keystrokes

-to enter a character that does not exist directly on the keyboard.

-A number of algorithms have been developed for entering such characters.

-These are known as European input methods, compose input methods, 

-or dead-key input methods.

-</para>

-<para>

-<!-- .LP -->

-Japanese is an example of a language with a phonetic symbol set,

-where each symbol represents a specific sound.

-There are two phonetic symbol sets in Japanese:  Katakana and Hiragana.

-In general,

-Katakana is used for words that are of foreign origin,

-and Hiragana is used for writing native Japanese words.

-Collectively, the two systems are called Kana.

-Each set consists of 48 characters.

-</para>

-<para>

-<!-- .LP -->

-Korean also has a phonetic symbol set, called Hangul.

-Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)

-represents a specific sound.

-A syllable is composed of two or three parts: 

-the initial consonants, the vowels, and the optional last consonants.

-With Hangul,

-syllables can be treated as the basic units on which text processing is done.

-For example,

-a delete operation may work on a phonetic symbol or a syllable.

-Korean code sets include several thousands of these syllables.

-A user types the phonetic symbols that make up the syllables of the words

-to be entered.

-The display may change as each phonetic symbol is entered.

-For example,

-when the second phonetic symbol of a syllable is entered,

-the first phonetic symbol may change its shape and size.

-Likewise, when the third phonetic symbol is entered,

-the first two phonetic symbols may change their shape and size.

-</para>

-<para>

-<!-- .LP -->

-Not all languages rely solely on alphabetic or phonetic systems.

-Some languages, including Japanese and Korean, employ an

-ideographic writing system.

-In an ideographic system, rather than taking a small set of

-symbols and combining them in different ways to create words,

-each word consists of one unique symbol (or, occasionally, several symbols).

-The number of symbols can be very large: 

-approximately 50,000 have been identified in Hanzi,

-the Chinese ideographic system.

-</para>

-<para>

-<!-- .LP -->

-Two major aspects of ideographic systems impact their use with computers.

-First, the standard computer character sets in Japan, China, and Korea

-include roughly 8,000 characters,

-while sets in Taiwan have between 15,000 and 30,000 characters.

-This makes it necessary to use more than one byte to represent a character.

-Second, it obviously is impractical to have a keyboard that includes

-all of a given language's ideographic symbols.

-Therefore, a mechanism is required for entering characters

-so that a keyboard with a reasonable number of keys can be used.

-Those input methods are usually based on phonetics,

-but there also exist methods based on the graphical properties of

-characters.

-</para>

-<para>

-<!-- .LP -->

-In Japan, both Kana and the ideographic system Kanji are used.

-In Korea, Hangul and sometimes the ideographic system Hanja are used.

-Now consider entering ideographs in Japan, Korea, China, and Taiwan.

-</para>

-<para>

-<!-- .LP -->

-In Japan, either Kana or English characters are typed and then a region

-is selected (sometimes automatically) for conversion to Kanji.

-Several Kanji characters may have the same phonetic representation.

-If that is the case with the string entered,

-a menu of characters is presented and

-the user must choose the appropriate one.

-If no choice is necessary or a preference has been established,

-the input method does the substitution directly.

-When Latin characters are converted to Kana or Kanji,

-it is called a romaji conversion.

-</para>

-<para>

-<!-- .LP -->

-In Korea, it is usually acceptable to keep Korean text in Hangul form,

-but some people may choose to write Hanja-originated words in Hanja

-rather than in Hangul.

-To change Hangul to Hanja,

-the user selects a region for conversion

-and then follows the same basic method as that described for Japanese.

-</para>

-<para>

-<!-- .LP -->

-Probably because there are well-accepted phonetic writing systems

-for Japanese and Korean,

-computer input methods in these countries for entering ideographs 

-are fairly standard.

-Keyboard keys have both English characters and phonetic symbols

-engraved on them, and the user can switch between the two sets.

-</para>

-<para>

-<!-- .LP -->

-The situation is different for Chinese.

-While there is a phonetic system called Pinyin promoted by authorities,

-there is no consensus for entering Chinese text.

-Some vendors use a phonetic decomposition (Pinyin or another),

-others use ideographic decomposition of Chinese words,

-with various implementations and keyboard layouts. 

-There are about 16 known methods, none of which is a clear standard. 

-</para>

-<para>

-<!-- .LP -->

-Also, there are actually two ideographic sets used:

-Traditional Chinese (the original written Chinese)

-and Simplified Chinese.

-Several years ago,

-the People's Republic of China launched a campaign to simplify

-some ideographic characters and eliminate redundancies altogether.

-Under the plan, 

-characters would be streamlined every five years.

-Characters have been revised several times now, 

-resulting in the smaller, simpler set that makes up Simplified Chinese.

-</para>

-<sect3 id="Input_Method_Architecture">

-<title>Input Method Architecture</title>

-<!-- .XS -->

-<!-- (SN Input Method Architecture -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-As shown in the previous section,

-there are many different input methods in use today,

-each varying with language, culture, and history. 

-A common feature of many input methods is that the user may type

-multiple keystrokes to compose a single character (or set

-of characters).

-The process of composing characters from keystrokes is called

-<emphasis remap='I'>preediting</emphasis>.

-It may require complex algorithms and large dictionaries 

-involving substantial computer resources.

-</para>

-<para>

-<!-- .LP -->

-Input methods may require one or more areas in which to show the

-feedback of the actual keystrokes, to propose disambiguation to the

-user, to list dictionaries, and so on.

-The input method areas of concern are as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The <emphasis remap='I'>status</emphasis> area is a logical extension of the

-LEDs that exist on the physical keyboard.

-It is a window that is intended to present the internal state

-of the input method that is critical to the user.

-The status area may consist of text data and bitmaps or some combination.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The <emphasis remap='I'>preedit</emphasis> area displays the

-intermediate text for those languages that are composing prior to 

-the client handling the data.   

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The <emphasis remap='I'>auxiliary</emphasis> area is used for pop-up menus and customizing

-dialogs that may be required for an input method.

-There may be multiple auxiliary areas for an input method.

-Auxiliary areas are managed by the input method independent of the client.

-Auxiliary areas are assumed to be separate dialogs,

-which are maintained by the input method.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-There are various user interaction styles used for preediting.

-The ones supported by Xlib are as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-For <emphasis remap='I'>on-the-spot</emphasis> input methods,

-preediting data will be displayed directly in the application window.

-Application data is moved to allow preedit data to appear

-at the point of insertion.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<emphasis remap='I'>Over-the-spot</emphasis> preediting means that the data is displayed in

-a preedit window that is placed over the point of insertion.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<emphasis remap='I'>Off-the-spot</emphasis> preediting means that the preedit window is

-inside the application window but not at the point of insertion.

-Often, this type of window is placed at the bottom of the application window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<emphasis remap='I'>Root-window</emphasis> preediting refers to input methods that use a preedit

-window that is the child of 

-<function>RootWindow</function>.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-It would require a lot of computing resources if portable applications

-had to include input methods for all the languages in the world.

-To avoid this,

-a goal of the Xlib design is to allow an application 

-to communicate with an input method placed in a separate process.

-Such a process is called an <emphasis remap='I'>input server</emphasis>.

-The server to which the application should connect is dependent on

-the environment when the application is started up,

-that is, the user language and the actual encoding to be used for it.

-The input method connection is said to be <emphasis remap='I'>locale-dependent</emphasis>.

-It is also user-dependent.

-For a given language, the user can choose, to some extent,

-the user interface style of input method (if choice is possible among

-several).

-</para>

-<para>

-<!-- .LP -->

-Using an input server implies communication overhead,

-but applications can be migrated without relinking.

-Input methods can be implemented either as a

-stub communicating to an input server or as a local library.

-</para>

-<para>

-<!-- .LP -->

-An input method may be based on a <emphasis remap='I'>front-end</emphasis> or a <emphasis remap='I'>back-end</emphasis>

-architecture.

-In a front-end architecture,

-there are two separate connections to the X server:

-keystrokes go directly from the X server to the input method on

-one connection and other events to the regular client connection.

-The input method is then acting as a filter and sends composed strings

-to the client.

-A front-end architecture requires synchronization between the

-two connections to avoid lost key events or locking issues.

-</para>

-<para>

-<!-- .LP -->

-In a back-end architecture,

-a single X server connection is used.

-A dispatching mechanism must decide on this channel to delegate appropriate

-keystrokes to the input method.

-For instance,

-it may retain a Help keystroke for its own purpose.

-In the case where the input method is a separate process (that is, a server),

-there must be a special communication protocol between the back-end client

-and the input server.

-</para>

-<para>

-<!-- .LP -->

-A front-end architecture introduces synchronization issues

-and a filtering mechanism for noncharacter keystrokes

-(Function keys, Help, and so on).

-A back-end architecture sometimes implies more communication overhead

-and more process switching.

-If all three processes (X server, input server, client)

-are running on a single workstation, 

-there are two process switches for each keystroke in a back-end

-architecture,

-but there is only one in a front-end architecture.

-</para>

-<para>

-<!-- .LP -->

-The abstraction used by a client to communicate with an input method

-is an opaque data structure represented by the 

-<type>XIM</type>

-data type.

-This data structure is returned by the 

-<function>XOpenIM</function>

-function, which opens an input method on a given display.

-Subsequent operations on this data structure encapsulate all communication

-between client and input method.

-There is no need for an X client to use any networking library 

-or natural language package to use an input method.

-</para>

-<para>

-<!-- .LP -->

-A single input server may be used for one or more languages,

-supporting one or more encoding schemes.

-But the strings returned from an input method will always be encoded

-in the (single) locale associated with the

-<type>XIM</type>

-object.

-</para>

-</sect3>

-<sect3 id="Input_Contexts">

-<title>Input Contexts</title>

-<!-- .XS -->

-<!-- (SN Input Contexts -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides the ability to manage a multi-threaded state for text input.

-A client may be using multiple windows,

-each window with multiple text entry areas,

-and the user possibly switching among them at any time.

-The abstraction for representing the state of a particular input thread

-is called an <emphasis remap='I'>input context</emphasis>.

-The Xlib representation of an input context is an 

-<type>XIC</type>.

-</para>

-<para>

-<!-- .LP -->

-An input context is the abstraction retaining the state, properties,

-and semantics of communication between a client and an input method.

-An input context is a combination of an input method, a locale

-specifying the encoding of the character strings to be returned,

-a client window, internal state information,

-and various layout or appearance characteristics.

-The input context concept somewhat matches for input the graphics context

-abstraction defined for graphics output.

-</para>

-<para>

-<!-- .LP -->

-One input context belongs to exactly one input method.

-Different input contexts may be associated with the same input method,

-possibly with the same client window.

-An 

-<type>XIC</type>

-is created with the

-<function>XCreateIC</function>

-function, providing an 

-<type>XIM</type>

-argument and affiliating the input context to the input method

-for its lifetime. 

-When an input method is closed with 

-<function>XCloseIM</function>,

-all of its affiliated input contexts should not be used any more

-(and should preferably be destroyed before closing the input method).

-</para>

-<para>

-<!-- .LP -->

-Considering the example of a client window with multiple text entry areas,

-the application programmer could, for example, choose to implement as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-As many input contexts are created as text entry areas, and the client

-will get the input accumulated on each context each time it looks up

-in that context.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A single context is created for a top-level window in the application.

-If such a window contains several text entry areas, 

-each time the user moves to another text entry area,

-the client has to indicate changes in the context.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-A range of choices can be made by application designers to use

-either a single or multiple input contexts,

-according to the needs of their application.

-</para>

-</sect3>

-<sect3 id="Getting_Keyboard_Input">

-<title>Getting Keyboard Input</title>

-<!-- .XS -->

-<!-- (SN Getting Keyboard Input -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To obtain characters from an input method,

-a client must call the function

-<function>XmbLookupString</function>

-or 

-<function>XwcLookupString</function>

-with an input context created from that input method.

-Both a locale and display are bound to an input method when it is opened,

-and an input context inherits this locale and display.

-Any strings returned by 

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>

-will be encoded in that locale. 

-</para>

-</sect3>

-<sect3 id="Focus_Management">

-<title>Focus Management</title>

-<!-- .XS -->

-<!-- (SN Focus Management -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-For each text entry area in which the

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>

-functions are used,

-there will be an associated input context.

-</para>

-<para>

-<!-- .LP -->

-When the application focus moves to a text entry area,

-the application must set the input context focus to the

-input context associated with that area.

-The input context focus is set by calling 

-<function>XSetICFocus</function>

-with the appropriate input context.

-</para>

-<para>

-<!-- .LP -->

-Also, when the application focus moves out of a text entry area, the

-application should unset the focus for the associated input context

-by calling

-<function>XUnsetICFocus</function>.

-As an optimization, if

-<function>XSetICFocus</function>

-is called successively on two different input contexts,

-setting the focus on the second 

-will automatically unset the focus on the first.

-</para>

-<para>

-<!-- .LP -->

-To set and unset the input context focus correctly,

-it is necessary to track application-level focus changes.

-Such focus changes do not necessarily correspond to X server focus changes.

-</para>

-<para>

-<!-- .LP -->

-If a single input context

-is being used to do input for

-multiple text entry areas, it will also be necessary

-to set the focus window of the

-input context whenever the focus window changes

-(see section 13.5.6.3).

-</para>

-</sect3>

-<sect3 id="Geometry_Management">

-<title>Geometry Management</title>

-<!-- .XS -->

-<!-- (SN Geometry Management -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-In most input method architectures 

-(on-the-spot being the notable exception),

-the input method will perform the display of its own data.

-To provide better visual locality,

-it is often desirable to have the input method areas embedded within a client.

-To do this,

-the client may need to allocate space for an input method.

-Xlib provides support that allows the size and position of input method

-areas to be provided by a client.

-The input method areas that are supported for geometry management

-are the status area and the preedit area.

-</para>

-<para>

-<!-- .LP -->

-The fundamental concept on which geometry management for input method windows

-is based is the proper division of responsibilities between the

-client (or toolkit) and the input method.

-The division of responsibilities is as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The client is responsible for the geometry of the input method window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The input method is responsible for the contents of the input method window.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-An input method is able to suggest a size to the client,

-but it cannot suggest a placement.

-Also the input method can only suggest a size.

-It does not determine the size,

-and it must accept the size it is given.

-</para>

-<para>

-<!-- .LP -->

-Before a client provides geometry management for an input method,

-it must determine if geometry management is needed.

-The input method indicates the need for geometry management 

-by setting 

-<symbol>XIMPreeditArea</symbol>

-or 

-<symbol>XIMStatusArea</symbol>

-in its 

-<structname>XIMStyles</structname>

-value returned by 

-<function>XGetIMValues</function>.

-When a client has decided that it will provide geometry management

-for an input method, 

-it indicates that decision by setting the

-<symbol>XNInputStyle</symbol>

-value in the 

-<type>XIC</type>.

-</para>

-<para>

-<!-- .LP -->

-After a client has established with the input method

-that it will do geometry management,

-the client must negotiate the geometry with the input method.

-The geometry is negotiated by the following steps:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The client suggests an area to the input method by setting the

-<symbol>XNAreaNeeded</symbol>

-value for that area.

-If the client has no constraints for the input method,

-it either will not suggest an area or will set the width and height to zero.

-Otherwise, it will set one of the values.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The client will get the <acronym>XIC</acronym> value 

-<symbol>XNAreaNeeded</symbol>.

-The input method will return its suggested size in this value.

-The input method should pay attention to any constraints suggested

-by the client.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The client sets the <acronym>XIC</acronym> value

-<symbol>XNArea</symbol>

-to inform the input method of the geometry of its window.  

-The client should try to honor the geometry requested by the input method.

-The input method must accept this geometry.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Clients doing geometry management must be aware that setting other

-<acronym>XIC</acronym> values may affect the geometry desired by an input method.

-For example, 

-<symbol>XNFontSet</symbol>

-and

-<symbol>XNLineSpace</symbol>

-may change the geometry desired by the input method.  

-</para>

-<para>

-<!-- .LP -->

-The table of <acronym>XIC</acronym> values (see section 13.5.6)

-indicates the values that can cause the desired geometry to change

-when they are set.

-It is the responsibility of the client to renegotiate the geometry

-of the input method window when it is needed.

-</para>

-<para>

-<!-- .LP -->

-In addition,

-a geometry management callback is provided

-by which an input method can initiate a geometry change.

-</para>

-</sect3>

-<sect3 id="Event_Filtering">

-<title>Event Filtering</title>

-<!-- .XS -->

-<!-- (SN Event Filtering -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A filtering mechanism is provided to allow input methods

-to capture X events transparently to clients.

-It is expected that toolkits (or clients) using

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>

-will call this filter at some point in the event processing mechanism

-to make sure that events needed by an input method can be filtered

-by that input method.

-</para>

-<para>

-<!-- .LP -->

-If there were no filter,

-a client could receive and discard events that are necessary

-for the proper functioning of an input method.

-The following provides a few examples of such events:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Expose events on preedit window in local mode.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Events may be used by an input method to communicate with an input server.

-Such input server protocol-related events have to be intercepted

-if one does not want to disturb client code.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Key events can be sent to a filter before they are bound

-to translations such as those the X Toolkit Intrinsics library provides.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Clients are expected to get the <acronym>XIC</acronym> value 

-<symbol>XNFilterEvents</symbol>

-and augment the event mask for the client window with that event mask.

-This mask may be zero.

-</para>

-</sect3>

-<sect3 id="Callbacks">

-<title>Callbacks</title>

-<!-- .XS -->

-<!-- (SN Callbacks -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-When an on-the-spot input method is implemented,

-only the client can insert or delete preedit data in place

-and possibly scroll existing text.

-This means that the echo of the keystrokes has to be achieved 

-by the client itself, tightly coupled with the input method logic.

-</para>

-<para>

-<!-- .LP -->

-When the user enters a keystroke,

-the client calls

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>.

-At this point, in the on-the-spot case,

-the echo of the keystroke in the preedit has not yet been done.

-Before returning to the client logic that handles the input characters,

-the look-up function

-must call the echoing logic to insert the new keystroke.

-If the keystrokes entered so far make up a character,

-the keystrokes entered need to be deleted,

-and the composed character will be returned.

-Hence, what happens is that, while being called by client code,

-the input method logic has to call back to the client before it returns.

-The client code, that is, a callback procedure,

-is called from the input method logic.

-</para>

-<para>

-<!-- .LP -->

-There are a number of cases where the input method logic has to

-call back the client.

-Each of those cases is associated with a well-defined callback action.

-It is possible for the client to specify, for each input context,

-what callback is to be called for each action.

-</para>

-<para>

-<!-- .LP -->

-There are also callbacks provided for feedback of status information

-and a callback to initiate a geometry request for an input method.

-</para>

-</sect3>

-<sect3 id="Visible_Position_Feedback_Masks">

-<title>Visible Position Feedback Masks</title>

-<!-- .XS -->

-<!-- (SN Visible Position Feedback Masks -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-In the on-the-spot input style, there is a problem when

-attempting to draw preedit strings that are longer than the

-available space.  Once the display area is exceeded, it is not

-clear how best to display the preedit string.

-The visible position feedback masks of

-<structname>XIMText</structname>

-help resolve this problem by allowing the input method to specify hints that

-indicate the essential portions of the preedit string.

-For example, such hints can help developers implement

-scrolling of a long preedit string within a short preedit display area.

-</para>

-</sect3>

-<sect3 id="Preedit_String_Management">

-<title>Preedit String Management</title>

-<!-- .XS -->

-<!-- (SN Preedit String Management -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-As highlighted before, the input method architecture provides

-preediting, which supports a type of preprocessor input composition.

-In this case, composition consists of interpreting a sequence

-of key events and returning a committed string via 

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>.

-This provides the basics for input methods.

-</para>

-<para>

-<!-- .LP -->

-In addition to preediting based on key events, a general framework

-is provided to give a client that desires it more advanced preediting based

-on the text within the client.  This framework is called 

-<emphasis remap='I'>string conversion</emphasis> and is provided using <acronym>XIC</acronym> values. 

-The fundamental concept of string conversion

-is to allow the input method to manipulate the client's

-text independent of any user preediting operation.

-</para>

-<para>

-<!-- .LP -->

-The need for string conversion is based on 

-language needs and input method capabilities.

-The following are some examples of string conversion:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Transliteration conversion provides language-specific conversions

-within the input method.

-In the case of Korean input, users wish to convert a Hangul string 

-into a Hanja string while in preediting, after preediting,

-or in other situations (for example, on a selected string).

-The conversion is triggered when the user

-presses a Hangul-to-Hanja key sequence (which may be input method specific).

-Sometimes the user may want to invoke the conversion after finishing

-preediting or on a user-selected string.  

-Thus, the string to be converted is in an application buffer, not in 

-the preedit area of the input method.  The string conversion services

-allow the client to request this transliteration conversion from the 

-input method.

-There are many other transliteration conversions defined for 

-various languages, for example, Kana-to-Kanji conversion in Japanese.

-<!-- .sp -->

-The key to remember is that transliteration conversions are triggered

-at the request of the user and returned to the client 

-immediately without affecting the preedit area of the input method.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Reconversion of a previously committed string or 

-a selected string is supported by many input methods as a 

-convenience to the user.

-For example, a user tends to mistype the commit key while

-preediting.  In that case, some input methods provide a special

-key sequence to request a ``reconvert'' operation on the 

-committed string, similiar to the undo facility provided by most

-text editors.

-Another example is where the user is proofreading a document 

-that has some misconversions from preediting and wants to correct

-the misconverted text.  Such reconversion is again triggered

-by the user invoking some special action, but reconversions should

-not affect the state of the preedit area.  

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Context-sensitive conversion is required for some languages

-and input methods that need to retrieve text that surrounds the

-current spot location (cursor position) of the client's buffer.

-Such text is needed when the preediting operation depends on 

-some surrounding characters (usually preceding the spot location).

-For example, 

-in Thai language input, certain character sequences may be invalid and

-the input method may want to check whether characters constitute a

-valid word.  Input methods that do such context-dependent

-checking need to retrieve the characters surrounding the current

-cursor position to obtain complete words.

-<!-- .sp -->

-Unlike other conversions, this conversion is not explicitly 

-requested by the user.

-Input methods that provide such context-sensitive conversion 

-continuously need to request context from the client, and any change

-in the context of the spot location may affect such conversions.

-The client's context would be needed if the user moves the cursor

-and starts editing again.

-<!-- .sp -->

-For this reason, an input method supporting this type of conversion

-should take notice of when the client calls

-<function>XmbResetIC</function>

-or

-<function>XwcResetIC</function>,

-which is usually an indication of a context change.  

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Context-sensitive conversions just need a copy of the client's text,

-while other conversions replace the client's text with new text

-to achieve the reconversion or transliteration.   Yet in all

-cases the result of a conversion, either immediately or via preediting,

-is returned by the

-<function>XmbLookupString</function>

-and

-<function>XwcLookupString</function>

-functions.

-</para>

-<para>

-<!-- .LP -->

-String conversion support is dependent on the availability of the 

-<symbol>XNStringConversion</symbol>

-or 

-<symbol>XNStringConversionCallback</symbol>

-<acronym>XIC</acronym> values.

-Because the input method may not support string conversions,

-clients have to query the availability of string conversion

-operations by checking the supported <acronym>XIC</acronym> values list by calling

-<function>XGetIMValues</function>

-with the

-<symbol>XNQueryICValuesList</symbol>

-IM value.

-</para>

-<para>

-<!-- .LP -->

-The difference between these two values is whether the

-conversion is invoked by the client or the input method.  

-The 

-<symbol>XNStringConversion</symbol>

-<acronym>XIC</acronym> value is used by clients to request 

-a string conversion from the input method.  The client

-is responsible for determining which events are used 

-to trigger the string conversion and whether the string to be

-converted should be copied or deleted.  The type of conversion

-is determined by the input method; the client can only 

-pass the string to be converted.  The client is guaranteed that

-no

-<symbol>XNStringConversionCallback</symbol>

-will be issued when this value is set; thus, the client need

-only set one of these values.

-</para>

-<para>

-<!-- .LP -->

-The

-<symbol>XNStringConversionCallback</symbol>

-<acronym>XIC</acronym> value is used by the client to notify the input method that

-it will accept requests from the input method for string conversion.

-If this value is set,

-it is the input method's responsibility to determine which

-events are used to trigger the string conversion.

-When such events occur, the input method issues a call to the

-client-supplied procedure to retrieve the string to be converted.  The client's

-callback procedure is notified whether to copy or delete the string and 

-is provided with hints as to the amount of text needed.

-The

-<structname>XIMStringConversionCallbackStruct</structname>

-specifies which text should be passed back to the input method.

-</para>

-<para>

-<!-- .LP -->

-Finally, the input method may call the client's 

-<symbol>XNStringConversionCallback</symbol>

-procedure multiple times if the string returned from the callback is

-not sufficient to perform a successful conversion.   The arguments

-to the client's procedure allow the input method to define a

-position (in character units) relative to the client's cursor position 

-and the size of the text needed.  By varying the position and size of

-the desired text in subsequent callbacks, the input method can retrieve 

-additional text.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-</sect2>

-<sect2 id="Input_Method_Management">

-<title>Input Method Management</title>

-<!-- .XS -->

-<!-- (SN Input Method Management -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The interface to input methods might appear to be simply creating

-an input method

-(<function>XOpenIM</function>)

-and freeing an input method

-(<function>XCloseIM</function>).

-However, input methods may 

-require complex communication with input method servers (IM servers),

-for example:

-</para>

-

-<itemizedlist>

-  <listitem>

-    <para>

-If the X server, IM server, and X clients are started asynchronously,

-some clients may attempt to connect to the IM server before it is

-fully operational, and fail.

-Therefore, some mechanism is needed to allow clients to detect when an IM 

-server has started.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-It is up to clients to decide what should be done when an IM server is 

-not available (for example, wait, or use some other IM server).

-</para>

-<para>

-<!-- .LP -->

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Some input methods may allow the underlying IM server to be switched. 

-Such customization may be desired without restarting the entire client.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-To support management of input methods in these cases, the following 

-functions are provided:

-</para>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><function>XRegisterIMInstantiateCallback</function></entry>

-      <entry>This function allows clients to register a callback procedure

-      to be called when Xlib detects that an IM server is up and available.</entry>

-    </row>

-    <row>

-      <entry><function>XOpenIM</function></entry>

-      <entry>A client calls this function as a result of the callback procedure

-      being called.</entry>

-    </row>

-    <row>

-      <entry><function>XSetIMValues</function>, <function>XSetICValues</function></entry>

-      <entry>These functions use the <acronym>XIM</acronym> and <acronym>XIC</acronym> values,

-      <symbol>XNDestroyCallback</symbol>,

-      to allow a client 

-      to register a callback procedure to be called when Xlib detects that

-      an IM server that was associated with an opened 

-      input method is no longer available.

-      In addition, this function can be used to switch IM servers for those input 

-      methods that support such functionality.  The IM value for switching IM 

-      servers is implementation-dependent; see the description below about

-      switching IM servers.</entry>

-    </row>

-    <row>

-      <entry><function>XUnregisterIMInstantiateCallback</function></entry>

-      <entry>This function removes a callback procedure registered by the client.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-Input methods that support switching of IM servers may exhibit some

-side-effects:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The input method will ensure that any new IM server supports any of the 

-input styles being used by input contexts already associated with the

-input method.

-However, the list of supported input styles may be different.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Geometry management requests on previously created input contexts

-may be initiated by the new IM server.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-</para>

-<sect3 id="Hot_Keys">

-<title>Hot Keys</title>

-<!-- .XS -->

-<!-- (SN Hot Keys -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Some clients need to guarantee which keys can be used to escape from the

-input method, regardless of the input method state;

-for example, the client-specific Help key or the keys to move the

-input focus.

-The HotKey mechanism allows clients 

-to specify a set of keys for this purpose.  However, the input 

-method might not allow clients to specify hot keys.

-Therefore, clients have to query support of hot keys by checking the

-supported <acronym>XIC</acronym> values list by calling

-<function>XGetIMValues</function>

-with the

-<symbol>XNQueryICValuesList</symbol>

-IM value.

-When the hot keys specified conflict with the key bindings of the 

-input method, hot keys take precedence over the key bindings of the input 

-method.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Preedit_State_Operation">

-<title>Preedit State Operation</title>

-<!-- .XS -->

-<!-- (SN Preedit State Operation -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-An input method may have several internal states, depending on its

-implementation and the locale.  However, one state that is

-independent of locale and implementation is whether the input method

-is currently performing a preediting operation.

-Xlib provides the ability for an application to manage the preedit state

-programmatically.  Two methods are provided for

-retrieving the preedit state of an input context.

-One method is to query the state by calling

-<function>XGetICValues</function>

-with the

-<symbol>XNPreeditState</symbol>

-<acronym>XIC</acronym> value.

-Another method is to receive notification whenever

-the preedit state is changed.  To receive such notification,

-an application needs to register a callback by calling

-<function>XSetICValues</function>

-with the

-<symbol>XNPreeditStateNotifyCallback</symbol>

-<acronym>XIC</acronym> value. 

-In order to change the preedit state programmatically, an application 

-needs to call 

-<function>XSetICValues</function>

-with

-<symbol>XNPreeditState</symbol>.

-</para>

-<para>

-<!-- .LP -->

-Availability of the preedit state is input method dependent.  The input 

-method may not provide the ability to set the state or to

-retrieve the state programmatically.  Therefore, clients have to 

-query availability of preedit state operations by checking the 

-supported <acronym>XIC</acronym> values list by calling

-<function>XGetIMValues</function>

-with the

-<symbol>XNQueryICValuesList</symbol>

-IM value.

-</para>

-</sect3>

-</sect2>

-<sect2 id="Input_Method_Functions">

-<title>Input Method Functions</title>

-<!-- .XS -->

-<!-- (SN Input Method Functions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To open a connection, use

-<function>XOpenIM</function>.

-<indexterm significance="preferred"><primary>XOpenIM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XIM <function>XOpenIM</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>

-  <paramdef>char<parameter> *res_name</parameter></paramdef>

-  <paramdef>char<parameter> *res_class</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>res_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the full resource name of the application.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>res_class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the full class name of the application.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XOpenIM</function>

-function opens an input method, 

-matching the current locale and modifiers specification.

-Current locale and modifiers are bound to the input method at opening time.

-The locale associated with an input method cannot be changed dynamically.

-This implies that the strings returned by

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>,

-for any input context affiliated with a given input method,

-will be encoded in the locale current at the time the input method is opened.

-</para>

-<para>

-<!-- .LP -->

-The specific input method to which this call will be routed

-is identified on the basis of the current locale. 

-<function>XOpenIM</function>

-will identify a default input method corresponding to the

-current locale.

-That default can be modified using 

-<function>XSetLocaleModifiers</function>

-for the input method modifier.

-</para>

-<para>

-<!-- .LP -->

-The db argument is the resource database to be used by the input method

-for looking up resources that are private to the input method.

-It is not intended that this database be used to look

-up values that can be set as IC values in an input context.

-If db is NULL,

-no database is passed to the input method.

-</para>

-<para>

-<!-- .LP -->

-The res_name and res_class arguments specify the resource name 

-and class of the application. 

-They are intended to be used as prefixes by the input method

-when looking up resources that are common to all input contexts

-that may be created for this input method.

-The characters used for resource names and classes must be in the

-X Portable Character Set.

-The resources looked up are not fully specified

-if res_name or res_class is NULL.

-</para>

-<para>

-<!-- .LP -->

-The res_name and res_class arguments are not assumed to exist beyond

-the call to

-<function>XOpenIM</function>.

-The specified resource database is assumed to exist for the lifetime

-of the input method.

-</para>

-<para>

-<!-- .LP -->

-<function>XOpenIM</function>

-returns NULL if no input method could be opened.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To close a connection, use

-<function>XCloseIM</function>.

-<indexterm significance="preferred"><primary>XCloseIM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XCloseIM</function></funcdef>

-  <paramdef>XIM<parameter> im</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>im</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input method.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCloseIM</function>

-function closes the specified input method.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set input method attributes, use

-<function>XSetIMValues</function>.

-<indexterm significance="preferred"><primary>XSetIMValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XSetIMValues</function></funcdef>

-  <paramdef>XIM<parameter> im</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>im</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input method.

-<!-- .ds Al \ to set <acronym>XIM</acronym> values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable-length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetIMValues</function>

-function presents a variable argument list programming interface

-for setting attributes of the specified input method.

-It returns NULL if it succeeds;

-otherwise,

-it returns the name of the first argument that could not be set.

-Xlib does not attempt to set arguments from the supplied list that

-follow the failed argument;

-all arguments in the list preceding the failed argument have been set

-correctly.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To query an input method, use 

-<function>XGetIMValues</function>.

-<indexterm significance="preferred"><primary>XGetIMValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XGetIMValues</function></funcdef>

-  <paramdef>XIM<parameter> im</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>im</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input method.

-<!-- .ds Al \ to get XIM values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetIMValues</function>

-function presents a variable argument list programming interface

-for querying properties or features of the specified input method.

-This function returns NULL if it succeeds;

-otherwise,

-it returns the name of the first argument that could not be obtained.

-</para>

-<para>

-<!-- .LP -->

-Each <acronym>XIM</acronym> value argument (following a name) must point to

-a location where the <acronym>XIM</acronym> value is to be stored.

-That is, if the <acronym>XIM</acronym> value is of type T,

-the argument must be of type T*.

-If T itself is a pointer type,

-then

-<function>XGetIMValues</function>

-allocates memory to store the actual data,

-and the client is responsible for freeing this data by calling

-<function>XFree</function>

-with the returned pointer.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the display associated with an input method, use

-<function>XDisplayOfIM</function>.

-<indexterm significance="preferred"><primary>XDisplayOfIM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Display *<function>XDisplayOfIM</function></funcdef>

-  <paramdef>XIM<parameter> im</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>im</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input method.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDisplayOfIM</function>

-function returns the display associated with the specified input method.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the locale associated with an input method, use

-<function>XLocaleOfIM</function>.

-<indexterm significance="preferred"><primary>XLocaleOfIM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XLocaleOfIM</function></funcdef>

-  <paramdef>XIM<parameter> im</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>im</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input method.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLocaleOfIM</function>

-function returns the locale associated with the specified input method.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To register an input method instantiate callback, use

-<function>XRegisterIMInstantiateCallback</function>.

-<indexterm significance="preferred"><primary>XRegisterIMInstantiateCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XRegisterIMInstantiateCallback</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>

-  <paramdef>char<parameter> *res_name</parameter></paramdef>

-  <paramdef>char<parameter> *res_class</parameter></paramdef>

-  <paramdef>XIMProc<parameter> callback</parameter></paramdef>

-  <paramdef>XPointer<parameter> *client_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>res_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the full resource name of the application.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>res_class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the full class name of the application.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>callback</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the input method instantiate callback.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRegisterIMInstantiateCallback</function>

-function registers a callback to be invoked whenever a new input method

-becomes available for the specified display that matches the current

-locale and modifiers.

-</para>

-<para>

-<!-- .LP -->

-The function returns 

-<symbol>True</symbol>

- if it succeeds; otherwise, it returns 

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-The generic prototype is as follows:

-<indexterm significance="preferred"><primary>IMInstantiateCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>IMInstantiateCallback</replaceable></function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Not used for this callback and always passed as NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-To unregister an input method instantiation callback, use

-<function>XUnregisterIMInstantiateCallback</function>.

-<indexterm significance="preferred"><primary>XUnregisterIMInstantiateCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XUnregisterIMInstantiateCallback</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>

-  <paramdef>char<parameter> *res_name</parameter></paramdef>

-  <paramdef>char<parameter> *res_class</parameter></paramdef>

-  <paramdef>XIMProc<parameter> callback</parameter></paramdef>

-  <paramdef>XPointer<parameter> *client_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>res_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the full resource name of the application.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>res_class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the full class name of the application.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>callback</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a pointer to the input method instantiate callback.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUnregisterIMInstantiateCallback</function>

-function removes an input method instantiation callback previously

-registered.

-The function returns

-<symbol>True</symbol>

-if it succeeds; otherwise, it returns 

-<symbol>False</symbol>.

-</para>

-</sect2>

-<sect2 id="Input_Method_Values">

-<title>Input Method Values</title>

-<!-- .XS -->

-<!-- (SN Input Method Values -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The following table describes how <acronym>XIM</acronym> values are interpreted

-by an input method.

-The first column lists the <acronym>XIM</acronym> values.

-The second column indicates how each of the <acronym>XIM</acronym> values 

-are treated by that input style.

-</para>

-<para>

-<!-- .LP -->

-</para>

-<para>

-<!-- .LP -->

-The following keys apply to this table.

-</para>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry>Key</entry>

-      <entry>Explanation</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>D</entry>

-      <entry>This value may be set using

-      <function>XSetIMValues</function>.

-      If it is not set,

-      a default is provided.</entry>

-    </row>

-    <row>

-      <entry>S</entry>

-      <entry>This value may be set using <function>XSetIMValues</function>.</entry>

-    </row>

-    <row>

-      <entry>G</entry>

-      <entry>This value may be read using <function>XGetIMValues</function>.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<!-- .LP -->

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry><acronym>XIM</acronym> Value</entry>

-      <entry>Key</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry><symbol>XNQueryInputStyle</symbol></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNResourceName</symbol></entry>

-      <entry>D-S-G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNResourceClass</symbol></entry>

-      <entry>D-S-G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNDestroyCallback</symbol></entry>

-      <entry>D-S-G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNQueryIMValuesList</symbol></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNQueryICValuesList</symbol></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNVisiblePosition</symbol></entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry><symbol>XNR6PreeditCallback</symbol></entry>

-      <entry>D-S-G</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-<symbol>XNR6PreeditCallback</symbol>

-is obsolete and its use is not recommended (see section 13.5.4.6).

-</para>

-

-<sect3 id="Query_Input_Style">

-<title>Query Input Style</title>

-<!-- .XS -->

-<!-- (SN Query Input Style -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A client should always query the input method to determine which input 

-styles are supported.

-The client should then find an input style it is capable of supporting.

-</para>

-<para>

-<!-- .LP -->

-If the client cannot find an input style that it can support,

-it should negotiate with the user the continuation of the program

-(exit, choose another input method, and so on).

-</para>

-<para>

-<!-- .LP -->

-The argument value must be a pointer to a location

-where the returned value will be stored.

-The returned value is a pointer to a structure of type

-<structname>XIMStyles</structname>.

-Clients are responsible for freeing the 

-<structname>XIMStyles</structname>

-structure.

-To do so, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XIMStyles</structname>

-structure is defined as follows:

-</para>

-

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMStyle</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStyles</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-typedef unsigned long XIMStyle;

-

-

-#define     XIMPreeditArea             0x0001L

-#define     XIMPreeditCallbacks        0x0002L

-#define     XIMPreeditPosition         0x0004L

-#define     XIMPreeditNothing          0x0008L

-#define     XIMPreeditNone             0x0010L

-

-#define     XIMStatusArea              0x0100L

-#define     XIMStatusCallbacks         0x0200L

-#define     XIMStatusNothing           0x0400L

-#define     XIMStatusNone              0x0800L

-

-typedef struct {

-      unsigned short count_styles;

-      XIMStyle * supported_styles;

-} XIMStyles;

-

-</literallayout>

-

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-An 

-<structname>XIMStyles</structname>

-structure contains the number of input styles supported

-in its count_styles field.

-This is also the size of the supported_styles array.

-</para>

-<para>

-<!-- .LP -->

-The supported styles is a list of bitmask combinations,

-which indicate the combination of styles for each of the areas supported.

-These areas are described later.

-Each element in the list should select one of the bitmask values for

-each area.

-The list describes the complete set of combinations supported.

-Only these combinations are supported by the input method.

-</para>

-<para>

-<!-- .LP -->

-The preedit category defines what type of support is provided

-by the input method for preedit information.

-</para>

-<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>XIMPreeditArea</symbol></entry>

-      <entry>If chosen,

-      the input method would require the client to provide some area values

-      for it to do its preediting.

-      Refer to <acronym>XIC</acronym> values 

-      <symbol>XNArea</symbol>

-      and

-      <symbol>XNAreaNeeded</symbol>.</entry>

-    </row>

-    <row>

-      <entry><symbol>XIMPreeditPosition</symbol></entry>

-      <entry>If chosen,

-      the input method would require the client to provide positional values. 

-      Refer to <acronym>XIC</acronym> values 

-      <symbol>XNSpotLocation</symbol>

-      and

-      <symbol>XNFocusWindow</symbol>.</entry>

-    </row>

-    <row>

-      <entry><symbol>XIMPreeditCallbacks</symbol></entry>

-      <entry>If chosen,

-      the input method would require the client to define the set of preedit callbacks.

-      Refer to <acronym>XIC</acronym> values 

-      <symbol>XNPreeditStartCallback</symbol>,

-      <symbol>XNPreeditDoneCallback</symbol>,

-      <symbol>XNPreeditDrawCallback</symbol>,

-      and

-      <symbol>XNPreeditCaretCallback</symbol>.</entry>

-    </row>

-    <row>

-      <entry><symbol>XIMPreeditNothing</symbol></entry>

-      <entry>If chosen, the input method can function without any preedit values.</entry>

-    </row>

-    <row>

-      <entry><symbol>XIMPreeditNone</symbol></entry>

-      <entry>The input method does not provide any preedit feedback.

-      Any preedit value is ignored.

-      This style is mutually exclusive with the other preedit styles.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-The status category defines what type of support is provided

-by the input method for status information.

-</para>

-<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>XIMStatusArea</symbol></entry>

-      <entry>The input method requires the client to provide

-      some area values for it to do its status feedback.

-      See

-      <symbol>XNArea</symbol>

-      and

-      <symbol>XNAreaNeeded</symbol>.</entry>

-    </row>

-    <row>

-      <entry><symbol>XIMStatusCallbacks</symbol></entry>

-      <entry>The input method requires the client to define the set of status callbacks,

-      <symbol>XNStatusStartCallback</symbol>,

-      <symbol>XNStatusDoneCallback</symbol>,

-      and

-      <symbol>XNStatusDrawCallback</symbol>.</entry>

-    </row>

-    <row>

-      <entry><symbol>XIMStatusNothing</symbol></entry>

-      <entry>The input method can function without any status values.</entry>

-    </row>

-    <row>

-      <entry><symbol>XIMStatusNone</symbol></entry>

-      <entry>The input method does not provide any status feedback.

-      If chosen, any status value is ignored.

-      This style is mutually exclusive with the other status styles.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-</sect3>

-<sect3 id="Resource_Name_and_Class_c">

-<title>Resource Name and Class</title>

-<!-- .XS -->

-<!-- (SN Resource Name and Class -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNResourceName</symbol>

-and

-<symbol>XNResourceClass</symbol>

-arguments are strings that specify the full name and class

-used by the input method.

-These values should be used as prefixes for the name and class

-when looking up resources that may vary according to the input method.

-If these values are not set,

-the resources will not be fully specified.

-</para>

-<para>

-<!-- .LP -->

-It is not intended that values that can be set as <acronym>XIM</acronym> values be

-set as resources.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Destroy_Callback">

-<title>Destroy Callback</title>

-<!-- .XS -->

-<!-- (SN Destroy Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The 

-<symbol>XNDestroyCallback</symbol>

-argument is a pointer to a structure of type

-<structname>XIMCallback</structname>.

-<symbol>XNDestroyCallback</symbol>

-is triggered when an input method stops its service for any reason. 

-After the callback is invoked, the input method is closed and the

-associated input context(s) are destroyed by Xlib.

-Therefore, the client should not call

-<function>XCloseIM</function>

-or

-<function>XDestroyIC</function>.

-</para>

-<para>

-<!-- .LP -->

-The generic prototype of this callback function is as follows:

-<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>DestroyCallback</replaceable></function></funcdef>

-  <paramdef>XIM<parameter> im</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>im</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input method.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Not used for this callback and always passed as NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-A DestroyCallback is always called with a NULL call_data argument.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Query_IM_IC_Values_List">

-<title>Query IM/IC Values List</title>

-<!-- .XS -->

-<!-- (SN Query IM/IC Values List -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<symbol>XNQueryIMValuesList</symbol>

-and

-<symbol>XNQueryICValuesList</symbol>

-are used to query about <acronym>XIM</acronym> and <acronym>XIC</acronym> values supported by the input method.

-</para>

-<para>

-<!-- .LP -->

-The argument value must be a pointer to a location where the returned

-value will be stored.  The returned value is a pointer to a structure

-of type

-<structname>XIMValuesList</structname>.

-Clients are responsible for freeing the 

-<structname>XIMValuesList</structname>

-structure.

-To do so, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XIMValuesList</structname>

-structure is defined as follows:

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-     unsigned short count_values;

-     char **supported_values;

-} XIMValuesList;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-</sect3>

-<sect3 id="Visible_Position">

-<title>Visible Position</title>

-<!-- .XS -->

-<!-- (SN Visible Position -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The 

-<symbol>XNVisiblePosition</symbol>

-argument indicates whether the visible position masks of 

-<type>XIMFeedback</type>

-in

-<structname>XIMText</structname>

-are available.

-</para>

-<para>

-<!-- .LP -->

-The argument value must be a pointer to a location where the returned

-value will be stored.  The returned value is of type

-<type>Bool</type>.

-If the returned value is

-<symbol>True</symbol>,

-the input method uses the visible position masks of

-<type>XIMFeedback</type>

-in

-<structname>XIMText</structname>;

-otherwise, the input method does not use the masks.

-</para>

-<para>

-<!-- .LP -->

-Because this <acronym>XIM</acronym> value is optional, a client should call

-<function>XGetIMValues</function>

-with argument

-<symbol>XNQueryIMValuesList</symbol>

-before using this argument.

-If the 

-<symbol>XNVisiblePosition</symbol>

-does not exist in the IM values list returned from 

-<symbol>XNQueryIMValuesList</symbol>,

-the visible position masks of

-<type>XIMFeedback</type>

-in

-<structname>XIMText</structname>

-are not used to indicate the visible position.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Preedit_Callback_Behavior">

-<title>Preedit Callback Behavior</title>

-<!-- .XS -->

-<!-- (SN Preedit Callback Behavior -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNR6PreeditCallback</symbol>

-argument originally included in the X11R6 specification has been

-deprecated.\(dg

-<!-- .\" If XNR6PreeditCallbackBehavior is not deprecated, then its type -->

-<!-- .\" should be changed from *Bool to Bool. -->

-<!-- .FS \(dg -->

-During formulation of the X11R6 specification, the behavior of

-the R6 PreeditDrawCallbacks was going to differ significantly from

-that of the R5 callbacks.

-Late changes to the specification converged the R5 and R6 behaviors,

-eliminating the need for

-<symbol>XNR6PreeditCallback</symbol>.

-Unfortunately, this argument was not removed from the R6 specification

-before it was published.

-<!-- .FE -->

-</para>

-<para>

-<!-- .LP -->

-The 

-<symbol>XNR6PreeditCallback</symbol>

-argument indicates whether the behavior of preedit callbacks regarding

-<structname>XIMPreeditDrawCallbackStruct</structname>

-values follows Release 5 or Release 6 semantics.

-</para>

-<para>

-<!-- .LP -->

-The value is of type

-<type>Bool</type>.

-When querying for

-<symbol>XNR6PreeditCallback</symbol>,

-if the returned value is

-<symbol>True</symbol>,

-the input method uses the Release 6 behavior;

-otherwise, it uses the Release 5 behavior.

-The default value is

-<symbol>False</symbol>.

-In order to use Release 6 semantics, the value of

-<symbol>XNR6PreeditCallback</symbol>

-must be set to

-<symbol>True</symbol>.

-</para>

-<para>

-<!-- .LP -->

-Because this <acronym>XIM</acronym> value is optional, a client should call

-<function>XGetIMValues</function>

-with argument

-<symbol>XNQueryIMValuesList</symbol>

-before using this argument.

-If the

-<symbol>XNR6PreeditCallback</symbol>

-does not exist in the IM values list returned from

-<symbol>XNQueryIMValuesList</symbol>,

-the PreeditCallback behavior is Release 5 semantics.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-</sect2>

-<sect2 id="Input_Context_Functions">

-<title>Input Context Functions</title>

-<!-- .XS -->

-<!-- (SN Input Context Functions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-An input context is an abstraction that is used to contain both the data

-required (if any) by an input method and the information required

-to display that data.

-There may be multiple input contexts for one input method.

-The programming interfaces for creating, reading, or modifying

-an input context use a variable argument list.

-The name elements of the argument lists are referred to as <acronym>XIC</acronym> values.

-It is intended that input methods be controlled by these <acronym>XIC</acronym> values.

-As new <acronym>XIC</acronym> values are created,

-they should be registered with the X Consortium.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create an input context, use

-<function>XCreateIC</function>.

-<indexterm significance="preferred"><primary>XCreateIC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XIC <function>XCreateIC</function></funcdef>

-  <paramdef>XIM<parameter> im</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>im</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input method.

-<!-- .ds Al \ to set <acronym>XIC</acronym> values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateIC</function>

-function creates a context within the specified input method.

-</para>

-<para>

-<!-- .LP -->

-Some of the arguments are mandatory at creation time, and

-the input context will not be created if those arguments are not provided.

-The mandatory arguments are the input style and the set of text callbacks

-(if the input style selected requires callbacks).

-All other input context values can be set later.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateIC</function>

-returns a NULL value if no input context could be created.

-A NULL value could be returned for any of the following reasons:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-A required argument was not set.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A read-only argument was set (for example,

-<symbol>XNFilterEvents</symbol>).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The argument name is not recognized.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The input method encountered an input method implementation-dependent error.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-<function>XCreateIC</function>

-can generate

-<errorname>BadAtom</errorname>,

-<errorname>BadColor</errorname>,

-<errorname>BadPixmap</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To destroy an input context, use

-<function>XDestroyIC</function>.

-<indexterm significance="preferred"><primary>XDestroyIC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XDestroyIC</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XDestroyIC</function>

-destroys the specified input context.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To communicate to and synchronize with input method

-for any changes in keyboard focus from the client side,

-use 

-<function>XSetICFocus</function>

-and

-<function>XUnsetICFocus</function>.

-<indexterm significance="preferred"><primary>XSetICFocus</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetICFocus</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetICFocus</function>

-function allows a client to notify an input method that the focus window

-attached to the specified input context has received keyboard focus.

-The input method should take action to provide appropriate feedback.

-Complete feedback specification is a matter of user interface policy.

-</para>

-<para>

-<!-- .LP -->

-Calling

-<function>XSetICFocus</function>

-does not affect the focus window value.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-<indexterm significance="preferred"><primary>XUnsetICFocus</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XUnsetICFocus</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUnsetICFocus</function>

-function allows a client to notify an input method that the specified input context

-has lost the keyboard focus and that no more input is expected on the focus window

-attached to that input context.

-The input method should take action to provide appropriate feedback.

-Complete feedback specification is a matter of user interface policy.

-</para>

-<para>

-<!-- .LP -->

-Calling

-<function>XUnsetICFocus</function>

-does not affect the focus window value;

-the client may still receive 

-events from the input method that are directed to the focus window.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To reset the state of an input context to its initial state, use

-<function>XmbResetIC</function>

-or

-<function>XwcResetIC</function>.

-<indexterm significance="preferred"><primary>XmbResetIC</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcResetIC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XmbResetIC</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>wchar_t *<function>XwcResetIC</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-When

-<symbol>XNResetState</symbol>

-is set to

-<symbol>XIMInitialState</symbol>,

-<function>XmbResetIC</function>

-and

-<function>XwcResetIC</function>

-reset an input context to its initial state;

-when

-<symbol>XNResetState</symbol>

-is set to

-<symbol>XIMPreserveState</symbol>,

-the current input context state is preserved.

-In both cases, any input pending on that context is deleted.

-The input method is required to clear the preedit area, if any,

-and update the status accordingly.

-Calling 

-<function>XmbResetIC</function>

-or

-<function>XwcResetIC</function>

-does not change the focus.

-</para>

-<para>

-<!-- .LP -->

-The return value of

-<function>XmbResetIC</function>

-is its current preedit string as a multibyte string.

-If there is any preedit text drawn or visible to the user,

-then these procedures must return a non-NULL string.

-If there is no visible preedit text, 

-then it is input method implementation-dependent 

-whether these procedures return a non-NULL string or NULL.

-</para>

-<para>

-<!-- .LP -->

-The client should free the returned string by calling

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the input method associated with an input context, use

-<function>XIMOfIC</function>.

-<indexterm significance="preferred"><primary>XIMOfIC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XIM <function>XIMOfIC</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XIMOfIC</function>

-function returns the input method associated with the specified input context.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-Xlib provides two functions for setting and reading <acronym>XIC</acronym> values, respectively,

-<function>XSetICValues</function>

-and

-<function>XGetICValues</function>.

-Both functions have a variable-length argument list.

-In that argument list, any <acronym>XIC</acronym> value's name must be denoted

-with a character string using the X Portable Character Set.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set <acronym>XIC</acronym> values, use

-<function>XSetICValues</function>.

-<indexterm significance="preferred"><primary>XSetICValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XSetICValues</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-<!-- .ds Al \ to set <acronym>XIC</acronym> values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetICValues</function>

-function returns NULL if no error occurred; 

-otherwise,

-it returns the name of the first argument that could not be set.

-An argument might not be set for any of the following reasons:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The argument is read-only (for example,

-<symbol>XNFilterEvents</symbol>).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The argument name is not recognized.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-An implementation-dependent error occurs.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Each value to be set must be an appropriate datum,

-matching the data type imposed by the semantics of the argument.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetICValues</function>

-can generate

-<errorname>BadAtom</errorname>,

-<errorname>BadColor</errorname>,

-<errorname>BadCursor</errorname>,

-<errorname>BadPixmap</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain <acronym>XIC</acronym> values, use

-<function>XGetICValues</function>.

-<indexterm significance="preferred"><primary>XGetICValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XGetICValues</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-<!-- .ds Al \ to get XIC values -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      ...

-    </term>

-    <listitem>

-      <para>

-Specifies the variable length argument list(Al.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetICValues</function>

-function returns NULL if no error occurred; otherwise,

-it returns the name of the first argument that could not be obtained.

-An argument could not be obtained for any of the following reasons:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The argument name is not recognized.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The input method encountered an implementation-dependent error.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-Each IC attribute value argument (following a name) must point to

-a location where the IC value is to be stored.

-That is, if the IC value is of type T,

-the argument must be of type T*.

-If T itself is a pointer type,

-then

-<function>XGetICValues</function>

-allocates memory to store the actual data,

-and the client is responsible for freeing this data by calling

-<function>XFree</function>

-with the returned pointer.

-The exception to this rule is for an IC value of type

-<type>XVaNestedList</type>

-(for preedit and status attributes).

-In this case,  the argument must also be of type

-<type>XVaNestedList</type>.

-Then, the rule of changing type T to T* and freeing the allocated data

-applies to each element of the nested list.

-</para>

-</sect2>

-<sect2 id="Input_Context_Values">

-<title>Input Context Values</title>

-<!-- .XS -->

-<!-- (SN Input Context Values -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The following tables describe how <acronym>XIC</acronym> values are interpreted

-by an input method depending on the input style chosen by the 

-user.

-</para>

-<para>

-<!-- .LP -->

-The first column lists the <acronym>XIC</acronym> values.

-The second column indicates which values are involved in affecting,

-negotiating, and setting the geometry of the input method windows.

-The subentries under the third column indicate the different

-input styles that are supported.

-Each of these columns indicates how each of the <acronym>XIC</acronym> values 

-are treated by that input style.

-</para>

-<para>

-<!-- .LP -->

-The following keys apply to these tables.

-</para>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry>Key</entry>

-      <entry>Explanation</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>C</entry>

-      <entry>This value must be set with <function>XCreateIC</function>.</entry>

-    </row>

-    <row>

-      <entry>D</entry>

-      <entry>This value may be set using 

-      <function>XCreateIC</function>.>

-      If it is not set,>

-      a default is provided.</entry>

-    </row>

-    <row>

-      <entry>G</entry>

-      <entry>This value may be read using 

-      <function>XGetICValues</function>.</entry>

-    </row>

-    <row>

-      <entry>GN</entry>

-      <entry>This value may cause geometry negotiation when its value is set by means of

-      <function>XCreateIC</function>

-      or

-      <function>XSetICValues</function>.</entry>

-    </row>

-    <row>

-      <entry>GR</entry>

-      <entry>This value will be the response of the input method when any 

-      GN value is changed.</entry>

-    </row>

-    <row>

-      <entry>GS</entry>

-      <entry>This value will cause the geometry of the input method window to be set.</entry>

-    </row>

-    <row>

-      <entry>O</entry>

-      <entry>This value must be set once and only once.

-      It need not be set at create time.</entry>

-    </row>

-    <row>

-      <entry>S</entry>

-      <entry>This value may be set with

-      <function>XSetICValues</function>.</entry>

-    </row>

-    <row>

-      <entry>Ignored</entry>

-      <entry>This value is ignored by the input method for the given input style.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<!-- .LP -->

-<informaltable>

-  <tgroup cols='7' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <colspec colname='c4'/>

-  <colspec colname='c5'/>

-  <colspec colname='c6'/>

-  <colspec colname='c7'/>

-  <tbody>

-    <row>

-      <entry><acronym>XIC</acronym> Value</entry>

-      <entry>Geometry Mangement</entry>

-      <entry>Preedit Callback</entry>

-      <entry>Preedit Position</entry>

-      <entry>Input Style Preedit Area</entry>

-      <entry>Preedit Nothing</entry>

-      <entry>Preedit None</entry>

-    </row>

-    <row>

-      <entry>Input Style</entry>

-      <entry></entry>

-      <entry>C-G</entry>

-      <entry>C-G</entry>

-      <entry>C-G</entry>

-      <entry>C-G</entry>

-      <entry>C-G</entry>

-    </row>

-    <row>

-      <entry>Client Window</entry>

-      <entry></entry>

-      <entry>O-G</entry>

-      <entry>O-G</entry>

-      <entry>O-G</entry>

-      <entry>O-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Focus Window</entry>

-      <entry>GN</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Resource Name</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Resource Class</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Geometry Callback</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Filter Events</entry>

-      <entry></entry>

-      <entry>G</entry>

-      <entry>G</entry>

-      <entry>G</entry>

-      <entry>G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Destroy Callback</entry>

-      <entry></entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-    </row>

-    <row>

-      <entry>String Conversion Callback</entry>

-      <entry></entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-    </row>

-    <row>

-      <entry>String Conversion</entry>

-      <entry></entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-    </row>

-    <row>

-      <entry>Reset State</entry>

-      <entry></entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>HotKey</entry>

-      <entry></entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>HotKeyState</entry>

-      <entry></entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry><function>Preedit</function></entry>

-    </row>

-    <row>

-      <entry>Area</entry>

-      <entry>GS</entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Area Needed</entry>

-      <entry>GN-GR</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-      <entry>S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Spot Location</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Colormap</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Foreground</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Background</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Background Pixmap</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Font Set</entry>

-      <entry>GN</entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Line Spacing</entry>

-      <entry>GN</entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Cursor</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Preedit State</entry>

-      <entry></entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Preedit State Notify Callback</entry>

-      <entry></entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Preedit Callbacks</entry>

-      <entry></entry>

-      <entry>C-S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<!-- .LP -->

-<informaltable>

-  <tgroup cols='6' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <colspec colname='c4'/>

-  <colspec colname='c5'/>

-  <colspec colname='c6'/>

-  <thead>

-    <row>

-      <entry><acronym>XIC</acronym> Value</entry>

-      <entry>Geomentry Management</entry>

-      <entry>Status Callback</entry>

-      <entry>Status Area</entry>

-      <entry>Status Nothing</entry>

-      <entry>Status None</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>Input Style</entry>

-      <entry></entry>

-      <entry>C-G</entry>

-      <entry>C-G</entry>

-      <entry>C-G</entry>

-      <entry>C-G</entry>

-    </row>

-    <row>

-      <entry>Client Window</entry>

-      <entry></entry>

-      <entry>O-G</entry>

-      <entry>O-G</entry>

-      <entry>O-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Focus Window</entry>

-      <entry>GN</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Resource Name</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Resource Class</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Geometry Callback</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Filter Events</entry>

-      <entry></entry>

-      <entry>G</entry>

-      <entry>G</entry>

-      <entry>G</entry>

-      <entry>G</entry>

-    </row>

-    <row>

-      <entry><type>Status</type></entry>

-    </row>

-    <row>

-      <entry>Area</entry>

-      <entry>GS</entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Area Needed</entry>

-      <entry>GN-GR</entry>

-      <entry>Ignored</entry>

-      <entry>S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Colormap</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Foreground</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Background</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Background Pixmap</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Font Set</entry>

-      <entry>GN</entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Line Spacing</entry>

-      <entry>GN</entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Cursor</entry>

-      <entry></entry>

-      <entry>Ignored</entry>

-      <entry>D-S-G</entry>

-      <entry>D-S-G</entry>

-      <entry>Ignored</entry>

-    </row>

-    <row>

-      <entry>Status Callbacks</entry>

-      <entry></entry>

-      <entry>C-S-G</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-      <entry>Ignored</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-<sect3 id="Input_Style">

-<title>Input Style</title>

-<!-- .XS -->

-<!-- (SN Input Style -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNInputStyle</symbol>

-argument specifies the input style to be used.

-The value of this argument must be one of the values returned by the

-<function>XGetIMValues</function>

-function with the

-<symbol>XNQueryInputStyle</symbol>

-argument specified in the supported_styles list.

-</para>

-<para>

-<!-- .LP -->

-Note that this argument must be set at creation time

-and cannot be changed.

-</para>

-</sect3>

-<sect3 id="Client_Window">

-<title>Client Window</title>

-<!-- .XS -->

-<!-- (SN Client Window -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNClientWindow</primary></indexterm>

-The

-<symbol>XNClientWindow</symbol>

-argument specifies to the input method the client window in

-which the input method

-can display data or create subwindows.

-Geometry values for input method areas are given with respect to the client

-window.

-Dynamic change of client window is not supported.

-This argument may be set only once and

-should be set before any input is done using this input context.

-If it is not set,

-the input method may not operate correctly.

-</para>

-<para>

-<!-- .LP -->

-If an attempt is made to set this value a second time with

-<function>XSetICValues</function>,

-the string

-<symbol>XNClientWindow</symbol>

-will be returned by

-<function>XSetICValues</function>,

-and the client window will not be changed.

-</para>

-<para>

-<!-- .LP -->

-If the client window is not a valid window ID on the display

-attached to the input method,

-a 

-<errorname>BadWindow</errorname>

-error can be generated when this value is used by the input method.

-</para>

-</sect3>

-<sect3 id="Focus_Window">

-<title>Focus Window</title>

-<!-- .XS -->

-<!-- (SN Focus Window -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNFocusWindow</primary></indexterm>

-The

-<symbol>XNFocusWindow</symbol>

-argument specifies the focus window.

-The primary purpose of the 

-<symbol>XNFocusWindow</symbol>

-is to identify the window that will receive the key event when input

-is composed.

-In addition, the input method may possibly affect the focus window

-as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Select events on it

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Send events to it

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Modify its properties

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Grab the keyboard within that window  

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The associated value must be of type 

-<type>Window</type>.

-If the focus window is not a valid window ID on the display 

-attached to the input method,

-a 

-<errorname>BadWindow</errorname>

-error can be generated when this value is used by the input method.

-</para>

-<para>

-<!-- .LP -->

-When this <acronym>XIC</acronym> value is left unspecified,

-the input method will use the client window as the default focus window.

-</para>

-</sect3>

-<sect3 id="Resource_Name_and_Class_b">

-<title>Resource Name and Class</title>

-<!-- .XS -->

-<!-- (SN Resource Name and Class -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNResourceName</primary></indexterm>

-<indexterm significance="preferred"><primary>XNResourceClass</primary></indexterm>

-The

-<symbol>XNResourceName</symbol>

-and

-<symbol>XNResourceClass</symbol>

-arguments are strings that specify the full name and class

-used by the client to obtain resources for the client window. 

-These values should be used as prefixes for name and class

-when looking up resources that may vary according to the input context.

-If these values are not set,

-the resources will not be fully specified.

-</para>

-<para>

-<!-- .LP -->

-It is not intended that values that can be set as <acronym>XIC</acronym> values be

-set as resources.

-</para>

-</sect3>

-<sect3 id="Geometry_Callback">

-<title>Geometry Callback</title>

-<!-- .XS -->

-<!-- (SN Geometry Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNGeometryCallback</primary></indexterm>

-The 

-<symbol>XNGeometryCallback</symbol>

-argument is a structure of type 

-<structname>XIMCallback</structname>

-(see section 13.5.6.13.12).

-</para>

-<para>

-<!-- .LP -->

-The 

-<symbol>XNGeometryCallback</symbol>

-argument specifies the geometry callback that a client can set.

-This callback is not required for correct operation of either 

-an input method or a client.

-It can be set for a client whose user interface policy permits

-an input method to request the dynamic change of that input 

-method's window.

-An input method that does dynamic change will need to filter any

-events that it uses to initiate the change.

-</para>

-</sect3>

-<sect3 id="Filter_Events">

-<title>Filter Events</title>

-<!-- .XS -->

-<!-- (SN Filter Events -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNFilterEvents</primary></indexterm>

-The 

-<symbol>XNFilterEvents</symbol>

-argument returns the event mask that an input method needs

-to have selected for.

-The client is expected to augment its own event mask 

-for the client window with this one.

-</para>

-<para>

-<!-- .LP -->

-This argument is read-only, is set by the input method at create time,

-and is never changed.

-</para>

-<para>

-<!-- .LP -->

-The type of this argument is 

-<type>unsigned</type>

-<type>long</type>.

-Setting this value will cause an error.

-</para>

-</sect3>

-<sect3 id="Destroy_Callback_b">

-<title>Destroy Callback</title>

-<!-- .XS -->

-<!-- (SN Destroy Callback  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The 

-<symbol>XNDestroyCallback</symbol>

-argument is a pointer to a structure of type

-<structname>XIMCallback</structname>

-(see section 13.5.6.13.12).  This callback is triggered when the input method 

-stops its service for any reason; for example, when a connection to an IM

-server is broken.  After the destroy callback is called, 

-the input context is destroyed and the input method is closed.

-Therefore, the client should not call 

-<function>XDestroyIC</function>

-and

-<function>XCloseIM</function>.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="String_Conversion_Callback">

-<title>String Conversion Callback</title>

-<!-- .XS -->

-<!-- (SN String Conversion Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNStringConversionCallback</symbol>

-argument is a structure of type

-<structname>XIMCallback</structname>

-(see section 13.5.6.13.12).

-</para>

-<para>

-<!-- .LP -->

-The

-<symbol>XNStringConversionCallback</symbol>

-argument specifies a string conversion callback.  This callback

-is not required for correct operation of

-either the input method or the client.  It can be set by a client

-to support string conversions that may be requested

-by the input method.  An input method that does string conversions

-will filter any events that it uses to initiate the conversion.

-</para>

-<para>

-<!-- .LP -->

-Because this <acronym>XIC</acronym> value is optional, a client should call

-<function>XGetIMValues</function>

-with argument

-<symbol>XNQueryICValuesList</symbol>

-before using this argument.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="String_Conversion_">

-<title>String Conversion </title>

-<!-- .XS -->

-<!-- (SN String Conversion -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNStringConversion</symbol>

-argument is a structure of type

-<structname>XIMStringConversionText</structname>.

-</para>

-<para>

-<!-- .LP -->

-The

-<symbol>XNStringConversion</symbol>

-argument specifies the string to be converted by an input method.

-This argument is not required for correct operation of either

-the input method or the client.

-</para>

-<para>

-<!-- .LP -->

-String conversion facilitates the manipulation of text independent

-of preediting.

-It is essential for some input methods and clients to manipulate

-text by performing context-sensitive conversion,

-reconversion, or transliteration conversion on it.

-</para>

-<para>

-<!-- .LP -->

-Because this <acronym>XIC</acronym> value is optional, a client should call

-<function>XGetIMValues</function>

-with argument

-<symbol>XNQueryICValuesList</symbol>

-before using this argument.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XIMStringConversionText</structname>

-structure is defined as follows:

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-

-typedef struct _XIMStringConversionText {

-     unsigned short              length;

-     XIMStringConversionFeedback *feedback;

-     Bool                        encoding_is_wchar;

-     union {

-          char     *mbs;

-          wchar_t  *wcs;

-     } string;

-} XIMStringConversionText;

-

-typedef unsigned long XIMStringConversionFeedback;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The feedback member is reserved for future use.  The text to be

-converted is defined by the string and length members.  The length

-is indicated in characters.  To prevent the library from freeing memory

-pointed to by an uninitialized pointer, the client should set the feedback

-element to NULL.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Reset_State">

-<title>Reset State</title>

-<!-- .XS -->

-<!-- (SN Reset State -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNResetState</symbol>

-argument specifies the state the input context will return to after calling

-<function>XmbResetIC</function>

-or

-<function>XwcResetIC</function>.

-</para>

-<para>

-<!-- .LP -->

-The <acronym>XIC</acronym> state may be set to its initial state, as specified by the

-<symbol>XNPreeditState</symbol>

-value when

-<function>XCreateIC</function>

-was called, or it may be set to preserve the current state.

-</para>

-<para>

-<!-- .LP -->

-The valid masks for

-<type>XIMResetState</type>

-are as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMInitialState</primary></indexterm>

-<indexterm significance="preferred"><primary>XINPreserveState</primary></indexterm>

-<!-- .sM -->

-</para>

-<literallayout class="monospaced">

-typedef unsigned long XIMResetState;

-

-#define XIMInitialState  (1L)

-#define XIMPreserveState (1L&lt;&lt;1)

-

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If

-<symbol>XIMInitialState</symbol>

-is set, then

-<function>XmbResetIC</function>

-and

-<function>XwcResetIC</function>

-will return to the initial

-<symbol>XNPreeditState</symbol>

-state of the <acronym>XIC</acronym>.

-</para>

-<para>

-<!-- .LP -->

-If

-<symbol>XIMPreserveState</symbol>

-is set, then 

-<function>XmbResetIC</function>

-and

-<function>XwcResetIC</function>

-will preserve the current state of the <acronym>XIC</acronym>.

-</para>

-<para>

-<!-- .LP -->

-If

-<symbol>XNResetState</symbol>

-is left unspecified, the default is

-<symbol>XIMInitialState</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<type>XIMResetState</type>

-values other than those specified above will default to

-<symbol>XIMInitialState</symbol>.

-</para>

-<para>

-<!-- .LP -->

-Because this <acronym>XIC</acronym> value is optional, a client should call

-<function>XGetIMValues</function>

-with argument

-<symbol>XNQueryICValuesList</symbol>

-before using this argument.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Hot_Keys_b">

-<title>Hot Keys</title>

-<!-- .XS -->

-<!-- (SN Hot Keys -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNHotKey</symbol>

-argument specifies the hot key list to the <acronym>XIC</acronym>.

-The hot key list is a pointer to the structure of type

-<structname>XIMHotKeyTriggers</structname>,

-which specifies the key events that must be received

-without any interruption of the input method.

-For the hot key list set with this argument to be utilized, the client

-must also set

-<symbol>XNHotKeyState</symbol>

-to

-<symbol>XIMHotKeyStateON</symbol>.

-</para>

-<para>

-<!-- .LP -->

-Because this <acronym>XIC</acronym> value is optional, a client should call

-<function>XGetIMValues</function>

-with argument

-<symbol>XNQueryICValuesList</symbol>

-before using this functionality.

-</para>

-<para>

-<!-- .LP -->

-The value of the argument is a pointer to a structure of type

-<structname>XIMHotKeyTriggers</structname>.

-</para>

-<para>

-<!-- .LP -->

-If an event for a key in the hot key list is found, then the process will

-receive the event and it will be processed inside the client.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-     KeySym keysym;

-     unsigned int modifier;

-     unsigned int modifier_mask;

-} XIMHotKeyTrigger;

-

-typedef struct {

-     int num_hot_key;

-     XIMHotKeyTrigger *key;

-} XIMHotKeyTriggers;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-<para>

-<!-- .LP -->

-The combination of modifier and modifier_mask are used to represent one of

-three states for each modifier:

-either the modifier must be on, or the modifier must be off, or the modifier

-is a ``don't care'' - it may be on or off.

-When a modifier_mask bit is set to 0, the state of the associated modifier

-is ignored when evaluating whether the key is hot or not.

-</para>

-

-<informaltable>

-  <tgroup cols='3' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <thead>

-    <row>

-      <entry>Modifier Bit</entry>

-      <entry>Mask Bit</entry>

-      <entry>Meaning</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>0</entry>

-      <entry>1</entry>

-      <entry>The modifier must be off.</entry>

-    </row>

-    <row>

-      <entry>1</entry>

-      <entry>1</entry>

-      <entry>The modifier must be on.</entry>

-    </row>

-    <row>

-      <entry>n/a</entry>

-      <entry>0</entry>

-      <entry>Do not care if the modifier is on or off.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-</sect3>

-<sect3 id="Hot_Key_State">

-<title>Hot Key State</title>

-<!-- .XS -->

-<!-- (SN Hot Key State -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNHotKeyState</symbol>

-argument specifies the hot key state of the input method.

-This is usually used to switch the input method between hot key

-operation and normal input processing.

-</para>

-<para>

-<!-- .LP -->

-The value of the argument is a pointer to a structure of type

-XIMHotKeyState .

-</para>

-<literallayout class="monospaced">

-typedef unsigned long XIMHotKeyState;

-

-#define XIMHotKeyStateON            (0x0001L)

-#define XIMHotKeyStateOFF           (0x0002L)

-

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-<para>

-<!-- .LP -->

-If not specified, the default is

-<symbol>XIMHotKeyStateOFF</symbol>.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-<sect3 id="Preedit_and_Status_Attributes">

-<title>Preedit and Status Attributes</title>

-<!-- .XS -->

-<!-- (SN Preedit and Status Attributes -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNPreeditAttributes</primary></indexterm>

-<indexterm significance="preferred"><primary>XNStatusAttributes</primary></indexterm>

-The

-<symbol>XNPreeditAttributes</symbol>

-and

-<symbol>XNStatusAttributes</symbol>

-arguments specify to an input method the attributes to be used for the 

-preedit and status areas,

-if any.

-Those attributes are passed to 

-<function>XSetICValues</function>

-or

-<function>XGetICValues</function>

-as a nested variable-length list.

-The names to be used in these lists are described in the following sections.

-</para>

-<sect4 id="Area">

-<title>Area</title>

-<!-- .XS -->

-<!-- (SN Area -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNArea</primary></indexterm>

-The value of the

-<symbol>XNArea</symbol>

-argument must be a pointer to a structure of type

-<structname>XRectangle</structname>.

-The interpretation of the

-<symbol>XNArea</symbol>

-argument is dependent on the input method style that has been set.

-</para>

-<para>

-<!-- .LP -->

-If the input method style is 

-<symbol>XIMPreeditPosition</symbol>,

-<symbol>XNArea</symbol>

-specifies the clipping region within which preediting will take place.

-If the focus window has been set,

-the coordinates are assumed to be relative to the focus window.

-Otherwise, the coordinates are assumed to be relative to the client window.

-If neither has been set,

-the results are undefined.

-</para>

-<para>

-<!-- .LP -->

-If 

-<symbol>XNArea</symbol>

-is not specified, is set to NULL, or is invalid,

-the input method will default the clipping region

-to the geometry of the

-<symbol>XNFocusWindow</symbol>.

-If the area specified is NULL or invalid,

-the results are undefined.

-</para>

-<para>

-<!-- .LP -->

-If the input style is 

-<symbol>XIMPreeditArea</symbol>

-or 

-<symbol>XIMStatusArea</symbol>,

-<symbol>XNArea</symbol>

-specifies the geometry provided by the client to the input method.

-The input method may use this area to display its data,

-either preedit or status depending on the area designated.

-The input method may create a window as a child of the client window

-with dimensions that fit the

-<symbol>XNArea</symbol>.

-The coordinates are relative to the client window.

-If the client window has not been set yet,

-the input method should save these values 

-and apply them when the client window is set.

-If 

-<symbol>XNArea</symbol>

-is not specified, is set to NULL, or is invalid,

-the results are undefined.

-</para>

-</sect4>

-<sect4 id="Area_Needed">

-<title>Area Needed</title>

-<!-- .XS -->

-<!-- (SN Area Needed -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNAreaNeeded</primary></indexterm>

-When set, the

-<symbol>XNAreaNeeded</symbol>

-argument specifies the geometry suggested by the client for this area

-(preedit or status).

-The value associated with the argument must be a pointer to a 

-structure of type 

-<structname>XRectangle</structname>.

-Note that the x, y values are not used

-and that nonzero values for width or height are the constraints 

-that the client wishes the input method to respect.

-</para>

-<para>

-<!-- .LP -->

-When read, the

-<symbol>XNAreaNeeded</symbol>

-argument specifies the preferred geometry desired by the input method

-for the area.

-</para>

-<para>

-<!-- .LP -->

-This argument is only valid if the input style is 

-<symbol>XIMPreeditArea</symbol>

-or 

-<symbol>XIMStatusArea</symbol>.

-It is used for geometry negotiation between the client and the input method

-and has no other effect on the input method 

-(see section 13.5.1.5).

-</para>

-</sect4>

-<sect4 id="Spot_Location">

-<title>Spot Location</title>

-<!-- .XS -->

-<!-- (SN Spot Location -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNSpotLocation</primary></indexterm>

-The

-<symbol>XNSpotLocation</symbol>

-argument specifies to the input method the coordinates of the spot

-to be used by an input method executing with 

-<symbol>XNInputStyle</symbol>

-set to 

-<symbol>XIMPreeditPosition</symbol>.

-When specified to any input method other than 

-<symbol>XIMPreeditPosition</symbol>,

-this <acronym>XIC</acronym> value is ignored.

-</para>

-<para>

-<!-- .LP -->

-The x coordinate specifies the position where the next character

-would be inserted.

-The y coordinate is the position of the baseline used

-by the current text line in the focus window.

-The x and y coordinates are relative to the focus window, if it has been set;

-otherwise, they are relative to the client window.

-If neither the focus window nor the client window has been set,

-the results are undefined.

-</para>

-<para>

-<!-- .LP -->

-The value of the argument is a pointer to a structure of type

-<structname>XPoint</structname>.

-</para>

-</sect4>

-<sect4 id="Colormap">

-<title>Colormap</title>

-<!-- .XS -->

-<!-- (SN Colormap -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Two different arguments can be used to indicate what colormap the input method

-should use to allocate colors, a colormap ID, or a standard colormap name.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNColormap</primary></indexterm>

-The

-<symbol>XNColormap</symbol>

-argument is used to specify a colormap ID.

-The argument value is of type

-<type>Colormap</type>.

-An invalid argument may generate a 

-<errorname>BadColor</errorname>

-error when it is used by the input method.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNStdColormap</primary></indexterm>

-The

-<symbol>XNStdColormap</symbol>

-argument is used to indicate the name of the standard colormap

-in which the input method should allocate colors.

-The argument value is an 

-<type>Atom</type>

-that should be a valid atom for calling

-<function>XGetRGBColormaps</function>.

-An invalid argument may generate a

-<errorname>BadAtom</errorname>

-error when it is used by the input method.

-</para>

-<para>

-<!-- .LP -->

-If the colormap is left unspecified,

-the client window colormap becomes the default.

-</para>

-</sect4>

-<sect4 id="Foreground_and_Background">

-<title>Foreground and Background</title>

-<!-- .XS -->

-<!-- (SN Foreground and Background -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNForeground</primary></indexterm>

-<indexterm significance="preferred"><primary>XNBackground</primary></indexterm>

-The

-<symbol>XNForeground</symbol>

-and

-<symbol>XNBackground</symbol>

-arguments specify the foreground and background pixel, respectively.

-The argument value is of type

-<type>unsigned</type>

-<type>long</type>.

-It must be a valid pixel in the input method colormap.

-</para>

-<para>

-<!-- .LP -->

-If these values are left unspecified,

-the default is determined by the input method.

-</para>

-</sect4>

-<sect4 id="Background_Pixmap">

-<title>Background Pixmap</title>

-<!-- .XS -->

-<!-- (SN Background Pixmap -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNBackgroundPixmap</symbol>

-argument specifies a background pixmap to be used as the background of the

-window.

-The value must be of type 

-<type>Pixmap</type>.

-An invalid argument may generate a

-<errorname>BadPixmap</errorname>

-error when it is used by the input method.

-</para>

-<para>

-<!-- .LP -->

-If this value is left unspecified,

-the default is determined by the input method.

-</para>

-</sect4>

-<sect4 id="Font_Set">

-<title>Font Set</title>

-<!-- .XS -->

-<!-- (SN Font Set -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNFontSet</primary></indexterm>

-The

-<symbol>XNFontSet</symbol>

-argument specifies to the input method what font set is to be used.

-The argument value is of type

-<type>XFontSet</type>.

-</para>

-<para>

-<!-- .LP -->

-If this value is left unspecified,

-the default is determined by the input method.

-</para>

-</sect4>

-<sect4 id="Line_Spacing">

-<title>Line Spacing</title>

-<!-- .XS -->

-<!-- (SN Line Spacing -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNLineSpace</symbol>

-argument specifies to the input method what line spacing is to be used

-in the preedit window if more than one line is to be used.

-This argument is of type

-<type>int</type>.

-</para>

-<para>

-<!-- .LP -->

-If this value is left unspecified,

-the default is determined by the input method.

-</para>

-</sect4>

-<sect4 id="Cursor">

-<title>Cursor</title>

-<!-- .XS -->

-<!-- (SN Cursor -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XNCursor</primary></indexterm>

-The

-<symbol>XNCursor</symbol>

-argument specifies to the input method what cursor is to be used

-in the specified window.

-This argument is of type 

-<type>Cursor</type>.

-</para>

-<para>

-<!-- .LP -->

-An invalid argument may generate a

-<errorname>BadCursor</errorname>

-error when it is used by the input method.

-If this value is left unspecified,

-the default is determined by the input method.

-</para>

-</sect4>

-<sect4 id="Preedit_State">

-<title>Preedit State</title>

-<!-- .XS -->

-<!-- (SN Preedit State -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<symbol>XNPreeditState</symbol>

-argument specifies the state of input preediting for the input method.

-Input preediting can be on or off.

-</para>

-<para>

-<!-- .LP -->

-The valid mask names for

-<symbol>XNPreeditState</symbol>

-are as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMPreeditUnknown</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditEnable</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreeditDisable</primary></indexterm>

-<!-- .sM -->

-</para>

-<!-- .LP -->

-<literallayout class="monospaced">

-typedef unsigned long XIMPreeditState;

-

-#define XIMPreeditUnknown    0L

-#define XIMPreeditEnable     1L

-#define XIMPreeditDisable    (1L&lt;&lt;1)

-

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If a value of

-<symbol>XIMPreeditEnable</symbol>

-is set, then input preediting is turned on by the input method.

-</para>

-<para>

-<!-- .LP -->

-If a value of

-<symbol>XIMPreeditDisable</symbol>

-is set, then input preediting is turned off by the input method.

-</para>

-<para>

-<!-- .LP -->

-If

-<symbol>XNPreeditState</symbol>

-is left unspecified, then the state will be implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-When

-<symbol>XNResetState</symbol>

-is set to

-<symbol>XIMInitialState</symbol>,

-the

-<symbol>XNPreeditState</symbol>

-value specified at the creation time will be reflected as the initial state for

-<function>XmbResetIC</function>

-and

-<function>XwcResetIC</function>.

-</para>

-<para>

-<!-- .LP -->

-Because this <acronym>XIC</acronym> value is optional, a client should call

-<function>XGetIMValues</function>

-with argument

-<symbol>XNQueryICValuesList</symbol>

-before using this argument.

-</para>

-</sect4>

-<sect4 id="Preedit_State_Notify_Callback">

-<title>Preedit State Notify Callback</title>

-<!-- .XS -->

-<!-- (SN Preedit State Notify Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The preedit state notify callback is triggered by the input method

-when the preediting state has changed.

-The value of the

-<symbol>XNPreeditStateNotifyCallback</symbol>

-argument is a pointer to a structure of type

-<structname>XIMCallback</structname>.

-The generic prototype is as follows:

-<indexterm significance="preferred"><primary>PreeditStateNotifyCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>PreeditStateNotifyCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XIMPreeditStateNotifyCallbackStruct<parameter> *call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the current preedit state.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<structname>XIMPreeditStateNotifyCallbackStruct</structname>

-structure is defined as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMPreeditStateNotifyCallbackStruct</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct _XIMPreeditStateNotifyCallbackStruct {

-     XIMPreeditState state;

-} XIMPreeditStateNotifyCallbackStruct;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-<para>

-<!-- .LP -->

-Because this <acronym>XIC</acronym> value is optional, a client should call

-<function>XGetIMValues</function>

-with argument

-<symbol>XNQueryICValuesList</symbol>

-before using this argument.

-</para>

-</sect4>

-<sect4 id="Preedit_and_Status_Callbacks">

-<title>Preedit and Status Callbacks</title>

-<!-- .XS -->

-<!-- (SN Preedit and Status Callbacks -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A client that wants to support the input style

-<symbol>XIMPreeditCallbacks</symbol>

-must provide a set of preedit callbacks to the input method.

-The set of preedit callbacks is as follows:

-</para>

-<indexterm significance="preferred"><primary>XNPreeditStartCallback</primary></indexterm>

-<indexterm significance="preferred"><primary>XNPreeditDoneCallback</primary></indexterm>

-<indexterm significance="preferred"><primary>XNPreeditDrawCallback</primary></indexterm>

-<indexterm significance="preferred"><primary>XNPreeditCaretCallback</primary></indexterm>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>XNPreeditStartCallback</symbol></entry>

-      <entry>This is called when the input method starts preedit.</entry>

-    </row>

-    <row>

-      <entry><symbol>XNPreeditDoneCallback</symbol></entry>

-      <entry>This is called when the input method stops preedit.</entry>

-    </row>

-    <row>

-      <entry><symbol>XNPreeditDrawCallback</symbol></entry>

-      <entry>This is called when a number of preedit keystrokes should be echoed.</entry>

-    </row>

-    <row>

-      <entry><symbol>XNPreeditCaretCallback</symbol></entry>

-      <entry>This is called to move the text insertion point within the preedit string.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-A client that wants to support the input style

-<symbol>XIMStatusCallbacks</symbol>

-must provide a set of status callbacks to the input method.

-The set of status callbacks is as follows:

-</para>

-

-<indexterm significance="preferred"><primary>XNStatusStartCallback</primary></indexterm>

-<indexterm significance="preferred"><primary>XNStatusDoneCallback</primary></indexterm>

-<indexterm significance="preferred"><primary>XNStatusDrawCallback</primary></indexterm>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>XNStatusStartCallback</symbol></entry>

-      <entry>This is called when the input method initializes the status area.</entry>

-    </row>

-    <row>

-      <entry><symbol>XNStatusDoneCallback</symbol></entry>

-      <entry>This is called when the input method no longer needs the status area.</entry>

-    </row>

-    <row>

-      <entry><symbol>XNStatusDrawCallback</symbol></entry>

-      <entry>This is called when updating of the status area is required.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-<para>

-<!-- .LP -->

-The value of any status or preedit argument is a pointer

-to a structure of type

-<structname>XIMCallback</structname>.

-<indexterm significance="preferred"><primary>XIMProc</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMCallback</primary></indexterm>

-<!-- .sM -->

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef void (*XIMProc)();

-

-typedef struct {

-     XPointer client_data;

-     XIMProc callback;

-} XIMCallback;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Each callback has some particular semantics and will carry the data

-that expresses the environment necessary to the client 

-into a specific data structure.

-This paragraph only describes the arguments to be used to set

-the callback.

-</para>

-<para>

-<!-- .LP -->

-Setting any of these values while doing preedit

-may cause unexpected results.

-</para>

-</sect4>

-</sect3>

-</sect2>

-<sect2 id="Input_Method_Callback_Semantics">

-<title>Input Method Callback Semantics</title>

-<!-- .XS -->

-<!-- (SN Input Method Callback Semantics -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<acronym>XIM</acronym> callbacks are procedures defined by clients or text drawing packages

-that are to be called from the input method when selected events occur.

-Most clients will use a text editing package or a toolkit

-and, hence, will not need to define such callbacks.

-This section defines the callback semantics, when they are triggered,

-and what their arguments are.

-This information is mostly useful for X toolkit implementors.

-</para>

-<para>

-<!-- .LP -->

-Callbacks are mostly provided so that clients (or text editing

-packages) can implement on-the-spot preediting in their own window.

-In that case,

-the input method needs to communicate and synchronize with the client.

-The input method needs to communicate changes in the preedit window 

-when it is under control of the client.

-Those callbacks allow the client to initialize the preedit area,

-display a new preedit string,

-move the text insertion point during preedit,

-terminate preedit, or update the status area.

-</para>

-<para>

-<!-- .LP -->

-All callback procedures follow the generic prototype:

-<indexterm significance="preferred"><primary>CallbackPrototype</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>CallbackPrototype</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>SomeType<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies data specific to the callback.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The call_data argument is a structure that expresses the arguments needed

-to achieve the semantics;

-that is,

-it is a specific data structure appropriate to the callback.

-In cases where no data is needed in the callback,

-this call_data argument is NULL.

-The client_data argument is a closure that has been initially specified

-by the client when specifying the callback and passed back.

-It may serve, for example, to inherit application context in the callback.

-</para>

-<para>

-<!-- .LP -->

-The following paragraphs describe the programming semantics

-and specific data structure associated with the different reasons.

-</para>

-<sect3 id="Geometry_Callback_b">

-<title>Geometry Callback</title>

-<!-- .XS -->

-<!-- (SN Geometry Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The geometry callback is triggered by the input method 

-to indicate that it wants the client to negotiate geometry.

-The generic prototype is as follows:

-<indexterm significance="preferred"><primary>GeometryCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>GeometryCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Not used for this callback and always passed as NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The callback is called with a NULL call_data argument.

-</para>

-</sect3>

-<sect3 id="Destroy_Callback_c">

-<title>Destroy Callback</title>

-<!-- .XS -->

-<!-- (SN Destroy Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The destroy callback is triggered by the input method 

-when it stops service for any reason.

-After the callback is invoked, the input context will be freed by Xlib.

-The generic prototype is as follows:

-<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>DestroyCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Not used for this callback and always passed as NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The callback is called with a NULL call_data argument.

-</para>

-</sect3>

-<sect3 id="String_Conversion_Callback_b">

-<title>String Conversion Callback</title>

-<!-- .XS -->

-<!-- (SN String Conversion Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The string conversion callback is triggered by the input method 

-to request the client to return the string to be converted.  The

-returned string may be either a multibyte or wide character string,

-with an encoding matching the locale bound to the input context.

-The callback prototype is as follows:

-<indexterm significance="preferred"><primary>StringConversionCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>StringConversionCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XIMStringConversionCallbackStruct<parameter> *call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input method.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the amount of the string to be converted.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The callback is passed an

-<structname>XIMStringConversionCallbackStruct</structname>

-structure in the call_data argument.

-The text member is an

-<structname>XIMStringConversionText</structname>

-structure (see section 13.5.6.9) to be filled in by the client

-and describes the text to be sent to the input method.

-The data pointed to by the 

-string and feedback elements of the

-<structname>XIMStringConversionText</structname>

-structure will be freed using

-<function>XFree</function>

-by the input method

-after the callback returns.  So the client should not point to 

-internal buffers that are critical to the client.

-Similarly, because the feedback element is currently reserved for future

-use, the client should set feedback to NULL to prevent the library from

-freeing memory at some random location due to an uninitialized pointer.

-</para>

-<para>

-<!-- .LP -->

-The 

-<structname>XIMStringConversionCallbackStruct</structname>

-structure is defined as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMStringConversionCallbackStruct</primary></indexterm>

-<!-- .sM -->

-</para>

-<!-- .LP -->

-<literallayout class="monospaced">

-typedef struct _XIMStringConversionCallbackStruct {

-     XIMStringConversionPosition position;          

-     XIMCaretDirection direction;

-     short factor;

-     XIMStringConversionOperation operation;

-     XIMStringConversionText *text;

-} XIMStringConversionCallbackStruct;

-

-typedef short XIMStringConversionPosition;

-

-typedef unsigned short XIMStringConversionOperation;

-

-#define XIMStringConversionSubstitution       (0x0001)

-#define XIMStringConversionRetrieval          (0x0001)

-

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<type>XIMStringConversionPosition</type>

-specifies the starting position of the string to be returned

-in the

-<structname>XIMStringConversionText</structname>

-structure.  The value identifies a position, in units of characters,

-relative to the client's cursor position in the client's buffer.

-</para>

-<para>

-<!-- .LP -->

-The ending position of the text buffer is determined by

-the direction and factor members.  Specifically, it is the character position 

-relative to the starting point as defined by the

-<structname>XIMCaretDirection</structname>.

-The factor member of 

-<structname>XIMStringConversionCallbackStruct</structname>

-specifies the number of

-<structname>XIMCaretDirection</structname>

-positions to be applied.  For example, if the direction specifies

-<constant>XIMLineEnd</constant>

-and factor is 1, then all characters from the starting position to 

-the end of the current display line are returned.  If the direction

-specifies

-<constant>XIMForwardChar</constant>

-or

-<constant>XIMBackwardChar</constant>,

-then the factor specifies a relative position, indicated in characters, 

-from the starting position.

-</para>

-<para>

-<!-- .LP -->

-<type>XIMStringConversionOperation</type>

-specifies whether the string to be converted should be 

-deleted (substitution) or copied (retrieval) from the client's

-buffer.  When the

-<type>XIMStringConversionOperation</type>

-is

-<symbol>XIMStringConversionSubstitution</symbol>,

-the client must delete the string to be converted from its own buffer.

-When the

-<type>XIMStringConversionOperation</type>

-is

-<symbol>XIMStringConversionRetrieval</symbol>,

-the client must not delete the string to be converted from its buffer.

-The substitute operation is typically used for reconversion and

-transliteration conversion,

-while the retrieval operation is typically used for context-sensitive 

-conversion.

-</para>

-</sect3>

-<sect3 id="Preedit_State_Callbacks">

-<title>Preedit State Callbacks</title>

-<!-- .XS -->

-<!-- (SN Preedit State Callbacks -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-When the input method turns preediting on or off, a

-<function><replaceable>PreeditStartCallback</replaceable></function>

-or

-<function><replaceable>PreeditDoneCallback</replaceable></function>

-callback is triggered to let the toolkit do the setup

-or the cleanup for the preedit region.

-<indexterm significance="preferred"><primary>PreeditStartCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function><replaceable>PreeditStartCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Not used for this callback and always passed as NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-When preedit starts on the specified input context,

-the callback is called with a NULL call_data argument.

-<function><replaceable>PreeditStartCallback</replaceable></function>

-will return the maximum size of the preedit string.

-A positive number indicates the maximum number of bytes allowed

-in the preedit string, 

-and a value of -1 indicates there is no limit.

-<indexterm significance="preferred"><primary>PreeditDoneCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>PreeditDoneCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Not used for this callback and always passed as NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-When preedit stops on the specified input context,

-the callback is called with a NULL call_data argument.

-The client can release the data allocated by

-<function><replaceable>PreeditStartCallback</replaceable></function>.

-</para>

-<para>

-<!-- .LP -->

-<function><replaceable>PreeditStartCallback</replaceable></function>

-should initialize appropriate data needed for

-displaying preedit information and for handling further 

-<function><replaceable>PreeditDrawCallback</replaceable></function>

-calls.

-Once

-<function><replaceable>PreeditStartCallback</replaceable></function>

-is called, it will not be called again before

-<function><replaceable>PreeditDoneCallback</replaceable></function>

-has been called.

-</para>

-</sect3>

-<sect3 id="Preedit_Draw_Callback">

-<title>Preedit Draw Callback</title>

-<!-- .XS -->

-<!-- (SN Preedit Draw Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This callback is triggered to draw and insert, delete or replace,

-preedit text in the preedit region.

-The preedit text may include unconverted input text such as Japanese Kana,

-converted text such as Japanese Kanji characters, or characters of both kinds.

-That string is either a multibyte or wide character string, 

-whose encoding matches the locale bound to the input context.

-The callback prototype

-is as follows:

-<indexterm significance="preferred"><primary>PreeditDrawCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>PreeditDrawCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XIMPreeditDrawCallbackStruct<parameter> *call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the preedit drawing information.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The callback is passed an 

-<structname>XIMPreeditDrawCallbackStruct</structname>

-structure in the call_data argument.

-The text member of this structure contains the text to be drawn.

-After the string has been drawn,

-the caret should be moved to the specified location.

-</para>

-<para>

-<!-- .LP -->

-The 

-<structname>XIMPreeditDrawCallbackStruct</structname>

-structure is defined as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMPreeditDrawCallbackStruct</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct _XIMPreeditDrawCallbackStruct {

-     int caret;     /* Cursor offset within preedit string */

-     int chg_first;     /* Starting change position */

-     int chg_length;     /* Length of the change in character count */

-     XIMText *text;

-} XIMPreeditDrawCallbackStruct;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The client must keep updating a buffer of the preedit text

-and the callback arguments referring to indexes in that buffer.

-The call_data fields have specific meanings according to the operation,

-as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-To indicate text deletion, 

-the call_data member specifies a NULL text field.

-The text to be deleted is then the current text in the buffer 

-from position chg_first (starting at zero) on a character length

-of chg_length.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-When text is non-NULL,

-it indicates insertion or replacement of text in the buffer.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The chg_length member

-identifies the number of characters in the current preedit buffer

-that are affected by this call.

-A positive chg_length indicates that chg_length number of characters, starting

-at chg_first, must be deleted or must be replaced by text, whose length is

-specified in the

-<structname>XIMText</structname>

-structure.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A chg_length value of zero indicates that text must be inserted

-right at the position specified by chg_first.

-A value of zero for chg_first specifies the first character in the buffer.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-chg_length and chg_first combine to identify the modification required to

-the preedit buffer; beginning at chg_first, replace chg_length number of

-characters with the text in the supplied

-<structname>XIMText</structname>

-structure. For example, suppose the preedit buffer contains the string "ABCDE".

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<literallayout class="monospaced">

-<!-- .ft C -->

-Text:      A B C D E

-          ^ ^ ^ ^ ^ ^

-CharPos:  0 1 2 3 4 5

-<!-- .sp -->

-<!-- .ft P -->

-</literallayout>

-The CharPos in the diagram shows the location of the character position

-relative to the character.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the value of chg_first is 1 and the value of chg_length is 3, this

-says to replace 3 characters beginning at character position 1 with the

-string in the

-<structname>XIMText</structname>

-structure.

-Hence, <acronym>BCD</acronym> would be replaced by the value in the structure.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Though chg_length and chg_first are both signed integers they will

-never have a negative value.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The caret member

-identifies the character position before which the cursor should

-be placed - after modification to the preedit buffer has been completed.

-For example, if caret is zero, the cursor is at

-the beginning of the buffer.  If the caret is one, the cursor is between

-the first and second character.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMText</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 1.5i 3i -->

-typedef struct _XIMText {

-     unsigned short length;

-     XIMFeedback * feedback;

-     Bool encoding_is_wchar; 

-     union {

-          char * multi_byte;

-          wchar_t * wide_char;

-     } string; 

-} XIMText;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The text string passed is actually a structure specifying as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-The length member is the text length in characters.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The encoding_is_wchar member is a value that indicates 

-if the text string is encoded in wide character or multibyte format.

-The text string may be passed either as multibyte or as wide character;

-the input method controls in which form data is passed.

-The client's

-callback routine must be able to handle data passed in either form.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The string member is the text string.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The feedback member indicates rendering type for each character in the

-string member.

-If string is NULL (indicating that only highlighting of the existing

-preedit buffer should be updated), feedback points to length highlight

-elements that should be applied to the existing preedit buffer, beginning

-at chg_first.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The feedback member expresses the types of rendering feedback

-the callback should apply when drawing text.

-Rendering of the text to be drawn is specified either in generic ways

-(for example, primary, secondary) or in specific ways (reverse, underline).

-When generic indications are given,

-the client is free to choose the rendering style.

-It is necessary, however, that primary and secondary be mapped 

-to two distinct rendering styles.

-</para>

-<para>

-<!-- .LP -->

-If an input method wants to control display of the preedit string, an 

-input method can indicate the visibility hints using feedbacks in

-a specific way.

-The 

-<symbol>XIMVisibleToForward</symbol>,

-<symbol>XIMVisibleToBackword</symbol>,

-and

-<symbol>XIMVisibleToCenter</symbol>

-masks are exclusively used for these visibility hints.

-The 

-<symbol>XIMVisibleToForward</symbol>

-mask

-indicates that the preedit text is preferably displayed in the

-primary draw direction from the

-caret position in the preedit area forward.

-The 

-<symbol>XIMVisibleToBackword</symbol>

-mask

-indicates that the preedit text is preferably displayed from

-the caret position in the preedit area backward, relative to the primary

-draw direction.

-The 

-<symbol>XIMVisibleToCenter</symbol>

-mask

-indicates that the preedit text is preferably displayed with

-the caret position in the preedit area centered.

-</para>

-<para>

-<!-- .LP -->

-The insertion point of the preedit string could exist outside of

-the visible area when visibility hints are used.

-Only one of the 

-masks

-is valid for the entire preedit string, and only one character

-can hold one of these feedbacks for a given input context at one time.

-This feedback may be OR'ed together with another highlight (such as

-<symbol>XIMReverse</symbol>).

-Only the most recently set feedback is valid, and any previous

-feedback is automatically canceled.  This is a hint to the client, and

-the client is free to choose how to display the preedit string.

-</para>

-<para>

-<!-- .LP -->

-The feedback member also specifies how rendering of the text argument

-should be performed.

-If the feedback is NULL,

-the callback should apply the same feedback as is used for the surrounding

-characters in the preedit buffer; if chg_first is at a highlight boundary,

-the client can choose which of the two highlights to use.

-If feedback is not NULL, feedback specifies an array defining the

-rendering for each

-character of the string, and the length of the array is thus length.

-</para>

-<para>

-<!-- .LP -->

-If an input method wants to indicate that it is only updating the feedback of

-the preedit text without changing the content of it, 

-the

-<structname>XIMText</structname>

-structure will contain a NULL value for the string field,

-the number of characters affected (relative to chg_first)

-will be in the length field,

-and the feedback field will point to an array of 

-<type>XIMFeedback</type>.

-</para>

-<para>

-<!-- .LP -->

-Each element in the feedback array is a bitmask represented by a value of type

-<type>XIMFeedback</type>.

-The valid mask names are as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMReverse</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMUnderline</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMHighlight</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPrimary</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMSecondary</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMTertiary</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMVisibleToForward</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMVisibleToBackward</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMVisibleToCenter</primary></indexterm>

-<!-- .sM -->

-</para>

-<literallayout class="monospaced">

-typedef unsigned long XIMFeedback;

-

-#define     XIMReverse                     1L

-#define     XIMUnderline                   (1L&lt;&lt;1)

-#define     XIMHighlight                   (1L&lt;&lt;2)

-#define     XIMPrimary                     (1L&lt;&lt;5)*

-#define     XIMSecondary                   (1L&lt;&lt;6)*

-#define     XIMTertiary                    (1L&lt;&lt;7)*

-#define     XIMVisibleToForward            (1L&lt;&lt;8)

-#define     XIMVisibleToBackward           (1L&lt;&lt;9)

-#define     XIMVisibleToCenter               (1L&lt;&lt;10)

-

-*† The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorrectly defined in

-the R5 specification. The X Consortium’s X11R5 implementation correctly

-implemented the values for these highlights. The value of these highlights has

-been corrected in this specification to agree with the values in the

-Consortium’s X11R5 and X11R6 implementations.

-

-</literallayout>

-

-<para>

-<!-- .LP -->

-Characters drawn with the

-<symbol>XIMReverse</symbol>

-highlight should be drawn by swapping the foreground and background colors

-used to draw normal, unhighlighted characters.

-Characters drawn with the

-<symbol>XIMUnderline</symbol>

-highlight should be underlined.

-Characters drawn with the

-<symbol>XIMHighlight</symbol>,

-<symbol>XIMPrimary</symbol>,

-<symbol>XIMSecondary</symbol>,

-and

-<symbol>XIMTertiary</symbol>

-highlights should be drawn in some unique manner that must be different

-from

-<symbol>XIMReverse</symbol>

-and

-<symbol>XIMUnderline</symbol>.

-<!-- .FS \(dg -->

-The values for

-<symbol>XIMPrimary</symbol>,

-<symbol>XIMSecondary</symbol>,

-and

-<symbol>XIMTertiary</symbol>

-were incorrectly defined in the R5 specification.

-The X Consortium's X11R5

-implementation correctly implemented the values for these highlights.

-The value of these highlights has been corrected in this specification

-to agree with the values in the Consortium's X11R5 and X11R6 implementations.

-<!-- .FE -->

-</para>

-</sect3>

-<sect3 id="Preedit_Caret_Callback">

-<title>Preedit Caret Callback</title>

-<!-- .XS -->

-<!-- (SN Preedit Caret Callback -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-An input method may have its own navigation keys to allow the user

-to move the text insertion point in the preedit area 

-(for example, to move backward or forward). 

-Consequently, input method needs to indicate to the client that it

-should move the text insertion point.

-It then calls the PreeditCaretCallback.

-<indexterm significance="preferred"><primary>PreeditCaretCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>PreeditCaretCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XIMPreeditCaretCallbackStruct<parameter> *call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the preedit caret information.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The input method will trigger PreeditCaretCallback

-to move the text insertion point during preedit.

-The call_data argument contains a pointer to an 

-<structname>XIMPreeditCaretCallbackStruct</structname>

-structure,

-which indicates where the caret should be moved.

-The callback must move the insertion point to its new location

-and return, in field position, the new offset value from the initial position.  

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XIMPreeditCaretCallbackStruct</structname>

-structure is defined as follows:

-<indexterm significance="preferred"><primary>XIMPreeditCaretCallbackStruct</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct _XIMPreeditCaretCallbackStruct {

-     int position;     /* Caret offset within preedit string */

-     XIMCaretDirection direction;     /* Caret moves direction */

-     XIMCaretStyle style;     /* Feedback of the caret */

-} XIMPreeditCaretCallbackStruct;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<structname>XIMCaretStyle</structname>

-structure is defined as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XIMCaretStyle</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef enum {

-     XIMIsInvisible,     /* Disable caret feedback */ 

-     XIMIsPrimary,     /* <acronym>UI</acronym> defined caret feedback */

-     XIMIsSecondary,     /* <acronym>UI</acronym> defined caret feedback */

-} XIMCaretStyle;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<structname>XIMCaretDirection</structname>

-structure is defined as follows:

-<indexterm significance="preferred"><primary>XIMCaretDirection</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef enum {

-     XIMForwardChar, XIMBackwardChar,

-     XIMForwardWord, XIMBackwardWord,

-     XIMCaretUp, XIMCaretDown,

-     XIMNextLine, XIMPreviousLine,

-     XIMLineStart, XIMLineEnd, 

-     XIMAbsolutePosition,

-     XIMDontChange,

- } XIMCaretDirection;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-These values are defined as follows:

-</para>

-<indexterm significance="preferred"><primary>XIMForwardChar</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMBackwardChar</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMForwardWord</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMBackwardWord</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMCaretUp</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMCaretDown</primary></indexterm>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><constant>XIMForwardChar</constant></entry>

-      <entry>Move the caret forward one character position.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMBackwardChar</constant></entry>

-      <entry>Move the caret backward one character position.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMForwardWord</constant></entry>

-      <entry>Move the caret forward one word.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMBackwardWord</constant></entry>

-      <entry>Move the caret backward one word.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMCaretUp</constant></entry>

-      <entry>Move the caret up one line keeping the current horizontal offset.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMCaretDown</constant></entry>

-      <entry>Move the caret down one line keeping the current horizontal offset.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMPreviousLine</constant></entry>

-      <entry>Move the caret to the beginning of the previous line.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMNextLine</constant></entry>

-      <entry>Move the caret to the beginning of the next line.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMLineStart</constant></entry>

-      <entry>Move the caret to the beginning of the current display line that contains the caret.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMLineEnd</constant></entry>

-      <entry>Move the caret to the end of the current display line that contains the caret.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMAbsolutePosition</constant></entry>

-      <entry>The callback must move to the location specified by the position field

-      of the callback data, indicated in characters, starting from the beginning

-      of the preedit text.

-      Hence, a value of zero means move back to the beginning of the preedit text.</entry>

-    </row>

-    <row>

-      <entry><constant>XIMDontChange</constant></entry>

-      <entry>The caret position does not change.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<indexterm significance="preferred"><primary>XIMNextLine</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMPreviousLine</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMLineStart</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMLineEnd</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMAbsolutePosition</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMDontChange</primary></indexterm>

-</sect3>

-<sect3 id="Status_Callbacks">

-<title>Status Callbacks</title>

-<!-- .XS -->

-<!-- (SN Status Callbacks -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-An input method may communicate changes in the status of an input context

-(for example, created, destroyed, or focus changes) with three status

-callbacks:  StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-When the input context is created or gains focus, 

-the input method calls the StatusStartCallback callback.

-<indexterm significance="preferred"><primary>StatusStartCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>StatusStartCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Not used for this callback and always passed as NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The callback should initialize appropriate data for displaying status

-and for responding to StatusDrawCallback calls.  

-Once StatusStartCallback is called,

-it will not be called again before StatusDoneCallback has been called.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-When an input context

-is destroyed or when it loses focus, the input method calls StatusDoneCallback.

-<indexterm significance="preferred"><primary>StatusDoneCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>StatusDoneCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XPointer<parameter> call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Not used for this callback and always passed as NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The callback may release any data allocated on 

-<function>StatusStart</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-When an input context status has to be updated, the input method calls

-StatusDrawCallback.

-<indexterm significance="preferred"><primary>StatusDrawCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function><replaceable>StatusDrawCallback</replaceable></function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XPointer<parameter> client_data</parameter></paramdef>

-  <paramdef>XIMStatusDrawCallbackStruct<parameter> *call_data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>client_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the additional client data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>call_data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the status drawing information.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The callback should update the status area by either drawing a string

-or imaging a bitmap in the status area.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XIMStatusDataType</structname>

-and

-<structname>XIMStatusDrawCallbackStruct</structname>

-structures are defined as follows:

-<indexterm significance="preferred"><primary>XIMStatusDataType</primary></indexterm>

-<indexterm significance="preferred"><primary>XIMStatusDrawCallbackStruct</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 1i 3i -->

-<!-- .ta .5i 1i 3i -->

-typedef enum {

-     XIMTextType,

-     XIMBitmapType,

-} XIMStatusDataType;

-

-typedef struct _XIMStatusDrawCallbackStruct {

-     XIMStatusDataType type;

-     union {

-          XIMText *text;

-          Pixmap  bitmap;

-     } data;

-} XIMStatusDrawCallbackStruct;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-<para>

-<!-- .LP -->

-The feedback styles

-<symbol>XIMVisibleToForward</symbol>,

-<symbol>XIMVisibleToBackword</symbol>,

-and

-<symbol>XIMVisibleToCenter</symbol>

-are not relevant and will not appear in the

-<type>XIMFeedback</type>

-element of the

-<structname>XIMText</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-</para>

-</sect3>

-</sect2>

-<sect2 id="Event_Filtering_b">

-<title>Event Filtering</title>

-<!-- .XS -->

-<!-- (SN Event Filtering -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides the ability for an input method

-to register a filter internal to Xlib.

-This filter is called by a client (or toolkit) by calling

-<function>XFilterEvent</function>

-after calling 

-<function>XNextEvent</function>.

-Any client that uses the 

-<type>XIM</type>

-interface should call

-<function>XFilterEvent</function>

-to allow input methods to process their events without knowledge

-of the client's dispatching mechanism.

-A client's user interface policy may determine the priority

-of event filters with respect to other event-handling mechanisms

-(for example, modal grabs).

-</para>

-<para>

-<!-- .LP -->

-Clients may not know how many filters there are, if any,

-and what they do.

-They may only know if an event has been filtered on return of 

-<function>XFilterEvent</function>.

-Clients should discard filtered events.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To filter an event, use

-<function>XFilterEvent</function>.

-<indexterm significance="preferred"><primary>XFilterEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XFilterEvent</function></funcdef>

-  <paramdef>XEvent<parameter> *event</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<!-- .ds Ev event to filter -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the (Ev.

-<!-- .ds Wi for which the filter is to be applied -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If the window argument is

-<symbol>None</symbol>,

-<function>XFilterEvent</function>

-applies the filter to the window specified in the

-<structname>XEvent</structname>

-structure.

-The window argument is provided so that layers above Xlib

-that do event redirection can indicate to which window an event

-has been redirected.

-</para>

-<para>

-<!-- .LP -->

-If

-<function>XFilterEvent</function>

-returns

-<symbol>True</symbol>,

-then some input method has filtered the event,

-and the client should discard the event.

-If

-<function>XFilterEvent</function>

-returns

-<symbol>False</symbol>,

-then the client should continue processing the event.

-</para>

-<para>

-<!-- .LP -->

-If a grab has occurred in the client and

-<function>XFilterEvent</function>

-returns

-<symbol>True</symbol>,

-the client should ungrab the keyboard.

-</para>

-</sect2>

-<sect2 id="Getting_Keyboard_Input_b">

-<title>Getting Keyboard Input</title>

-<!-- .XS -->

-<!-- (SN Getting Keyboard Input -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To get composed input from an input method,

-use

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>.

-<indexterm significance="preferred"><primary>XmbLookupString</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcLookupString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XmbLookupString</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>

-  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

-  <paramdef>int<parameter> bytes_buffer</parameter></paramdef>

-  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>

-  <paramdef>Status<parameter> *status_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XwcLookupString</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-  <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>

-  <paramdef>wchar_t<parameter> *buffer_return</parameter></paramdef>

-  <paramdef>int<parameter> wchars_buffer</parameter></paramdef>

-  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>

-  <paramdef>Status<parameter> *status_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ic</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the input context.

-<!-- .ds Ev key event to be used -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the (Ev.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buffer_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a multibyte string or wide character string (if any)

-from the input method.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bytes_buffer</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>wchars_buffer</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies space available in the return buffer.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the KeySym computed from the event if this argument is not NULL.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>status_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a value indicating what kind of data is returned.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbLookupString</function>

-and

-<function>XwcLookupString</function>

-functions return the string from the input method specified

-in the buffer_return argument.

-If no string is returned,

-the buffer_return argument is unchanged.

-</para>

-<para>

-<!-- .LP -->

-The KeySym into which the KeyCode from the event was mapped is returned

-in the keysym_return argument if it is non-NULL and the status_return

-argument indicates that a KeySym was returned.

-If both a string and a KeySym are returned,

-the KeySym value does not necessarily correspond to the string returned.

-</para>

-<para>

-<!-- .LP -->

-<function>XmbLookupString</function>

-returns the length of the string in bytes, and

-<function>XwcLookupString</function>

-returns the length of the string in characters.

-Both

-<function>XmbLookupString</function>

-and

-<function>XwcLookupString</function>

-return text in the encoding of the locale bound to the input method

-of the specified input context.

-</para>

-<para>

-<!-- .LP -->

-Each string returned by

-<function>XmbLookupString</function>

-and

-<function>XwcLookupString</function>

-begins in the initial state of the encoding of the locale

-(if the encoding of the locale is state-dependent).

-<!-- .NT -->

-<note><para>

-To insure proper input processing,

-it is essential that the client pass only 

-<symbol>KeyPress</symbol>

-events to

-<function>XmbLookupString</function>

-and

-<function>XwcLookupString</function>.

-Their behavior when a client passes a 

-<symbol>KeyRelease</symbol>

-event is undefined.

-</para></note>

-<!-- .NE -->

-</para>

-<para>

-<!-- .LP -->

-Clients should check the status_return argument before

-using the other returned values.

-These two functions both return a value to status_return 

-that indicates what has been returned in the other arguments.

-The possible values returned are:

-</para>

-

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <tbody>

-    <row>

-      <entry><symbol>XBufferOverflow</symbol></entry>

-      <entry>The input string to be returned is too large for the supplied buffer_return.

-      The required size

-      (<function>XmbLookupString</function>

-      in bytes;

-      <function>XwcLookupString</function>

-      in characters) is returned as the value of the function,

-      and the contents of buffer_return and keysym_return are not modified.

-      The client should recall the function with the same event

-      and a buffer of adequate size to obtain the string.</entry>

-    </row>

-    <row>

-      <entry><symbol>XLookupNone</symbol></entry>

-      <entry>No consistent input has been composed so far.

-      The contents of buffer_return and keysym_return are not modified, 

-      and the function returns zero.</entry>

-    </row>

-    <row>

-      <entry><symbol>XLookupChars</symbol></entry>

-      <entry>Some input characters have been composed.

-      They are placed in the buffer_return argument,

-      and the string length is returned as the value of the function.

-      The string is encoded in the locale bound to the input context.

-      The content of the keysym_return argument is not modified.</entry>

-    </row>

-    <row>

-      <entry><symbol>XLookupKeySym</symbol></entry>

-      <entry>A KeySym has been returned instead of a string

-      and is returned in keysym_return.

-      The content of the buffer_return argument is not modified,

-      and the function returns zero.</entry>

-    </row>

-    <row>

-      <entry><symbol>XLookupBoth</symbol></entry>

-      <entry>Both a KeySym and a string are returned;

-      <symbol>XLookupChars</symbol>

-      and

-      <symbol>XLookupKeySym</symbol>

-      occur simultaneously.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-<!-- .LP -->

-It does not make any difference if the input context passed as an argument to

-<function>XmbLookupString</function>

-and

-<function>XwcLookupString</function>

-is the one currently in possession of the focus or not.

-Input may have been composed within an input context before it lost the focus,

-and that input may be returned on subsequent calls to

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>

-even though it does not have any more keyboard focus.

-</para>

-</sect2>

-<sect2 id="Input_Method_Conventions">

-<title>Input Method Conventions</title>

-<!-- .XS -->

-<!-- (SN Input Method Conventions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The input method architecture is transparent to the client.

-However, clients should respect a number of conventions in order

-to work properly.

-Clients must also be aware of possible effects of synchronization

-between input method and library in the case of a remote input server.

-</para>

-<sect3 id="Client_Conventions">

-<title>Client Conventions</title>

-<!-- .XS -->

-<!-- (SN Client Conventions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A well-behaved client (or toolkit) should first query the input method style.

-If the client cannot satisfy the requirements of the supported styles

-(in terms of geometry management or callbacks),

-it should negotiate with the user continuation of the program

-or raise an exception or error of some sort.

-</para>

-</sect3>

-<sect3 id="Synchronization_Conventions">

-<title>Synchronization Conventions</title>

-<!-- .XS -->

-<!-- (SN Synchronization Conventions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A 

-<symbol>KeyPress</symbol>

-event with a KeyCode of zero is used exclusively as a

-signal that an input method has composed input that can be returned by

-<function>XmbLookupString</function>

-or

-<function>XwcLookupString</function>.

-No other use is made of a 

-<symbol>KeyPress</symbol>

-event with KeyCode of zero.

-</para>

-<para>

-<!-- .LP -->

-Such an event may be generated by either a front-end

-or a back-end input method in an implementation-dependent manner.

-Some possible ways to generate this event include:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-A synthetic event sent by an input method server

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-An artificial event created by a input method filter and pushed

-onto a client's event queue

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A 

-<symbol>KeyPress</symbol>

-event whose KeyCode value is modified by an input method filter

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-When callback support is specified by the client,

-input methods will not take action unless they explicitly

-called back the client and obtained no response

-(the callback is not specified or returned invalid data).

-</para>

-</sect3>

-</sect2>

-</sect1>

-<sect1 id="String_Constants">

-<title>String Constants</title>

-<!-- .XS -->

-<!-- (SN String Constants -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The following symbols for string constants are defined in

-&lt;X11/Xlib.h&gt; .

-Although they are shown here with particular macro definitions,

-they may be implemented as macros, as global symbols, or as a

-mixture of the two.  The string pointer value itself

-is not significant; clients must not assume that inequality of two

-values implies inequality of the actual string data.

-</para>

-

-<literallayout class="monospaced">

-#define XNVaNestedList                       "XNVaNestedList"

-#define XNSeparatorofNestedList              "separatorofNestedList"

-#define XNQueryInputStyle                    "queryInputStyle"

-#define XNClientWindow                       "clientWindow"

-#define XNInputStyle                         "inputStyle"

-#define XNFocusWindow                        "focusWindow"

-#define XNResourceName                       "resourceName"

-#define XNResourceClass                      "resourceClass"

-#define XNGeometryCallback                   "geometryCallback"

-#define XNDestroyCallback                    "destroyCallback"

-#define XNFilterEvents                       "filterEvents"

-#define XNPreeditStartCallback               "preeditStartCallback"

-#define XNPreeditDoneCallback                "preeditDoneCallback"

-#define XNPreeditDrawCallback                "preeditDrawCallback"

-#define XNPreeditCaretCallback               "preeditCaretCallback"

-#define XNPreeditStateNotifyCallback         "preeditStateNotifyCallback"

-#define XNPreeditAttributes                  "preeditAttributes"

-#define XNStatusStartCallback                "statusStartCallback"

-#define XNStatusDoneCallback                 "statusDoneCallback"

-#define XNStatusDrawCallback                 "statusDrawCallback"

-#define XNStatusAttributes                   "statusAttributes"

-#define XNArea                               "area"

-#define XNAreaNeeded                         "areaNeeded"

-#define XNSpotLocation                       "spotLocation"

-#define XNColormap                           "colorMap"

-#define XNStdColormap                        "stdColorMap"

-#define XNForeground                         "foreground"

-#define XNBackground                         "background"

-#define XNBackgroundPixmap                   "backgroundPixmap"

-#define XNFontSet                            "fontSet"

-#define XNLineSpace                          "lineSpace"

-#define XNCursor                             "cursor"

-#define XNQueryIMValuesList                  "queryIMValuesList"

-#define XNQueryICValuesList                  "queryICValuesList"

-#define XNStringConversionCallback           "stringConversionCallback"

-#define XNStringConversion                   "stringConversion"

-#define XNResetState                         "resetState"

-#define XNHotKey                             "hotkey"

-#define XNHotKeyState                        "hotkeyState"

-#define XNPreeditState                       "preeditState"

-#define XNVisiblePosition                    "visiblePosition"

-#define XNR6PreeditCallbackBehavior          "r6PreeditCallback"

-#define XNRequiredCharSet                    "requiredCharSet"

-#define XNQueryOrientation                   "queryOrientation"

-#define XNDirectionalDependentDrawing        "directionalDependentDrawing"

-#define XNContextualDrawing                  "contextualDrawing"

-#define XNBaseFontName                       "baseFontName"

-#define XNMissingCharSet                     "missingCharSet"

-#define XNDefaultString                      "defaultString"

-#define XNOrientation                        "orientation"

-#define XNFontInfo                           "fontInfo"

-#define XNOMAutomatic                        "omAutomatic"

-

-</literallayout>

-

-</sect1>

-</chapter>

+<?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="locales_and_internationalized_text_functions">
+<title>Locales and Internationalized Text Functions</title>
+
+<para>
+An internationalized application is one that is adaptable to the requirements of different native
+languages, local customs, and character string encodings. The process of adapting the operation
+to a particular native language, local custom, or string encoding is called localization. A goal of
+internationalization is to permit localization without program source modifications or recompilation.
+</para>
+<para>
+As one of the localization mechanisms, Xlib provides an X Input Method (<acronym>XIM</acronym>)
+functional interface for internationalized text input and an X Output Method
+(<acronym>XOM</acronym>) functional interface for internationalized text output.
+</para>
+<para>
+Internationalization in X is based on the concept of a locale. A locale defines the localized
+behavior of a program at run time. Locales affect Xlib in its:
+</para>
+
+<itemizedlist>
+  <listitem><para>Encoding and processing of input method text</para></listitem>
+  <listitem><para>Encoding of resource files and values</para></listitem>
+  <listitem><para>Encoding and imaging of text strings</para></listitem>
+  <listitem><para>Encoding and decoding for inter-client text communication</para></listitem>
+</itemizedlist>
+
+
+<para>
+•
+Encoding and decoding for inter-client text communication
+Characters from various languages are represented in a computer using an encoding.
+Different languages have different encodings, and there are even different
+encodings for the same characters in the same language.
+</para>
+<para>
+This chapter defines support for localized text imaging and text input and describes the locale
+mechanism that controls all locale-dependent Xlib functions. Sets of functions are provided for
+multibyte (char *) text as well as wide character (wchar_t) text in the form supported by the host
+C language environment. The multibyte and wide character functions are equivalent except for
+the form of the text argument.
+</para>
+<para>
+The Xlib internationalization functions are not meant to provide support for
+multilingual applications (mixing multiple languages within a single piece of text),
+but they make it possible to implement applications that work in limited
+fashion with more than one language in independent contexts.
+</para>
+<para>
+The remainder of this chapter discusses:
+</para>
+
+<itemizedlist>
+  <listitem><para>X locale management</para></listitem>
+  <listitem><para>Locale and modifier dependencies</para></listitem>
+  <listitem><para>Variable argument lists</para></listitem>
+  <listitem><para>Output methods</para></listitem>
+  <listitem><para>Input methods</para></listitem>
+  <listitem><para>String constants</para></listitem>
+</itemizedlist>
+
+
+<sect1 id="X_Locale_Management">
+<title>X Locale Management</title>
+<!-- .XS -->
+<!-- (SN X Locale Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+X supports one or more of the locales defined by the host environment.
+On implementations that conform to the ANSI C library,
+the locale announcement method is
+<function>setlocale</function>.
+This function configures the locale operation of both
+the host C library and Xlib.
+The operation of Xlib is governed by the LC_CTYPE category;
+this is called the <emphasis remap='I'>current locale</emphasis>.
+An implementation is permitted to provide implementation-dependent
+mechanisms for announcing the locale in addition to
+<function>setlocale</function>.
+</para>
+<para>
+<!-- .LP -->
+On implementations that do not conform to the ANSI C library, 
+the locale announcement method is Xlib implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+The mechanism by which the semantic operation of Xlib is defined
+for a specific locale is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+X is not required to support all the locales supported by the host.
+To determine if the current locale is supported by X, use
+<function>XSupportsLocale</function>.
+</para>
+
+<para>Bool XSupportsLocale()</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XSupportsLocale</function>
+function returns 
+<symbol>True</symbol>
+if Xlib functions are capable of operating under the current locale.
+If it returns 
+<symbol>False</symbol>,
+Xlib locale-dependent functions for which the 
+<symbol>XLocaleNotSupported</symbol>
+return status is defined will return 
+<symbol>XLocaleNotSupported</symbol>.
+Other Xlib locale-dependent routines will operate in the ``C'' locale.
+</para>
+<para>
+<!-- .LP -->
+The client is responsible for selecting its locale and X modifiers.
+Clients should provide a means for the user to override the clients'
+locale selection at client invocation.
+Most single-display X clients operate in a single locale 
+for both X and the host processing environment.
+They will configure the locale by calling three functions: 
+the host locale configuration function,
+<function>XSupportsLocale</function>,
+and 
+<function>XSetLocaleModifiers</function>.
+</para>
+<para>
+<!-- .LP -->
+The semantics of certain categories of X internationalization capabilities
+can be configured by setting modifiers.
+Modifiers are named by implementation-dependent and locale-specific strings.
+The only standard use for this capability at present
+is selecting one of several styles of keyboard input method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To configure Xlib locale modifiers for the current locale, use
+<function>XSetLocaleModifiers</function>.
+<indexterm significance="preferred"><primary>XSetLocaleModifiers</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetlocalemodifiers'>
+<funcprototype>
+  <funcdef>char *<function>XSetLocaleModifiers</function></funcdef>
+  <paramdef>char<parameter> *modifier_list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>modifier_list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the modifiers.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetLocaleModifiers</function>
+function sets the X modifiers for the current locale setting.
+The modifier_list argument is a null-terminated string of the form
+``{@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>}'', that is,
+having zero or more concatenated ``@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>''
+entries, where <emphasis remap='I'>category</emphasis> is a category name 
+and <emphasis remap='I'>value</emphasis> is the (possibly empty) setting for that category.
+The values are encoded in the current locale.
+Category names are restricted to the <acronym>POSIX</acronym> Portable Filename Character Set.
+</para>
+<para>
+<!-- .LP -->
+The local host X locale modifiers announcer (on <acronym>POSIX</acronym>-compliant systems,
+the XMODIFIERS environment variable) is appended to the modifier_list to
+provide default values on the local host.
+If a given category appears more than once in the list,
+the first setting in the list is used.
+If a given category is not included in the full modifier list,
+the category is set to an implementation-dependent default
+for the current locale.
+An empty value for a category explicitly specifies the
+implementation-dependent default.
+</para>
+<para>
+<!-- .LP -->
+If the function is successful, it returns a pointer to a string.
+The contents of the string are such that a subsequent call with that string
+(in the same locale) will restore the modifiers to the same settings.
+If modifier_list is a NULL pointer,
+<function>XSetLocaleModifiers</function>
+also returns a pointer to such a string,
+and the current locale modifiers are not changed.
+</para>
+<para>
+<!-- .LP -->
+If invalid values are given for one or more modifier categories supported by
+the locale, a NULL pointer is returned, and none of the
+current modifiers are changed.
+</para>
+<para>
+<!-- .LP -->
+At program startup,
+the modifiers that are in effect are unspecified until
+the first successful call to set them.  Whenever the locale is changed, the
+modifiers that are in effect become unspecified until the next successful call
+to set them.
+Clients should always call
+<function>XSetLocaleModifiers</function>
+with a non-NULL modifier_list after setting the locale
+before they call any locale-dependent Xlib routine.
+</para>
+<para>
+<!-- .LP -->
+The only standard modifier category currently defined is ``im'',
+which identifies the desired input method.
+The values for input method are not standardized.
+A single locale may use multiple input methods,
+switching input method under user control.
+The modifier may specify the initial input method in effect
+or an ordered list of input methods.
+Multiple input methods may be specified in a single im value string
+in an implementation-dependent manner.
+</para>
+<para>
+<!-- .LP -->
+The returned modifiers string is owned by Xlib and should not be modified or
+freed by the client.
+It may be freed by Xlib after the current locale or modifiers are changed.
+Until freed, it will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+The recommended procedure for clients initializing their locale and modifiers
+is to obtain locale and modifier announcers separately from
+one of the following prioritized sources:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+A command line option
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A resource
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The empty string ("")
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The first of these that is defined should be used.
+Note that when a locale command line option or locale resource is defined,
+the effect should be to set all categories to the specified locale,
+overriding any category-specific settings in the local host environment.
+</para>
+</sect1>
+<sect1 id="Locale_and_Modifier_Dependencies">
+<title>Locale and Modifier Dependencies</title>
+<!-- .XS -->
+<!-- (SN Locale and Modifier Dependencies -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The internationalized Xlib functions operate in the current locale
+configured by the host environment and X locale modifiers set by
+<function>XSetLocaleModifiers</function>
+or in the locale and modifiers configured at the time
+some object supplied to the function was created.
+For each locale-dependent function,
+the following table describes the locale (and modifiers) dependency:
+</para>
+
+<informaltable>
+  <tgroup cols='3' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <thead>
+    <row>
+      <entry>Locale from</entry>
+      <entry>Affects the Function</entry>
+      <entry>In</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry></entry>
+      <entry>Locale Query/Configuration:</entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry><function>XSupportsLocale</function></entry>
+      <entry>Locale queried</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XSetLocaleModifiers</function></entry>
+      <entry>Locale modified</entry>
+    </row>
+    <row>
+      <entry></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>Resources:</entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry><function>XrmGetFileDatabase</function></entry>
+      <entry>Locale of <type>XrmDatabase</type></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XrmGetStringDatabase</function></entry>
+    </row>
+    <row>
+      <entry><type>XrmDatabase</type></entry>
+      <entry><function>XrmPutFileDatabase</function></entry>
+      <entry>Locale of <type>XrmDatabase</type></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XrmLocaleOfDatabase</function></entry>
+    </row>
+    <row>
+      <entry></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>Setting Standard Properties:</entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry><function>XmbSetWMProperties</function></entry>
+      <entry>Encoding of supplied/returned
+      text (some WM_ property
+      text in environment locale)</entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry><function>XmbTextPropertyToTextList</function></entry>
+      <entry>Encoding of supplied/returned text</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XwcTextPropertyToTextList</function></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XmbTextListToTextProperty</function></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XwcTextListToTextProperty</function></entry>
+    </row>
+    <row>
+      <entry></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>Text Input:</entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry><function>XOpenIM</function></entry>
+      <entry><acronym>XIM</acronym> input method selection</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XRegisterIMInstantiateCallback</function></entry>
+      <entry><acronym>XIM</acronym> selection</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XUnregisterIMInstantiateCallback</function></entry>
+      <entry><acronym>XIM</acronym> selection</entry>
+    </row>
+    <row>
+      <entry><type>XIM</type></entry>
+      <entry><function>XCreateIC</function></entry>
+      <entry><acronym>XIC</acronym> input method configuration</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XLocaleOfIM</function>,  and so on</entry>
+      <entry>Queried locale</entry>
+    </row>
+    <row>
+      <entry><type>XIC</type></entry>
+      <entry><function>XmbLookupString</function></entry>
+      <entry>Keyboard layout</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XwcLookupString</function></entry>
+      <entry>Encoding of returned text</entry>
+    </row>
+    <row>
+      <entry></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>Text Drawing:</entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry><function>XOpenOM</function></entry>
+      <entry><acronym>XOM</acronym> output method selection</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XCreateFontSet</function></entry>
+      <entry>Charsets of fonts in XFontSet</entry>
+    </row>
+    <row>
+      <entry><type>XOM</type></entry>
+      <entry><function>XCreateOC</function></entry>
+      <entry><acronym>XOC</acronym> output method configuration</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XLocaleOfOM</function>,  and so on</entry>
+      <entry>Queried locale</entry>
+    </row>
+    <row>
+      <entry><type>XFontSet</type></entry>
+      <entry><function>XmbDrawText</function>,</entry>
+      <entry>Locale of supplied text</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XwcDrawText</function>, and so on</entry>
+      <entry>Locale of supplied text</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XExtentsOfFontSet</function>, and so on</entry>
+      <entry>Locale-dependent metrics</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XmbTextExtents</function>,</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XwcTextExtents</function>,  and so on</entry>
+    </row>
+    <row>
+      <entry></entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>Xlib Errors:</entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry><function>XGetErrorDatabaseText</function></entry>
+      <entry>Locale of error message</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry><function>XGetErrorText</function></entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Clients may assume that a locale-encoded text string returned 
+by an X function can be passed to a C library routine, or vice versa,
+if the locale is the same at the two calls.
+</para>
+<para>
+<!-- .LP -->
+All text strings processed by internationalized Xlib functions are assumed
+to begin in the initial state of the encoding of the locale, if the encoding
+is state-dependent.
+</para>
+<para>
+<!-- .LP -->
+All Xlib functions behave as if they do not change the current locale
+or X modifier setting.
+(This means that if they do change locale or call 
+<function>XSetLocaleModifiers</function>
+with a non-NULL argument, they must save and restore the current state on
+entry and exit.)
+Also, Xlib functions on implementations that conform to the ANSI C library do
+not alter the global state associated with the ANSI C functions 
+<function>mblen</function>,
+<function>mbtowc</function>,
+<function>wctomb</function>,
+and 
+<function>strtok</function>.
+</para>
+</sect1>
+<sect1 id="Variable_Argument_Lists">
+<title>Variable Argument Lists</title>
+<!-- .XS -->
+<!-- (SN Variable Argument Lists -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Various functions in this chapter have arguments that conform
+to the ANSI C variable argument list calling convention.
+Each function denoted with an argument of the form ``...'' takes 
+a variable-length list of name and value pairs,
+where each name is a string and each value is of type 
+<type>XPointer</type>.
+A name argument that is NULL identifies the end of the list. 
+</para>
+<para>
+<!-- .LP -->
+A variable-length argument list may contain a nested list.
+If the name 
+<symbol>XNVaNestedList</symbol>
+is specified in place of an argument name,
+then the following value is interpreted as an 
+<type>XVaNestedList</type>
+value that specifies a list of values logically inserted into the
+original list at the point of declaration.
+A NULL identifies the end of a nested list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a nested variable argument list dynamically, use
+<function>XVaCreateNestedList</function>.
+<indexterm significance="preferred"><primary>XVaCreateNestedList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xvacreatenestedlist'>
+<funcprototype>
+  <funcdef>XVaNestedList <function>XVaCreateNestedList</function></funcdef>
+  <paramdef>int<parameter> dummy</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dummy</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an unused argument (required by ANSI C).
+<!-- .ds Al -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XVaCreateNestedList</function>
+function allocates memory and copies its arguments into
+a single list pointer,
+which may be used as a value for arguments requiring a list value.
+Any entries are copied as specified.
+Data passed by reference is not copied;
+the caller must ensure data remains valid for the lifetime
+of the nested list.
+The list should be freed using
+<function>XFree</function>
+when it is no longer needed.
+</para>
+</sect1>
+<sect1 id="Output_Methods">
+<title>Output Methods</title>
+<!-- .XS -->
+<!-- (SN Output Methods -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section provides discussions of the following X Output Method
+(<acronym>XOM</acronym>) topics:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Output method overview
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Output method functions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Output method values
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Output context functions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Output context values
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Creating and freeing a font set
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Obtaining font set metrics
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Drawing text using font sets
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Output_Method_Overview">
+<title>Output Method Overview</title>
+<!-- .XS -->
+<!-- (SN Output Method Overview -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Locale-dependent text may include one or more text components, each of
+which may require different fonts and character set encodings.
+In some languages, each component might have a different
+drawing direction, and some components might contain
+context-dependent characters that change shape based on
+relationships with neighboring characters.
+</para>
+<para>
+<!-- .LP -->
+When drawing such locale-dependent text, some locale-specific
+knowledge is required;
+for example, what fonts are required to draw the text,
+how the text can be separated into components, and which
+fonts are selected to draw each component.
+Further, when bidirectional text must be drawn,
+the internal representation order of the text must be changed
+into the visual representation order to be drawn.
+</para>
+<para>
+<!-- .LP -->
+An X Output Method provides a functional interface so that clients
+do not have to deal directly with such locale-dependent details.
+Output methods provide the following capabilities:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Creating a set of fonts required to draw locale-dependent text.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Drawing locale-dependent text with a font set without the caller
+needing to be aware of locale dependencies.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Obtaining the escapement and extents in pixels of locale-dependent text.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Determining if bidirectional or context-dependent drawing is required
+in a specific locale with a specific font set.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Two different abstractions are used in the representation of
+the output method for clients.
+</para>
+<para>
+<!-- .LP -->
+The abstraction used to communicate with an output method
+is an opaque data structure represented by the 
+<type>XOM</type>
+data type.
+The abstraction for representing the state of a particular output thread
+is called an <emphasis remap='I'>output context</emphasis>.
+The Xlib representation of an output context is an 
+<type>XOC</type>,
+which is compatible with 
+<type>XFontSet</type>
+in terms of its functional interface, but is 
+a broader, more generalized abstraction.
+</para>
+</sect2>
+<sect2 id="Output_Method_Functions">
+<title>Output Method Functions</title>
+<!-- .XS -->
+<!-- (SN Output Method Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To open an output method, use
+<function>XOpenOM</function>.
+<indexterm significance="preferred"><primary>XOpenOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xopenom'>
+<funcprototype>
+  <funcdef>XOM <function>XOpenOM</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>
+  <paramdef>char<parameter> *res_name</parameter></paramdef>
+  <paramdef>char<parameter> *res_class</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>res_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the full resource name of the application.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>res_class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the full class name of the application.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XOpenOM</function>
+function opens an output method
+matching the current locale and modifiers specification.
+The current locale and modifiers are bound to the output method
+when
+<function>XOpenOM</function>
+is called.
+The locale associated with an output method cannot be changed.
+</para>
+<para>
+<!-- .LP -->
+The specific output method to which this call will be routed
+is identified on the basis of the current locale and modifiers.
+<function>XOpenOM</function>
+will identify a default output method corresponding to the
+current locale.
+That default can be modified using 
+<function>XSetLocaleModifiers</function>
+to set the output method modifier.
+</para>
+<para>
+<!-- .LP -->
+The db argument is the resource database to be used by the output method
+for looking up resources that are private to the output method.
+It is not intended that this database be used to look
+up values that can be set as OC values in an output context.
+If db is NULL,
+no database is passed to the output method.
+</para>
+<para>
+<!-- .LP -->
+The res_name and res_class arguments specify the resource name 
+and class of the application. 
+They are intended to be used as prefixes by the output method
+when looking up resources that are common to all output contexts
+that may be created for this output method.
+The characters used for resource names and classes must be in the
+X Portable Character Set.
+The resources looked up are not fully specified
+if res_name or res_class is NULL.
+</para>
+<para>
+<!-- .LP -->
+The res_name and res_class arguments are not assumed to exist beyond
+the call to
+<function>XOpenOM</function>.
+The specified resource database is assumed to exist for the lifetime
+of the output method.
+</para>
+<para>
+<!-- .LP -->
+<function>XOpenOM</function>
+returns NULL if no output method could be opened.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To close an output method, use
+<function>XCloseOM</function>.
+<indexterm significance="preferred"><primary>XCloseOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcloseom'>
+<funcprototype>
+  <funcdef>Status <function>XCloseOM</function></funcdef>
+  <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>om</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output method.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCloseOM</function>
+function closes the specified output method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set output method attributes, use 
+<function>XSetOMValues</function>.
+<indexterm significance="preferred"><primary>XSetOMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetomvalues'>
+<funcprototype>
+  <funcdef>char *<function>XSetOMValues</function></funcdef>
+  <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>om</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output method.
+<!-- .ds Al \ to set <acronym>XOM</acronym> values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable-length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetOMValues</function>
+function presents a variable argument list programming interface
+for setting properties or features of the specified output method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+</para>
+<para>
+<!-- .LP -->
+No standard arguments are currently defined by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To query an output method, use 
+<function>XGetOMValues</function>.
+<indexterm significance="preferred"><primary>XGetOMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetomvalues'>
+<funcprototype>
+  <funcdef>char *<function>XGetOMValues</function></funcdef>
+  <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>om</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output method.
+<!-- .ds Al \ to get XOM values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable-length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetOMValues</function>
+function presents a variable argument list programming interface
+for querying properties or features of the specified output method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+</para>
+<para>
+<!-- .LP -->
+To obtain the display associated with an output method, use
+<function>XDisplayOfOM</function>.
+<indexterm significance="preferred"><primary>XDisplayOfOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplayofom'>
+<funcprototype>
+  <funcdef>Display *<function>XDisplayOfOM</function></funcdef>
+  <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>om</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output method.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayOfOM</function>
+function returns the display associated with the specified output method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the locale associated with an output method, use
+<function>XLocaleOfOM</function>.
+<indexterm significance="preferred"><primary>XLocaleOfOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlocaleofom'>
+<funcprototype>
+  <funcdef>char *<function>XLocaleOfOM</function></funcdef>
+  <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>om</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output method.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLocaleOfOM</function>
+returns the locale associated with the specified output method.
+</para>
+</sect2>
+<sect2 id="X_Output_Method_Values">
+<title>X Output Method Values</title>
+<!-- .XS -->
+<!-- (SN X Output Method Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following table describes how <acronym>XOM</acronym> values are interpreted by an
+output method.
+The first column lists the <acronym>XOM</acronym> values.  The second column indicates
+how each of the <acronym>XOM</acronym> values are treated by a particular output style.
+</para>
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+The following key applies to this table.
+</para>
+
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry>Key</entry>
+      <entry>Explanation</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>G</entry>
+      <entry>This value may be read using <function>XGetOMValues</function>.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry><acronym>XOM</acronym> Value</entry>
+      <entry>Key</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry><symbol>XNRequiredCharSet</symbol></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNQueryOrientation</symbol></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNDirectionalDependentDrawing</symbol></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNContextualDrawing</symbol></entry>
+      <entry>G</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+</para>
+<sect3 id="Required_Char_Set">
+<title>Required Char Set</title>
+<!-- .XS -->
+<!-- (SN Required Char Set -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNRequiredCharSet</symbol>
+argument returns the list of charsets that are required for loading the fonts
+needed for the locale.
+The value of the argument is a pointer to a structure of type
+<structname>XOMCharSetList</structname>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XOMCharSetList</structname>
+structure is defined as follows:
+<indexterm significance="preferred"><primary>XOMCharSetList</primary></indexterm>
+<!-- .sM -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+     int    charset_count;
+     char   **charset_list;
+} XOMCharSetList;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The charset_list member is a list of one or more null-terminated
+charset names, and the charset_count member is the number of
+charset names.
+</para>
+<para>
+<!-- .LP -->
+The required charset list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to 
+<function>XCloseOM</function>
+with the associated 
+<type>XOM</type>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Query_Orientation">
+<title>Query Orientation</title>
+<!-- .XS -->
+<!-- (SN Query Orientation -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNQueryOrientation</symbol>
+argument returns the global orientation of text when drawn.
+Other than
+<constant>XOMOrientation_LTR_TTB</constant>,
+the set of orientations supported is locale-dependent.
+The value of the argument is a pointer to a structure of type
+<structname>XOMOrientation</structname>.
+Clients are responsible for freeing the
+<structname>XOMOrientation</structname>
+structure by using
+<function>XFree</function>;
+this also frees the contents of the structure.
+</para>
+
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+     int          num_orientation;
+     XOrientation *orientation;     /* Input Text description */
+} XOMOrientation;
+
+typedef enum {
+     XOMOrientation_LTR_TTB,
+     XOMOrientation_RTL_TTB,     
+     XOMOrientation_TTB_LTR,
+     XOMOrientation_TTB_RTL,
+     XOMOrientation_Context
+} XOrientation;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The possible value for XOrientation may be:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<constant>XOMOrientation_LTR_TTB</constant>
+left-to-right, top-to-bottom global orientation
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<constant>XOMOrientation_RTL_TTB</constant>
+right-to-left, top-to-bottom global orientation
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<constant>XOMOrientation_TTB_LTR</constant>
+top-to-bottom, left-to-right global orientation
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<constant>XOMOrientation_TTB_RTL</constant>
+top-to-bottom, right-to-left global orientation
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<constant>XOMOrientation_Context</constant>
+contextual global orientation
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Directional_Dependent_Drawing">
+<title>Directional Dependent Drawing</title>
+<!-- .XS -->
+<!-- (SN Directional Dependent Drawing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNDirectionalDependentDrawing</symbol>
+argument indicates whether the text rendering functions
+implement implicit handling of directional text.  If this value
+is
+<symbol>True</symbol>,
+the output method has knowledge of directional
+dependencies and reorders text as necessary when
+rendering text.  If this value is
+<symbol>False</symbol>,
+the output method does not implement any directional text
+handling, and all character directions are assumed to be left-to-right.
+</para>
+<para>
+<!-- .LP -->
+Regardless of the rendering order of characters,
+the origins of all characters are on the primary draw direction side
+of the drawing origin.
+</para>
+<para>
+<!-- .LP -->
+This OM value presents functionality identical to the
+<function>XDirectionalDependentDrawing</function>
+function.
+</para>
+</sect3>
+<sect3 id="Context_Dependent_Drawing">
+<title>Context Dependent Drawing</title>
+<!-- .XS -->
+<!-- (SN Context Dependent Drawing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNContextualDrawing</symbol>
+argument indicates whether the text rendering functions
+implement implicit context-dependent drawing.  If this value is
+<symbol>True</symbol>,
+the output method has knowledge of context dependencies and
+performs character shape editing, combining glyphs to present
+a single character as necessary.  The actual shape editing is
+dependent on the locale implementation and the font set used.
+</para>
+<para>
+<!-- .LP -->
+This OM value presents functionality identical to the
+<function>XContextualDrawing</function>
+function.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Output_Context_Functions">
+<title>Output Context Functions</title>
+<!-- .XS -->
+<!-- (SN Output Context Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An output context is an abstraction that contains both the data
+required by an output method and the information required
+to display that data.
+There can be multiple output contexts for one output method.
+The programming interfaces for creating, reading, or modifying
+an output context use a variable argument list.
+The name elements of the argument lists are referred to as <acronym>XOC</acronym> values.
+It is intended that output methods be controlled by these <acronym>XOC</acronym> values.
+As new <acronym>XOC</acronym> values are created,
+they should be registered with the X Consortium.
+An
+<type>XOC</type>
+can be used anywhere an
+<type>XFontSet</type>
+can be used, and vice versa;
+<type>XFontSet</type>
+is retained for compatibility with previous releases.
+The concepts of output methods and output contexts include broader,
+more generalized abstraction than font set,
+supporting complex and more intelligent text display, and dealing not only
+with multiple fonts but also with context dependencies.
+However,
+<type>XFontSet</type>
+is widely used in several interfaces, so
+<type>XOC</type>
+is defined as an upward compatible type of
+<type>XFontSet</type>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create an output context, use
+<function>XCreateOC</function>.
+<indexterm significance="preferred"><primary>XCreateOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreateoc'>
+<funcprototype>
+  <funcdef>XOC <function>XCreateOC</function></funcdef>
+  <paramdef>XOM<parameter> om</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>om</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output method.
+<!-- .ds Al \ to set <acronym>XOC</acronym> values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable-length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateOC</function>
+function creates an output context within the specified output method.
+</para>
+<para>
+<!-- .LP -->
+The base font names argument is mandatory at creation time, and
+the output context will not be created unless it is provided.
+All other output context values can be set later.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateOC</function>
+returns NULL if no output context could be created.
+NULL can be returned for any of the following reasons:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+A required argument was not set.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A read-only argument was set.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+An argument name is not recognized.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The output method encountered an output method implementation-dependent error.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XCreateOC</function>
+can generate a
+<errorname>BadAtom</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy an output context, use
+<function>XDestroyOC</function>.
+<indexterm significance="preferred"><primary>XDestroyOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroyoc'>
+<funcprototype>
+  <funcdef>void <function>XDestroyOC</function></funcdef>
+  <paramdef>XOC<parameter> oc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>oc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output context.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDestroyOC</function>
+function destroys the specified output context.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the output method associated with an output context, use
+<function>XOMOfOC</function>.
+<indexterm significance="preferred"><primary>XOMOfOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xomofoc'>
+<funcprototype>
+  <funcdef>XOM <function>XOMOfOC</function></funcdef>
+  <paramdef>XOC<parameter> oc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>oc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output context.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XOMOfOC</function>
+function returns the output method associated with the
+specified output context.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Xlib provides two functions for setting and reading output context values,
+respectively,
+<function>XSetOCValues</function>
+and
+<function>XGetOCValues</function>.
+Both functions have a variable-length argument list.
+In that argument list, any <acronym>XOC</acronym> value's name must be denoted
+with a character string using the X Portable Character Set.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set <acronym>XOC</acronym> values, use
+<function>XSetOCValues</function>.
+<indexterm significance="preferred"><primary>XSetOCValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetocvalues'>
+<funcprototype>
+  <funcdef>char *<function>XSetOCValues</function></funcdef>
+  <paramdef>XOC<parameter> oc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>oc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output context.
+<!-- .ds Al \ to set <acronym>XOC</acronym> values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable-length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetOCValues</function>
+function returns NULL if no error occurred; 
+otherwise,
+it returns the name of the first argument that could not be set.
+An argument might not be set for any of the following reasons:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The argument is read-only.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The argument name is not recognized.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+An implementation-dependent error occurs.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Each value to be set must be an appropriate datum,
+matching the data type imposed by the semantics of the argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetOCValues</function>
+can generate a
+<errorname>BadAtom</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain <acronym>XOC</acronym> values, use
+<function>XGetOCValues</function>.
+<indexterm significance="preferred"><primary>XGetOCValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetocvalues'>
+<funcprototype>
+  <funcdef>char *<function>XGetOCValues</function></funcdef>
+  <paramdef>XOC<parameter> oc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>oc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the output context.
+<!-- .ds Al \ to get XOC values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable-length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetOCValues</function>
+function returns NULL if no error occurred; otherwise,
+it returns the name of the first argument that could not be obtained.
+An argument might not be obtained for any of the following reasons:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The argument name is not recognized.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+An implementation-dependent error occurs.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Each argument value
+following a name must point to a location where the value is to be stored.
+</para>
+</sect2>
+
+<sect2 id="Output_Context_Values">
+<title>Output Context Values</title>
+<!-- .XS -->
+<!-- (SN Output Context Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following table describes how <acronym>XOC</acronym> values are interpreted
+by an output method.
+The first column lists the <acronym>XOC</acronym> values.
+The second column indicates the alternative interfaces that function
+identically and are provided for compatibility with previous releases.
+The third column indicates how each of the <acronym>XOC</acronym> values is treated.
+</para>
+<!-- .LP -->
+<para>
+The following keys apply to this table.
+</para>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry>Key</entry>
+      <entry>Explanation</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>C</entry>
+      <entry>This value must be set with <function>XCreateOC</function>.</entry>
+    </row>
+    <row>
+      <entry>D</entry>
+      <entry>This value may be set using <function>XCreateOC</function>.
+      If it is not set,a default is provided.</entry>
+    </row>
+    <row>
+      <entry>G</entry>
+      <entry>This value may be read using <function>XGetOCValues</function>.</entry>
+    </row>
+    <row>
+      <entry>S</entry>
+      <entry>This value must be set using <function>XSetOCValues</function>.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<!-- .LP -->
+<informaltable>
+  <tgroup cols='3' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <thead>
+    <row>
+      <entry><acronym>XOC</acronym> Value</entry>
+      <entry>Alternative Interface</entry>
+      <entry>Key</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>BaseFontName</entry>
+      <entry><function>XCreateFontSet</function></entry>
+      <entry>C-G</entry>
+    </row>
+    <row>
+      <entry>MissingCharSet</entry>
+      <entry><function>XCreateFontSet</function></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry>DefaultString</entry>
+      <entry><function>XCreateFontSet</function></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry>Orientation</entry>
+      <entry>-</entry>
+      <entry>D-S-G</entry>
+    </row>
+    <row>
+      <entry>ResourceName</entry>
+      <entry>-</entry>
+      <entry>S-G</entry>
+    </row>
+    <row>
+      <entry>ResourceClass</entry>
+      <entry>-</entry>
+      <entry>S-G</entry>
+    </row>
+    <row>
+      <entry>FontInfo</entry>
+      <entry><function>XFontsOfFontSet</function></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry>OMAutomatic</entry>
+      <entry>-</entry>
+      <entry>G</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+</para>
+<sect3 id="Base_Font_Name">
+<title>Base Font Name</title>
+<!-- .XS -->
+<!-- (SN Base Font Name -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNBaseFontName</symbol>
+argument is a list of base font names that Xlib uses
+to load the fonts needed for the locale.
+The base font names are a comma-separated list.  The string is null-terminated
+and is assumed to be in the Host Portable Character Encoding;
+otherwise, the result is implementation-dependent.
+White space immediately on either side of a separating comma is ignored.
+</para>
+<para>
+<!-- .LP -->
+Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a
+variety of locales from a single locale-independent base font name.
+The single base font name should name a family of fonts whose members
+are encoded in the various charsets needed by the locales of interest.
+</para>
+<para>
+<!-- .LP -->
+An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.
+This allows the user to specify an exact font for use with a charset required
+by a locale, fully controlling the font selection.
+</para>
+<para>
+<!-- .LP -->
+If a base font name is not an <acronym>XLFD</acronym> name,
+Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties
+for the font.
+If Xlib is successful, the
+<function>XGetOCValues</function>
+function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.
+</para>
+<para>
+<!-- .LP -->
+This argument must be set at creation time
+and cannot be changed.
+If no fonts exist for any of the required charsets,
+or if the locale definition in Xlib requires that a font exist
+for a particular charset and a font is not found for that charset,
+<function>XCreateOC</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+When querying for the
+<symbol>XNBaseFontName</symbol>
+<acronym>XOC</acronym> value,
+<function>XGetOCValues</function>
+returns a null-terminated string identifying the base font names that
+Xlib used to load the fonts needed for the locale.
+This string is owned by Xlib and should not be modified or freed by
+the client.
+The string will be freed by a call to
+<function>XDestroyOC</function>
+with the associated
+<type>XOC</type>.
+Until freed, the string contents will not be modified by Xlib.
+</para>
+</sect3>
+<sect3 id="Missing_CharSet">
+<title>Missing CharSet</title>
+<!-- .XS -->
+<!-- (SN Missing CharSet -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNMissingCharSet</symbol>
+argument returns the list of required charsets that are missing from the
+font set.
+The value of the argument is a pointer to a structure of type
+<structname>XOMCharSetList</structname>.
+</para>
+<para>
+<!-- .LP -->
+If fonts exist for all of the charsets required by the current locale,
+charset_list is set to NULL and charset_count is set to zero.
+If no fonts exist for one or more of the required charsets,
+charset_list is set to a list of one or more null-terminated charset names
+for which no fonts exist, and charset_count is set to the number of
+missing charsets.
+The charsets are from the list of the required charsets for
+the encoding of the locale and do not include any charsets to which Xlib
+may be able to remap a required charset.
+</para>
+<para>
+<!-- .LP -->
+The missing charset list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to 
+<function>XDestroyOC</function>
+with the associated
+<type>XOC</type>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+</sect3>
+<sect3 id="Default_String">
+<title>Default String</title>
+<!-- .XS -->
+<!-- (SN Default String -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When a drawing or measuring function is called with an
+<type>XOC</type>
+that has missing charsets, some characters in the locale will not be
+drawable.
+The
+<symbol>XNDefaultString</symbol>
+argument returns a pointer to a string that represents the glyphs
+that are drawn with this
+<type>XOC</type>
+when the charsets of the available fonts do not include all glyphs
+required to draw a character.
+The string does not necessarily consist of valid characters
+in the current locale and is not necessarily drawn with
+the fonts loaded for the font set,
+but the client can draw or measure the default glyphs
+by including this string in a string being drawn or measured with the
+<type>XOC</type>.
+</para>
+<para>
+<!-- .LP -->
+If the
+<symbol>XNDefaultString</symbol>
+argument returned the empty string (""),
+no glyphs are drawn and the escapement is zero.
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It will be freed by a call to
+<function>XDestroyOC</function>
+with the associated
+<type>XOC</type>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+</sect3>
+<sect3 id="Orientation">
+<title>Orientation</title>
+<!-- .XS -->
+<!-- (SN Orientation -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNOrientation</symbol>
+argument specifies the current orientation of text when drawn.  The value of
+this argument is one of the values returned by the
+<function>XGetOMValues</function>
+function with the
+<symbol>XNQueryOrientation</symbol>
+argument specified in the
+<type>XOrientation</type>
+list.
+The value of the argument is of type
+<type>XOrientation</type>.
+When
+<symbol>XNOrientation</symbol>
+is queried, the value specifies the current orientation.  
+When
+<symbol>XNOrientation</symbol>
+is set, a value is used to set the current orientation.
+</para>
+<para>
+<!-- .LP -->
+When 
+<constant>XOMOrientation_Context</constant>
+is set, the text orientation of the 
+text is determined according to an implementation-defined method
+(for example, ISO 6429 control sequences), and the initial text orientation for
+locale-dependent Xlib functions is assumed to 
+be
+<constant>XOMOrientation_LTR_TTB</constant>.
+</para>
+<para>
+<!-- .LP -->
+The
+<symbol>XNOrientation</symbol>
+value does not change the prime drawing direction 
+for Xlib drawing functions.  
+</para>
+</sect3>
+<sect3 id="Resource_Name_and_Class">
+<title>Resource Name and Class</title>
+<!-- .XS -->
+<!-- (SN Resource Name and Class -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNResourceName</symbol>
+and
+<symbol>XNResourceClass</symbol>
+arguments are strings that specify the full name and class
+used by the client to obtain resources for the display of the output context.
+These values should be used as prefixes for name and class
+when looking up resources that may vary according to the output context.
+If these values are not set,
+the resources will not be fully specified.
+</para>
+<para>
+<!-- .LP -->
+It is not intended that values that can be set as <acronym>XOM</acronym> values be
+set as resources.
+</para>
+<para>
+<!-- .LP -->
+When querying for the
+<symbol>XNResourceName</symbol>
+or
+<symbol>XNResourceClass</symbol>
+<acronym>XOC</acronym> value,
+<function>XGetOCValues</function>
+returns a null-terminated string.
+This string is owned by Xlib and should not be modified or freed by
+the client.
+The string will be freed by a call to
+<function>XDestroyOC</function>
+with the associated
+<type>XOC</type>
+or when the associated value is changed via
+<function>XSetOCValues</function>.
+Until freed, the string contents will not be modified by Xlib.
+</para>
+</sect3>
+<sect3 id="Font_Info">
+<title>Font Info</title>
+<!-- .XS -->
+<!-- (SN Font Info -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNFontInfo</symbol>
+argument specifies a list of one or more 
+<structname>XFontStruct</structname>
+structures
+and font names for the fonts used for drawing by the given output context.
+The value of the argument is a pointer to a structure of type
+<structname>XOMFontInfo</structname>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+     int         num_font;
+     XFontStruct **font_struct_list;
+     char        **font_name_list;
+} XOMFontInfo;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+A list of pointers to the
+<structname>XFontStruct</structname>
+structures is returned to font_struct_list.
+A list of pointers to null-terminated, fully-specified font name strings
+in the locale of the output context is returned to font_name_list.
+The font_name_list order corresponds to the font_struct_list order.
+The number of
+<structname>XFontStruct</structname>
+structures and font names is returned to num_font.
+</para>
+<para>
+<!-- .LP -->
+Because it is not guaranteed that a given character will be imaged using a
+single font glyph,
+there is no provision for mapping a character or default string 
+to the font properties, font ID, or direction hint for the font 
+for the character.
+The client may access the 
+<structname>XFontStruct</structname>
+list to obtain these values for all the fonts currently in use.
+</para>
+<para>
+<!-- .LP -->
+Xlib does not guarantee that fonts are loaded from the server
+at the creation of an 
+<type>XOC</type>.
+Xlib may choose to cache font data, loading it only as needed to draw text 
+or compute text dimensions.
+Therefore, existence of the per_char metrics in the 
+<structname>XFontStruct</structname>
+structures in the
+<structname>XFontStructSet</structname>
+is undefined.
+Also, note that all properties in the 
+<structname>XFontStruct</structname>
+structures are in the STRING encoding.
+</para>
+<para>
+<!-- .LP -->
+The client must not free the 
+<structname>XOMFontInfo</structname>
+struct itself; it will be freed when the
+<type>XOC</type>
+is closed.
+</para>
+</sect3>
+<sect3 id="OM_Automatic">
+<title>OM Automatic</title>
+<!-- .XS -->
+<!-- (SN OM Automatic -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNOMAutomatic</symbol>
+argument returns whether the associated output context was created by
+<function>XCreateFontSet</function>
+or not.  Because the
+<function>XFreeFontSet</function>
+function not only destroys the output context but also closes the implicit
+output method associated with it,
+<function>XFreeFontSet</function>
+should be used with any output context created by 
+<function>XCreateFontSet</function>.
+However, it is possible that a client does not know how the output context
+was created.
+Before a client destroys the output context,
+it can query whether
+<symbol>XNOMAutomatic</symbol>
+is set to determine whether 
+<function>XFreeFontSet</function>
+or 
+<function>XDestroyOC</function>
+should be used to destroy the output context.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Creating_and_Freeing_a_Font_Set">
+<title>Creating and Freeing a Font Set</title>
+<!-- .XS -->
+<!-- (SN Creating and Freeing a Font Set -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib international text drawing is done using a set of one or more fonts,
+as needed for the locale of the text.
+Fonts are loaded according to a list of base font names 
+supplied by the client and the charsets required by the locale.
+The
+<type>XFontSet</type>
+is an opaque type representing the state of a particular output thread
+and is equivalent to the type
+<type>XOC</type>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The 
+<function>XCreateFontSet</function>
+function is a convenience function for creating an output context using
+only default values.  The returned
+<type>XFontSet</type>
+has an implicitly created
+<type>XOM</type>.
+This
+<type>XOM</type>
+has an OM value
+<symbol>XNOMAutomatic</symbol>
+automatically set to
+<symbol>True</symbol>
+so that the output context self indicates whether it was created by
+<function>XCreateOC</function>
+or
+<function>XCreateFontSet</function>.
+<indexterm significance="preferred"><primary>XCreateFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatefontset'>
+<funcprototype>
+  <funcdef>XFontSet <function>XCreateFontSet</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *base_font_name_list</parameter></paramdef>
+  <paramdef>char<parameter> ***missing_charset_list_return</parameter></paramdef>
+  <paramdef>int<parameter> *missing_charset_count_return</parameter></paramdef>
+  <paramdef>char<parameter> **def_string_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>base_font_name_list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the base font names.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>missing_charset_list_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the missing charsets.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>missing_charset_count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of missing charsets.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>def_string_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the string drawn for missing charsets.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XCreateFontSet</function>
+function creates a font set for the specified display.
+The font set is bound to the current locale when 
+<function>XCreateFontSet</function>
+is called.
+The font set may be used in subsequent calls to obtain font
+and character information and to image text in the locale of the font set.
+</para>
+<para>
+<!-- .LP -->
+The base_font_name_list argument is a list of base font names
+that Xlib uses to load the fonts needed for the locale.
+The base font names are a comma-separated list.
+The string is null-terminated
+and is assumed to be in the Host Portable Character Encoding; 
+otherwise, the result is implementation-dependent.
+White space immediately on either side of a separating comma is ignored.
+</para>
+<para>
+<!-- .LP -->
+Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a
+variety of locales from a single locale-independent base font name.
+The single base font name should name a family of fonts whose members
+are encoded in the various charsets needed by the locales of interest.
+</para>
+<para>
+<!-- .LP -->
+An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.
+This allows the user to specify an exact font for use with a charset required
+by a locale, fully controlling the font selection.
+</para>
+<para>
+<!-- .LP -->
+If a base font name is not an <acronym>XLFD</acronym> name,
+Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties
+for the font.
+If this action is successful in obtaining an <acronym>XLFD</acronym> name, the
+<function>XBaseFontNameListOfFontSet</function>
+function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.
+</para>
+<para>
+<!-- .LP -->
+Xlib uses the following algorithm to select the fonts
+that will be used to display text with the 
+<type>XFontSet</type>.
+</para>
+<para>
+<!-- .LP -->
+For each font charset required by the locale,
+the base font name list is searched for the first appearance of one 
+of the following cases that names a set of fonts that exist at the server:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The first <acronym>XLFD</acronym>-conforming base font name that specifies the required
+charset or a superset of the required charset in its 
+<structfield>CharSetRegistry</structfield>
+and 
+<structfield>CharSetEncoding</structfield>
+fields.
+The implementation may use a base font name whose specified charset
+is a superset of the required charset, for example,
+an ISO8859-1 font for an ASCII charset.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The first set of one or more <acronym>XLFD</acronym>-conforming base font names
+that specify one or more charsets that can be remapped to support the
+required charset.
+The Xlib implementation may recognize various mappings 
+from a required charset to one or more other charsets
+and use the fonts for those charsets.
+For example, JIS Roman is ASCII with tilde and backslash replaced 
+by yen and overbar;
+Xlib may load an ISO8859-1 font to support this character set
+if a JIS Roman font is not available.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The first <acronym>XLFD</acronym>-conforming font name or the first non-<acronym>XLFD</acronym> font name
+for which an <acronym>XLFD</acronym> font name can be obtained, combined with the
+required charset (replacing the 
+<structfield>CharSetRegistry</structfield>
+and
+<structfield>CharSetEncoding</structfield>
+fields in the <acronym>XLFD</acronym> font name).
+As in case 1,
+the implementation may use a charset that is a superset
+of the required charset.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The first font name that can be mapped in some implementation-dependent
+manner to one or more fonts that support imaging text in the charset.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+For example, assume that a locale required the charsets:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+ISO8859-1
+JISX0208.1983
+JISX0201.1976
+GB2312-1980.0
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The user could supply a base_font_name_list that explicitly specifies the
+charsets, ensuring that specific fonts are used if they exist.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
+-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
+-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
+-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Alternatively, the user could supply a base_font_name_list
+that omits the charsets,
+letting Xlib select font charsets required for the locale.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
+-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
+-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
+-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Alternatively, the user could simply supply a single base font name
+that allows Xlib to select from all available fonts
+that meet certain minimum <acronym>XLFD</acronym> property requirements.
+For example:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+"-*-*-*-R-Normal--*-180-100-100-*-*"
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If 
+<function>XCreateFontSet</function>
+is unable to create the font set, 
+either because there is insufficient memory or because the current locale
+is not supported,
+<function>XCreateFontSet</function>
+returns NULL, missing_charset_list_return is set to NULL,
+and missing_charset_count_return
+is set to zero.
+If fonts exist for all of the charsets required by the current locale,
+<function>XCreateFontSet</function>
+returns a valid
+<type>XFontSet</type>,
+missing_charset_list_return is set to NULL,
+and missing_charset_count_return is set to zero.
+</para>
+<para>
+<!-- .LP -->
+If no font exists for one or more of the required charsets,
+<function>XCreateFontSet</function>
+sets missing_charset_list_return to a
+list of one or more null-terminated charset names for which no font exists
+and sets missing_charset_count_return to the number of missing fonts.
+The charsets are from the list of the required charsets for
+the encoding of the locale and do not include any charsets to which Xlib
+may be able to remap a required charset.
+</para>
+<para>
+<!-- .LP -->
+If no font exists for any of the required charsets
+or if the locale definition in Xlib requires that a font exist
+for a particular charset and a font is not found for that charset, 
+<function>XCreateFontSet</function>
+returns NULL.
+Otherwise, 
+<function>XCreateFontSet</function>
+returns a valid 
+<type>XFontSet</type>
+to font_set.
+</para>
+<para>
+<!-- .LP -->
+When an Xmb/wc drawing or measuring function is called with an
+<type>XFontSet</type>
+that has missing charsets, some characters in the locale will not be
+drawable.
+If def_string_return is non-NULL,
+<function>XCreateFontSet</function>
+returns a pointer to a string that represents the glyphs
+that are drawn with this 
+<type>XFontSet</type>
+when the charsets of the available fonts do not include all font glyphs
+required to draw a codepoint.
+The string does not necessarily consist of valid characters 
+in the current locale and is not necessarily drawn with
+the fonts loaded for the font set,
+but the client can draw and measure the default glyphs
+by including this string in a string being drawn or measured with the 
+<type>XFontSet</type>.
+</para>
+<para>
+<!-- .LP -->
+If the string returned to def_string_return is the empty string (""),
+no glyphs are drawn, and the escapement is zero.
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It will be freed by a call to 
+<function>XFreeFontSet</function>
+with the associated 
+<type>XFontSet</type>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+The client is responsible for constructing an error message from the
+missing charset and default string information and may choose to continue
+operation in the case that some fonts did not exist.
+</para>
+<para>
+<!-- .LP -->
+The returned 
+<type>XFontSet</type>
+and missing charset list should be freed with 
+<function>XFreeFontSet</function>
+and
+<function>XFreeStringList</function>,
+respectively.
+The client-supplied base_font_name_list may be freed 
+by the client after calling 
+<function>XCreateFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a list of 
+<structname>XFontStruct</structname>
+structures and full font names given an 
+<type>XFontSet</type>,
+use
+<function>XFontsOfFontSet</function>.
+<indexterm significance="preferred"><primary>XFontsOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfontsoffontset'>
+<funcprototype>
+  <funcdef>int <function>XFontsOfFontSet</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>XFontStruct<parameter> ***font_struct_list_return</parameter></paramdef>
+  <paramdef>char<parameter> ***font_name_list_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_struct_list_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the list of font structs.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_name_list_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the list of font names.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFontsOfFontSet</function>
+function returns a list of one or more 
+<structname>XFontStruct</structname>s
+and font names for the fonts used by the Xmb and Xwc layers
+for the given font set.
+A list of pointers to the
+<structname>XFontStruct</structname>
+structures is returned to font_struct_list_return.
+A list of pointers to null-terminated, fully specified font name strings
+in the locale of the font set is returned to font_name_list_return.
+The font_name_list order corresponds to the font_struct_list order.
+The number of
+<structname>XFontStruct</structname>
+structures and font names is returned as the value of the function.
+</para>
+<para>
+<!-- .LP -->
+Because it is not guaranteed that a given character will be imaged using a
+single font glyph,
+there is no provision for mapping a character or default string 
+to the font properties, font ID, or direction hint for the font 
+for the character.
+The client may access the 
+<structname>XFontStruct</structname>
+list to obtain these values for all the fonts currently in use.
+</para>
+<para>
+<!-- .LP -->
+Xlib does not guarantee that fonts are loaded from the server
+at the creation of an 
+<type>XFontSet</type>.
+Xlib may choose to cache font data, loading it only as needed to draw text 
+or compute text dimensions.
+Therefore, existence of the per_char metrics in the 
+<structname>XFontStruct</structname>
+structures in the
+<structname>XFontStructSet</structname>
+is undefined.
+Also, note that all properties in the 
+<structname>XFontStruct</structname>
+structures are in the STRING encoding.
+</para>
+<para>
+<!-- .LP -->
+The 
+<structname>XFontStruct</structname>
+and font name lists are owned by Xlib 
+and should not be modified or freed by the client.
+They will be freed by a call to
+<function>XFreeFontSet</function>
+with the associated
+<type>XFontSet</type>.
+Until freed, their contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the base font name list and the selected font name list given an
+<type>XFontSet</type>,
+use
+<function>XBaseFontNameListOfFontSet</function>.
+<indexterm significance="preferred"><primary>XBaseFontNameListOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xbasefontnamelistoffontset'>
+<funcprototype>
+  <funcdef>char *<function>XBaseFontNameListOfFontSet</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XBaseFontNameListOfFontSet</function>
+function returns the original base font name list supplied
+by the client when the 
+<type>XFontSet</type>
+was created.
+A null-terminated string containing a list of
+comma-separated font names is returned
+as the value of the function.
+White space may appear immediately on either side of separating commas.
+</para>
+<para>
+<!-- .LP -->
+If 
+<function>XCreateFontSet</function>
+obtained an <acronym>XLFD</acronym> name from the font properties for the font specified
+by a non-<acronym>XLFD</acronym> base name, the
+<function>XBaseFontNameListOfFontSet</function>
+function will return the <acronym>XLFD</acronym> name instead of the non-<acronym>XLFD</acronym> base name.
+</para>
+<para>
+<!-- .LP -->
+The base font name list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to 
+<function>XFreeFontSet</function>
+with the associated 
+<type>XFontSet</type>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the locale name given an 
+<type>XFontSet</type>,
+use
+<function>XLocaleOfFontSet</function>.
+<indexterm significance="preferred"><primary>XLocaleOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlocaleoffontset'>
+<funcprototype>
+  <funcdef>char *<function>XLocaleOfFontSet</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLocaleOfFontSet</function>
+function
+returns the name of the locale bound to the specified
+<type>XFontSet</type>,
+as a null-terminated string.
+</para>
+<para>
+<!-- .LP -->
+The returned locale name string is owned by Xlib
+and should not be modified or freed by the client.
+It may be freed by a call to
+<function>XFreeFontSet</function>
+with the associated 
+<type>XFontSet</type>.
+Until freed, it will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The 
+<function>XFreeFontSet</function>
+function is a convenience function for freeing an output context.
+<function>XFreeFontSet</function>
+also frees its associated 
+<type>XOM</type>
+if the output context was created by
+<function>XCreateFontSet</function>.
+<indexterm significance="preferred"><primary>XFreeFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreefontset'>
+<funcprototype>
+  <funcdef>void <function>XFreeFontSet</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeFontSet</function>
+function frees the specified font set.
+The associated base font name list, font name list, 
+<structname>XFontStruct</structname>
+list, and 
+<structname>XFontSetExtents</structname>,
+if any, are freed.
+</para>
+</sect2>
+<sect2 id="Obtaining_Font_Set_Metrics">
+<title>Obtaining Font Set Metrics</title>
+<!-- .XS -->
+<!-- (SN Obtaining Font Set Metrics -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Metrics for the internationalized text drawing functions 
+are defined in terms of a primary draw direction, 
+which is the default direction in which the character origin advances
+for each succeeding character in the string.
+The Xlib interface is currently defined to support only a left-to-right
+primary draw direction.
+The drawing origin is the position passed to the drawing function 
+when the text is drawn.
+The baseline is a line drawn through the drawing origin parallel
+to the primary draw direction.
+Character ink is the pixels painted in the foreground color 
+and does not include interline or intercharacter spacing 
+or image text background pixels.
+</para>
+<para>
+<!-- .LP -->
+The drawing functions are allowed to implement implicit text
+directionality control, reversing the order in which characters are
+rendered along the primary draw direction in response to locale-specific
+lexical analysis of the string.
+</para>
+<para>
+<!-- .LP -->
+Regardless of the character rendering order,
+the origins of all characters are on the primary draw direction side
+of the drawing origin.
+The screen location of a particular character image may be determined with
+<function>XmbTextPerCharExtents</function>
+or
+<function>XwcTextPerCharExtents</function>.
+</para>
+<para>
+<!-- .LP -->
+The drawing functions are allowed to implement context-dependent
+rendering, where the glyphs drawn for a string are not simply a
+concatenation of the glyphs that represent each individual character.
+A string of two characters drawn with 
+<function>XmbDrawString</function>
+may render differently than if the two characters 
+were drawn with separate calls to
+<function>XmbDrawString</function>.
+If the client appends or inserts a character 
+in a previously drawn string,
+the client may need to redraw some adjacent characters 
+to obtain proper rendering.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To find out about direction-dependent rendering, use
+<function>XDirectionalDependentDrawing</function>.
+<indexterm significance="preferred"><primary>XDirectionalDependentDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdirectionaldependentdrawing'>
+<funcprototype>
+  <funcdef>Bool <function>XDirectionalDependentDrawing</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDirectionalDependentDrawing</function>
+function returns
+<symbol>True</symbol>
+if the drawing functions implement implicit text directionality;
+otherwise, it returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To find out about context-dependent rendering, use
+<function>XContextualDrawing</function>.
+<indexterm significance="preferred"><primary>XContextualDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcontextualdrawing'>
+<funcprototype>
+  <funcdef>Bool <function>XContextualDrawing</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XContextualDrawing</function>
+function returns
+<symbol>True</symbol>
+if text drawn with the font set might include context-dependent drawing;
+otherwise, it returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To find out about context-dependent or direction-dependent rendering, use
+<function>XContextDependentDrawing</function>.
+<indexterm significance="preferred"><primary>XContextDependentDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcontextdependentdrawing'>
+<funcprototype>
+  <funcdef>Bool <function>XContextDependentDrawing</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XContextDependentDrawing</function>
+function returns
+<symbol>True</symbol>
+if the drawing functions implement implicit text directionality or
+if text drawn with the font_set might include context-dependent drawing;
+otherwise, it returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The drawing functions do not interpret newline, tab, or other control
+characters.
+The behavior when nonprinting characters other than space are drawn
+is implementation-dependent.
+It is the client's responsibility to interpret control characters
+in a text stream.
+</para>
+<para>
+<!-- .LP -->
+The maximum character extents for the fonts that are used by the text
+drawing layers can be accessed by the 
+<structname>XFontSetExtents</structname>
+structure:
+<indexterm significance="preferred"><primary>XFontSetExtents</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     XRectangle max_ink_extent;     /* over all drawable characters */
+     XRectangle max_logical_extent; /* over all drawable characters */
+} XFontSetExtents;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The 
+<structname>XRectangle</structname>
+structures used to return font set metrics are the usual Xlib screen-oriented 
+rectangles
+with x, y giving the upper left corner, and width and height always positive.
+</para>
+<para>
+<!-- .LP -->
+The max_ink_extent member gives the maximum extent, over all drawable characters, of
+the rectangles that bound the character glyph image drawn in the
+foreground color, relative to a constant origin.
+See 
+<function>XmbTextExtents</function>
+and
+<function>XwcTextExtents</function>
+for detailed semantics.
+</para>
+<para>
+<!-- .LP -->
+The max_logical_extent member gives the maximum extent,
+over all drawable characters, of the rectangles 
+that specify minimum spacing to other graphical features,
+relative to a constant origin.
+Other graphical features drawn by the client, for example,
+a border surrounding the text, should not intersect this rectangle.
+The max_logical_extent member should be used to compute minimum 
+interline spacing and the minimum area that must be allowed
+in a text field to draw a given number of arbitrary characters.
+</para>
+<para>
+<!-- .LP -->
+Due to context-dependent rendering,
+appending a given character to a string may change 
+the string's extent by an amount other than that character's
+individual extent.
+</para>
+<para>
+<!-- .LP -->
+The rectangles for a given character in a string can be obtained from
+<function>XmbTextPerCharExtents</function>
+or
+<function>XwcTextPerCharExtents</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the maximum extents structure given an
+<type>XFontSet</type>,
+use
+<function>XExtentsOfFontSet</function>.
+<indexterm significance="preferred"><primary>XExtentsOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xextentsoffontset'>
+<funcprototype>
+  <funcdef>XFontSetExtents *<function>XExtentsOfFontSet</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XExtentsOfFontSet</function>
+function returns an
+<structname>XFontSetExtents</structname>
+structure for the fonts used by the Xmb and Xwc layers
+for the given font set.
+</para>
+<para>
+<!-- .LP -->
+The 
+<structname>XFontSetExtents</structname>
+structure is owned by Xlib and should not be modified
+or freed by the client.
+It will be freed by a call to 
+<function>XFreeFontSet</function>
+with the associated 
+<type>XFontSet</type>.
+Until freed, its contents will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the escapement in pixels of the specified text as a value,
+use
+<function>XmbTextEscapement</function>
+or 
+<function>XwcTextEscapement</function>.
+<indexterm significance="preferred"><primary>XmbTextEscapement</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextEscapement</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbtextescapement'>
+<funcprototype>
+  <funcdef>int <function>XmbTextEscapement</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwctextescapement'>
+<funcprototype>
+  <funcdef>int <function>XwcTextEscapement</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_wchars</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_bytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes in the string argument.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_wchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextEscapement</function>
+and
+<function>XwcTextEscapement</function>
+functions return the escapement in pixels of the specified string as a value,
+using the fonts loaded for the specified font set.
+The escapement is the distance in pixels in the primary draw
+direction from the drawing origin to the origin of the next character to
+be drawn, assuming that the rendering of the next character is not
+dependent on the supplied string.
+</para>
+<para>
+<!-- .LP -->
+Regardless of the character rendering order,
+the escapement is always positive.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the overall_ink_return and overall_logical_return arguments,
+the overall bounding box of the string's image, and a logical bounding box,
+use
+<function>XmbTextExtents</function>
+ or
+<function>XwcTextExtents</function>.
+<indexterm significance="preferred"><primary>XmbTextExtents</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbtextextents'>
+<funcprototype>
+  <funcdef>int <function>XmbTextExtents</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_bytes</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype id='xwctextextents'>
+  <funcdef>int <function>XwcTextExtents</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_wchars</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_bytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes in the string argument.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_wchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+<!-- .ds Ov dimensions -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>overall_ink_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the overall ink dimensions.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>overall_logical_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the overall logical dimensions.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextExtents</function>
+and
+<function>XwcTextExtents</function>
+functions set the components of the specified overall_ink_return and
+overall_logical_return
+arguments to the overall bounding box of the string's image
+and a logical bounding box for spacing purposes, respectively.
+They return the value returned by 
+<function>XmbTextEscapement</function>
+or
+<function>XwcTextEscapement</function>.
+These metrics are relative to the drawing origin of the string,
+using the fonts loaded for the specified font set.
+</para>
+<para>
+<!-- .LP -->
+If the overall_ink_return argument is non-NULL,
+it is set to the bounding box of the string's character ink.
+The overall_ink_return for a nondescending, horizontally drawn
+Latin character is conventionally entirely above the baseline;
+that is, overall_ink_return.height &lt;= -overall_ink_return.y.
+The overall_ink_return for a nonkerned character
+is entirely at, and to the right of, the origin;
+that is, overall_ink_return.x &gt;= 0.
+A character consisting of a single pixel at the origin would set
+overall_ink_return fields y = 0, x = 0, width = 1, and height = 1.
+</para>
+<para>
+<!-- .LP -->
+If the overall_logical_return argument is non-NULL,
+it is set to the bounding box that provides minimum spacing
+to other graphical features for the string.
+Other graphical features, for example, a border surrounding the text,
+should not intersect this rectangle.
+</para>
+<para>
+<!-- .LP -->
+When the 
+<type>XFontSet</type>
+has missing charsets,
+metrics for each unavailable character are taken 
+from the default string returned by 
+<function>XCreateFontSet</function>
+so that the metrics represent the text as it will actually be drawn.
+The behavior for an invalid codepoint is undefined.
+</para>
+<para>
+<!-- .LP -->
+To determine the effective drawing origin for a character in a drawn string,
+the client should call 
+<function>XmbTextPerCharExtents</function>
+on the entire string, then on the character,
+and subtract the x values of the returned 
+rectangles for the character.
+This is useful to redraw portions of a line of text
+or to justify words, but for context-dependent rendering,
+the client should not assume that it can redraw the character by itself
+and get the same rendering.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain per-character information for a text string,
+use
+<function>XmbTextPerCharExtents</function>
+or
+<function>XwcTextPerCharExtents</function>.
+<indexterm significance="preferred"><primary>XmbTextPerCharExtents</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextPerCharExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbtextpercharextents'>
+<funcprototype>
+  <funcdef>Status <function>XmbTextPerCharExtents</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_bytes</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>
+  <paramdef>int<parameter> array_size</parameter></paramdef>
+  <paramdef>int<parameter> *num_chars_return</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwctextpercharextents'>
+<funcprototype>
+  <funcdef>Status <function>XwcTextPerCharExtents</function></funcdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_wchars</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>
+  <paramdef>int<parameter> array_size</parameter></paramdef>
+  <paramdef>int<parameter> *num_chars_return</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_bytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes in the string argument.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_wchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ink_array_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the ink dimensions for each character.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>logical_array_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the logical dimensions for each character.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>array_size</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size of ink_array_return and logical_array_return.
+The caller must pass in arrays of this size.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_chars_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of characters in the string argument.
+<!-- .ds Ov extents of the entire string -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>overall_ink_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the overall ink dimensions.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>overall_logical_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the overall logical dimensions.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextPerCharExtents</function>
+and
+<function>XwcTextPerCharExtents</function>
+functions return the text dimensions of each character of the specified text,
+using the fonts loaded for the specified font set.
+Each successive element of ink_array_return and logical_array_return
+is set to the successive character's drawn metrics,
+relative to the drawing origin of the string and one 
+rectangle
+for each character in the supplied text string.
+The number of elements of ink_array_return and logical_array_return
+that have been set is returned to num_chars_return.
+</para>
+<para>
+<!-- .LP -->
+Each element of ink_array_return is set to the bounding box 
+of the corresponding character's drawn foreground color.
+Each element of logical_array_return is set to the bounding box 
+that provides minimum spacing to other graphical features
+for the corresponding character.
+Other graphical features should not intersect any of the
+logical_array_return rectangles.
+</para>
+<para>
+<!-- .LP -->
+Note that an 
+<structname>XRectangle</structname>
+represents the effective drawing dimensions of the character,
+regardless of the number of font glyphs that are used to draw
+the character or the direction in which the character is drawn.
+If multiple characters map to a single character glyph,
+the dimensions of all the 
+<structname>XRectangle</structname>s
+of those characters are the same.
+</para>
+<para>
+<!-- .LP -->
+When the 
+<type>XFontSet</type>
+has missing charsets, metrics for each unavailable
+character are taken from the default string returned by 
+<function>XCreateFontSet</function>
+so that the metrics represent the text as it will actually be drawn.
+The behavior for an invalid codepoint is undefined.
+</para>
+<para>
+<!-- .LP -->
+If the array_size is too small for the number of characters in the
+supplied text, the functions return zero
+and num_chars_return is set to the number of rectangles required.
+Otherwise, the functions return a nonzero value.
+</para>
+<para>
+<!-- .LP -->
+If the overall_ink_return or overall_logical_return argument is non-NULL,
+<function>XmbTextPerCharExtents</function>
+and 
+<function>XwcTextPerCharExtents</function>
+return the maximum extent of the string's metrics to overall_ink_return
+or overall_logical_return, as returned by 
+<function>XmbTextExtents</function>
+or 
+<function>XwcTextExtents</function>.
+</para>
+</sect2>
+<sect2 id="Drawing_Text_Using_Font_Sets">
+<title>Drawing Text Using Font Sets</title>
+<!-- .XS -->
+<!-- (SN Drawing Text Using Font Sets -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The functions defined in this section
+draw text at a specified location in a drawable.
+They are similar to the functions
+<function>XDrawText</function>,
+<function>XDrawString</function>,
+and
+<function>XDrawImageString</function>
+except that they work with font sets instead of single fonts
+and interpret the text based on the locale of the font set
+instead of treating the bytes of the string as direct font indexes.
+See section 8.6 for details of the use of Graphics Contexts (GCs)
+and possible protocol errors.
+If a 
+<errorname>BadFont</errorname>
+error is generated,
+characters prior to the offending character may have been drawn.
+</para>
+<para>
+<!-- .LP -->
+The text is drawn using the fonts loaded for the specified font set;
+the font in the GC is ignored and may be modified by the functions.
+No validation that all fonts conform to some width rule is performed.
+</para>
+<para>
+<!-- .LP -->
+The text functions
+<function>XmbDrawText</function>
+and
+<function>XwcDrawText</function>
+use the following structures:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XmbTextItem</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+     char     *chars;    /* pointer to string */
+     int      nchars;    /* number of bytes */
+     int      delta;     /* pixel delta between strings */
+     XFontSet font_set;  /* fonts, None means don't change */
+} XmbTextItem;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XwcTextItem</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+     wchar_t *chars;     /* pointer to wide char string */
+     int nchars;     /* number of wide characters */
+     int delta;     /* pixel delta between strings */
+     XFontSet font_set;     /* fonts, None means don't change */
+} XwcTextItem;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw text using multiple font sets in a given drawable, use
+<function>XmbDrawText</function>
+or
+<function>XwcDrawText</function>.
+<indexterm significance="preferred"><primary>XmbDrawText</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbdrawtext'>
+<funcprototype>
+  <funcdef>void <function>XmbDrawText</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>XmbTextItem<parameter> *items</parameter></paramdef>
+  <paramdef>int<parameter> nitems</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwcdrawtext'>
+<funcprototype>
+  <funcdef>void <function>XwcDrawText</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>XwcTextItem<parameter> *items</parameter></paramdef>
+  <paramdef>int<parameter> nitems</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>items</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of text items.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nitems</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of text items in the array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbDrawText</function>
+and 
+<function>XwcDrawText</function>
+functions allow complex spacing and font set shifts between text strings.
+Each text item is processed in turn, with the origin of a text
+element advanced in the primary draw direction by the escapement of the
+previous text item.
+A text item delta specifies an additional escapement of the text item
+drawing origin in the primary draw direction.
+A font_set member other than 
+<symbol>None</symbol>
+in an item causes the font set to be used for this and subsequent text items
+in the text_items list.
+Leading text items with a font_set member set to
+<symbol>None</symbol>
+will not be drawn.
+</para>
+<para>
+<!-- .LP -->
+<function>XmbDrawText</function>
+and
+<function>XwcDrawText</function>
+do not perform any context-dependent rendering between text segments.
+Clients may compute the drawing metrics by passing each text segment to
+<function>XmbTextExtents</function>
+and
+<function>XwcTextExtents</function>
+or 
+<function>XmbTextPerCharExtents</function>
+and
+<function>XwcTextPerCharExtents</function>.
+When the 
+<type>XFontSet</type>
+has missing charsets, each unavailable character is drawn 
+with the default string returned by 
+<function>XCreateFontSet</function>.
+The behavior for an invalid codepoint is undefined.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To draw text using a single font set in a given drawable, use
+<function>XmbDrawString</function>
+or
+<function>XwcDrawString</function>.
+<indexterm significance="preferred"><primary>XmbDrawString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbdrawstring'>
+<funcprototype>
+  <funcdef>void <function>XmbDrawString</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwcdrawstring'>
+<funcprototype>
+  <funcdef>void <function>XwcDrawString</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_wchars</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_bytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes in the string argument.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_wchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbDrawString</function>
+and
+<function>XwcDrawString</function>
+functions draw the specified text with the foreground pixel.
+When the 
+<type>XFontSet</type>
+has missing charsets, each unavailable character is drawn 
+with the default string returned by 
+<function>XCreateFontSet</function>.
+The behavior for an invalid codepoint is undefined.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To draw image text using a single font set in a given drawable, use
+<function>XmbDrawImageString</function>
+or
+<function>XwcDrawImageString</function>.
+<indexterm significance="preferred"><primary>XmbDrawImageString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawImageString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbdrawimagestring'>
+<funcprototype>
+  <funcdef>void <function>XmbDrawImageString</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwcdrawimagestring'>
+<funcprototype>
+  <funcdef>void <function>XwcDrawImageString</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>XFontSet<parameter> font_set</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>wchar_t<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_wchars</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>font_set</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the font set.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+<!-- .ds Xy -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_bytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes in the string argument.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_wchars</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of characters in the string argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbDrawImageString</function>
+and
+<function>XwcDrawImageString</function>
+functions fill a destination rectangle with the background pixel defined
+in the GC and then paint the text with the foreground pixel.
+The filled rectangle is the rectangle returned to overall_logical_return by
+<function>XmbTextExtents</function>
+or 
+<function>XwcTextExtents</function>
+for the same text and 
+<type>XFontSet</type>.
+</para>
+<para>
+<!-- .LP -->
+When the 
+<type>XFontSet</type>
+has missing charsets, each unavailable character is drawn 
+with the default string returned by 
+<function>XCreateFontSet</function>.
+The behavior for an invalid codepoint is undefined.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Input_Methods">
+<title>Input Methods</title>
+<!-- .XS -->
+<!-- (SN Input Methods -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section provides discussions of the following X Input Method
+(<acronym>XIM</acronym>) topics:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Input method overview
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Input method management
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Input method functions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Input method values
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Input context functions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Input context values
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Input method callback semantics
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Event filtering
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Getting keyboard input
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Input method conventions
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Input_Method_Overview">
+<title>Input Method Overview</title>
+<!-- .XS -->
+<!-- (SN Input Method Overview -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section provides definitions for terms and concepts used
+for internationalized text input and a brief overview of the
+intended use of the mechanisms provided by Xlib.
+</para>
+<para>
+<!-- .LP -->
+A large number of languages in the world use alphabets
+consisting of a small set of symbols (letters) to form words.
+To enter text into a computer in an alphabetic language,
+a user usually has a keyboard on which there exist key symbols corresponding
+to the alphabet.
+Sometimes, a few characters of an alphabetic language are missing
+on the keyboard.
+Many computer users who speak a Latin-alphabet-based language 
+only have an English-based keyboard.
+They need to hit a combination of keystrokes
+to enter a character that does not exist directly on the keyboard.
+A number of algorithms have been developed for entering such characters.
+These are known as European input methods, compose input methods, 
+or dead-key input methods.
+</para>
+<para>
+<!-- .LP -->
+Japanese is an example of a language with a phonetic symbol set,
+where each symbol represents a specific sound.
+There are two phonetic symbol sets in Japanese:  Katakana and Hiragana.
+In general,
+Katakana is used for words that are of foreign origin,
+and Hiragana is used for writing native Japanese words.
+Collectively, the two systems are called Kana.
+Each set consists of 48 characters.
+</para>
+<para>
+<!-- .LP -->
+Korean also has a phonetic symbol set, called Hangul.
+Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)
+represents a specific sound.
+A syllable is composed of two or three parts: 
+the initial consonants, the vowels, and the optional last consonants.
+With Hangul,
+syllables can be treated as the basic units on which text processing is done.
+For example,
+a delete operation may work on a phonetic symbol or a syllable.
+Korean code sets include several thousands of these syllables.
+A user types the phonetic symbols that make up the syllables of the words
+to be entered.
+The display may change as each phonetic symbol is entered.
+For example,
+when the second phonetic symbol of a syllable is entered,
+the first phonetic symbol may change its shape and size.
+Likewise, when the third phonetic symbol is entered,
+the first two phonetic symbols may change their shape and size.
+</para>
+<para>
+<!-- .LP -->
+Not all languages rely solely on alphabetic or phonetic systems.
+Some languages, including Japanese and Korean, employ an
+ideographic writing system.
+In an ideographic system, rather than taking a small set of
+symbols and combining them in different ways to create words,
+each word consists of one unique symbol (or, occasionally, several symbols).
+The number of symbols can be very large: 
+approximately 50,000 have been identified in Hanzi,
+the Chinese ideographic system.
+</para>
+<para>
+<!-- .LP -->
+Two major aspects of ideographic systems impact their use with computers.
+First, the standard computer character sets in Japan, China, and Korea
+include roughly 8,000 characters,
+while sets in Taiwan have between 15,000 and 30,000 characters.
+This makes it necessary to use more than one byte to represent a character.
+Second, it obviously is impractical to have a keyboard that includes
+all of a given language's ideographic symbols.
+Therefore, a mechanism is required for entering characters
+so that a keyboard with a reasonable number of keys can be used.
+Those input methods are usually based on phonetics,
+but there also exist methods based on the graphical properties of
+characters.
+</para>
+<para>
+<!-- .LP -->
+In Japan, both Kana and the ideographic system Kanji are used.
+In Korea, Hangul and sometimes the ideographic system Hanja are used.
+Now consider entering ideographs in Japan, Korea, China, and Taiwan.
+</para>
+<para>
+<!-- .LP -->
+In Japan, either Kana or English characters are typed and then a region
+is selected (sometimes automatically) for conversion to Kanji.
+Several Kanji characters may have the same phonetic representation.
+If that is the case with the string entered,
+a menu of characters is presented and
+the user must choose the appropriate one.
+If no choice is necessary or a preference has been established,
+the input method does the substitution directly.
+When Latin characters are converted to Kana or Kanji,
+it is called a romaji conversion.
+</para>
+<para>
+<!-- .LP -->
+In Korea, it is usually acceptable to keep Korean text in Hangul form,
+but some people may choose to write Hanja-originated words in Hanja
+rather than in Hangul.
+To change Hangul to Hanja,
+the user selects a region for conversion
+and then follows the same basic method as that described for Japanese.
+</para>
+<para>
+<!-- .LP -->
+Probably because there are well-accepted phonetic writing systems
+for Japanese and Korean,
+computer input methods in these countries for entering ideographs 
+are fairly standard.
+Keyboard keys have both English characters and phonetic symbols
+engraved on them, and the user can switch between the two sets.
+</para>
+<para>
+<!-- .LP -->
+The situation is different for Chinese.
+While there is a phonetic system called Pinyin promoted by authorities,
+there is no consensus for entering Chinese text.
+Some vendors use a phonetic decomposition (Pinyin or another),
+others use ideographic decomposition of Chinese words,
+with various implementations and keyboard layouts. 
+There are about 16 known methods, none of which is a clear standard. 
+</para>
+<para>
+<!-- .LP -->
+Also, there are actually two ideographic sets used:
+Traditional Chinese (the original written Chinese)
+and Simplified Chinese.
+Several years ago,
+the People's Republic of China launched a campaign to simplify
+some ideographic characters and eliminate redundancies altogether.
+Under the plan, 
+characters would be streamlined every five years.
+Characters have been revised several times now, 
+resulting in the smaller, simpler set that makes up Simplified Chinese.
+</para>
+<sect3 id="Input_Method_Architecture">
+<title>Input Method Architecture</title>
+<!-- .XS -->
+<!-- (SN Input Method Architecture -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+As shown in the previous section,
+there are many different input methods in use today,
+each varying with language, culture, and history. 
+A common feature of many input methods is that the user may type
+multiple keystrokes to compose a single character (or set
+of characters).
+The process of composing characters from keystrokes is called
+<emphasis remap='I'>preediting</emphasis>.
+It may require complex algorithms and large dictionaries 
+involving substantial computer resources.
+</para>
+<para>
+<!-- .LP -->
+Input methods may require one or more areas in which to show the
+feedback of the actual keystrokes, to propose disambiguation to the
+user, to list dictionaries, and so on.
+The input method areas of concern are as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The <emphasis remap='I'>status</emphasis> area is a logical extension of the
+LEDs that exist on the physical keyboard.
+It is a window that is intended to present the internal state
+of the input method that is critical to the user.
+The status area may consist of text data and bitmaps or some combination.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The <emphasis remap='I'>preedit</emphasis> area displays the
+intermediate text for those languages that are composing prior to 
+the client handling the data.   
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The <emphasis remap='I'>auxiliary</emphasis> area is used for pop-up menus and customizing
+dialogs that may be required for an input method.
+There may be multiple auxiliary areas for an input method.
+Auxiliary areas are managed by the input method independent of the client.
+Auxiliary areas are assumed to be separate dialogs,
+which are maintained by the input method.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+There are various user interaction styles used for preediting.
+The ones supported by Xlib are as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+For <emphasis remap='I'>on-the-spot</emphasis> input methods,
+preediting data will be displayed directly in the application window.
+Application data is moved to allow preedit data to appear
+at the point of insertion.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<emphasis remap='I'>Over-the-spot</emphasis> preediting means that the data is displayed in
+a preedit window that is placed over the point of insertion.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<emphasis remap='I'>Off-the-spot</emphasis> preediting means that the preedit window is
+inside the application window but not at the point of insertion.
+Often, this type of window is placed at the bottom of the application window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<emphasis remap='I'>Root-window</emphasis> preediting refers to input methods that use a preedit
+window that is the child of 
+<function>RootWindow</function>.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+It would require a lot of computing resources if portable applications
+had to include input methods for all the languages in the world.
+To avoid this,
+a goal of the Xlib design is to allow an application 
+to communicate with an input method placed in a separate process.
+Such a process is called an <emphasis remap='I'>input server</emphasis>.
+The server to which the application should connect is dependent on
+the environment when the application is started up,
+that is, the user language and the actual encoding to be used for it.
+The input method connection is said to be <emphasis remap='I'>locale-dependent</emphasis>.
+It is also user-dependent.
+For a given language, the user can choose, to some extent,
+the user interface style of input method (if choice is possible among
+several).
+</para>
+<para>
+<!-- .LP -->
+Using an input server implies communication overhead,
+but applications can be migrated without relinking.
+Input methods can be implemented either as a
+stub communicating to an input server or as a local library.
+</para>
+<para>
+<!-- .LP -->
+An input method may be based on a <emphasis remap='I'>front-end</emphasis> or a <emphasis remap='I'>back-end</emphasis>
+architecture.
+In a front-end architecture,
+there are two separate connections to the X server:
+keystrokes go directly from the X server to the input method on
+one connection and other events to the regular client connection.
+The input method is then acting as a filter and sends composed strings
+to the client.
+A front-end architecture requires synchronization between the
+two connections to avoid lost key events or locking issues.
+</para>
+<para>
+<!-- .LP -->
+In a back-end architecture,
+a single X server connection is used.
+A dispatching mechanism must decide on this channel to delegate appropriate
+keystrokes to the input method.
+For instance,
+it may retain a Help keystroke for its own purpose.
+In the case where the input method is a separate process (that is, a server),
+there must be a special communication protocol between the back-end client
+and the input server.
+</para>
+<para>
+<!-- .LP -->
+A front-end architecture introduces synchronization issues
+and a filtering mechanism for noncharacter keystrokes
+(Function keys, Help, and so on).
+A back-end architecture sometimes implies more communication overhead
+and more process switching.
+If all three processes (X server, input server, client)
+are running on a single workstation, 
+there are two process switches for each keystroke in a back-end
+architecture,
+but there is only one in a front-end architecture.
+</para>
+<para>
+<!-- .LP -->
+The abstraction used by a client to communicate with an input method
+is an opaque data structure represented by the 
+<type>XIM</type>
+data type.
+This data structure is returned by the 
+<function>XOpenIM</function>
+function, which opens an input method on a given display.
+Subsequent operations on this data structure encapsulate all communication
+between client and input method.
+There is no need for an X client to use any networking library 
+or natural language package to use an input method.
+</para>
+<para>
+<!-- .LP -->
+A single input server may be used for one or more languages,
+supporting one or more encoding schemes.
+But the strings returned from an input method will always be encoded
+in the (single) locale associated with the
+<type>XIM</type>
+object.
+</para>
+</sect3>
+<sect3 id="Input_Contexts">
+<title>Input Contexts</title>
+<!-- .XS -->
+<!-- (SN Input Contexts -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides the ability to manage a multi-threaded state for text input.
+A client may be using multiple windows,
+each window with multiple text entry areas,
+and the user possibly switching among them at any time.
+The abstraction for representing the state of a particular input thread
+is called an <emphasis remap='I'>input context</emphasis>.
+The Xlib representation of an input context is an 
+<type>XIC</type>.
+</para>
+<para>
+<!-- .LP -->
+An input context is the abstraction retaining the state, properties,
+and semantics of communication between a client and an input method.
+An input context is a combination of an input method, a locale
+specifying the encoding of the character strings to be returned,
+a client window, internal state information,
+and various layout or appearance characteristics.
+The input context concept somewhat matches for input the graphics context
+abstraction defined for graphics output.
+</para>
+<para>
+<!-- .LP -->
+One input context belongs to exactly one input method.
+Different input contexts may be associated with the same input method,
+possibly with the same client window.
+An 
+<type>XIC</type>
+is created with the
+<function>XCreateIC</function>
+function, providing an 
+<type>XIM</type>
+argument and affiliating the input context to the input method
+for its lifetime. 
+When an input method is closed with 
+<function>XCloseIM</function>,
+all of its affiliated input contexts should not be used any more
+(and should preferably be destroyed before closing the input method).
+</para>
+<para>
+<!-- .LP -->
+Considering the example of a client window with multiple text entry areas,
+the application programmer could, for example, choose to implement as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+As many input contexts are created as text entry areas, and the client
+will get the input accumulated on each context each time it looks up
+in that context.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A single context is created for a top-level window in the application.
+If such a window contains several text entry areas, 
+each time the user moves to another text entry area,
+the client has to indicate changes in the context.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+A range of choices can be made by application designers to use
+either a single or multiple input contexts,
+according to the needs of their application.
+</para>
+</sect3>
+<sect3 id="Getting_Keyboard_Input">
+<title>Getting Keyboard Input</title>
+<!-- .XS -->
+<!-- (SN Getting Keyboard Input -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To obtain characters from an input method,
+a client must call the function
+<function>XmbLookupString</function>
+or 
+<function>XwcLookupString</function>
+with an input context created from that input method.
+Both a locale and display are bound to an input method when it is opened,
+and an input context inherits this locale and display.
+Any strings returned by 
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>
+will be encoded in that locale. 
+</para>
+</sect3>
+<sect3 id="Focus_Management">
+<title>Focus Management</title>
+<!-- .XS -->
+<!-- (SN Focus Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+For each text entry area in which the
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>
+functions are used,
+there will be an associated input context.
+</para>
+<para>
+<!-- .LP -->
+When the application focus moves to a text entry area,
+the application must set the input context focus to the
+input context associated with that area.
+The input context focus is set by calling 
+<function>XSetICFocus</function>
+with the appropriate input context.
+</para>
+<para>
+<!-- .LP -->
+Also, when the application focus moves out of a text entry area, the
+application should unset the focus for the associated input context
+by calling
+<function>XUnsetICFocus</function>.
+As an optimization, if
+<function>XSetICFocus</function>
+is called successively on two different input contexts,
+setting the focus on the second 
+will automatically unset the focus on the first.
+</para>
+<para>
+<!-- .LP -->
+To set and unset the input context focus correctly,
+it is necessary to track application-level focus changes.
+Such focus changes do not necessarily correspond to X server focus changes.
+</para>
+<para>
+<!-- .LP -->
+If a single input context
+is being used to do input for
+multiple text entry areas, it will also be necessary
+to set the focus window of the
+input context whenever the focus window changes
+(see section 13.5.6.3).
+</para>
+</sect3>
+<sect3 id="Geometry_Management">
+<title>Geometry Management</title>
+<!-- .XS -->
+<!-- (SN Geometry Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In most input method architectures 
+(on-the-spot being the notable exception),
+the input method will perform the display of its own data.
+To provide better visual locality,
+it is often desirable to have the input method areas embedded within a client.
+To do this,
+the client may need to allocate space for an input method.
+Xlib provides support that allows the size and position of input method
+areas to be provided by a client.
+The input method areas that are supported for geometry management
+are the status area and the preedit area.
+</para>
+<para>
+<!-- .LP -->
+The fundamental concept on which geometry management for input method windows
+is based is the proper division of responsibilities between the
+client (or toolkit) and the input method.
+The division of responsibilities is as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The client is responsible for the geometry of the input method window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The input method is responsible for the contents of the input method window.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+An input method is able to suggest a size to the client,
+but it cannot suggest a placement.
+Also the input method can only suggest a size.
+It does not determine the size,
+and it must accept the size it is given.
+</para>
+<para>
+<!-- .LP -->
+Before a client provides geometry management for an input method,
+it must determine if geometry management is needed.
+The input method indicates the need for geometry management 
+by setting 
+<symbol>XIMPreeditArea</symbol>
+or 
+<symbol>XIMStatusArea</symbol>
+in its 
+<structname>XIMStyles</structname>
+value returned by 
+<function>XGetIMValues</function>.
+When a client has decided that it will provide geometry management
+for an input method, 
+it indicates that decision by setting the
+<symbol>XNInputStyle</symbol>
+value in the 
+<type>XIC</type>.
+</para>
+<para>
+<!-- .LP -->
+After a client has established with the input method
+that it will do geometry management,
+the client must negotiate the geometry with the input method.
+The geometry is negotiated by the following steps:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The client suggests an area to the input method by setting the
+<symbol>XNAreaNeeded</symbol>
+value for that area.
+If the client has no constraints for the input method,
+it either will not suggest an area or will set the width and height to zero.
+Otherwise, it will set one of the values.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The client will get the <acronym>XIC</acronym> value 
+<symbol>XNAreaNeeded</symbol>.
+The input method will return its suggested size in this value.
+The input method should pay attention to any constraints suggested
+by the client.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The client sets the <acronym>XIC</acronym> value
+<symbol>XNArea</symbol>
+to inform the input method of the geometry of its window.  
+The client should try to honor the geometry requested by the input method.
+The input method must accept this geometry.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Clients doing geometry management must be aware that setting other
+<acronym>XIC</acronym> values may affect the geometry desired by an input method.
+For example, 
+<symbol>XNFontSet</symbol>
+and
+<symbol>XNLineSpace</symbol>
+may change the geometry desired by the input method.  
+</para>
+<para>
+<!-- .LP -->
+The table of <acronym>XIC</acronym> values (see section 13.5.6)
+indicates the values that can cause the desired geometry to change
+when they are set.
+It is the responsibility of the client to renegotiate the geometry
+of the input method window when it is needed.
+</para>
+<para>
+<!-- .LP -->
+In addition,
+a geometry management callback is provided
+by which an input method can initiate a geometry change.
+</para>
+</sect3>
+<sect3 id="Event_Filtering">
+<title>Event Filtering</title>
+<!-- .XS -->
+<!-- (SN Event Filtering -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A filtering mechanism is provided to allow input methods
+to capture X events transparently to clients.
+It is expected that toolkits (or clients) using
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>
+will call this filter at some point in the event processing mechanism
+to make sure that events needed by an input method can be filtered
+by that input method.
+</para>
+<para>
+<!-- .LP -->
+If there were no filter,
+a client could receive and discard events that are necessary
+for the proper functioning of an input method.
+The following provides a few examples of such events:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Expose events on preedit window in local mode.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Events may be used by an input method to communicate with an input server.
+Such input server protocol-related events have to be intercepted
+if one does not want to disturb client code.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Key events can be sent to a filter before they are bound
+to translations such as those the X Toolkit Intrinsics library provides.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Clients are expected to get the <acronym>XIC</acronym> value 
+<symbol>XNFilterEvents</symbol>
+and augment the event mask for the client window with that event mask.
+This mask may be zero.
+</para>
+</sect3>
+<sect3 id="Callbacks">
+<title>Callbacks</title>
+<!-- .XS -->
+<!-- (SN Callbacks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When an on-the-spot input method is implemented,
+only the client can insert or delete preedit data in place
+and possibly scroll existing text.
+This means that the echo of the keystrokes has to be achieved 
+by the client itself, tightly coupled with the input method logic.
+</para>
+<para>
+<!-- .LP -->
+When the user enters a keystroke,
+the client calls
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>.
+At this point, in the on-the-spot case,
+the echo of the keystroke in the preedit has not yet been done.
+Before returning to the client logic that handles the input characters,
+the look-up function
+must call the echoing logic to insert the new keystroke.
+If the keystrokes entered so far make up a character,
+the keystrokes entered need to be deleted,
+and the composed character will be returned.
+Hence, what happens is that, while being called by client code,
+the input method logic has to call back to the client before it returns.
+The client code, that is, a callback procedure,
+is called from the input method logic.
+</para>
+<para>
+<!-- .LP -->
+There are a number of cases where the input method logic has to
+call back the client.
+Each of those cases is associated with a well-defined callback action.
+It is possible for the client to specify, for each input context,
+what callback is to be called for each action.
+</para>
+<para>
+<!-- .LP -->
+There are also callbacks provided for feedback of status information
+and a callback to initiate a geometry request for an input method.
+</para>
+</sect3>
+<sect3 id="Visible_Position_Feedback_Masks">
+<title>Visible Position Feedback Masks</title>
+<!-- .XS -->
+<!-- (SN Visible Position Feedback Masks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In the on-the-spot input style, there is a problem when
+attempting to draw preedit strings that are longer than the
+available space.  Once the display area is exceeded, it is not
+clear how best to display the preedit string.
+The visible position feedback masks of
+<structname>XIMText</structname>
+help resolve this problem by allowing the input method to specify hints that
+indicate the essential portions of the preedit string.
+For example, such hints can help developers implement
+scrolling of a long preedit string within a short preedit display area.
+</para>
+</sect3>
+<sect3 id="Preedit_String_Management">
+<title>Preedit String Management</title>
+<!-- .XS -->
+<!-- (SN Preedit String Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+As highlighted before, the input method architecture provides
+preediting, which supports a type of preprocessor input composition.
+In this case, composition consists of interpreting a sequence
+of key events and returning a committed string via 
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>.
+This provides the basics for input methods.
+</para>
+<para>
+<!-- .LP -->
+In addition to preediting based on key events, a general framework
+is provided to give a client that desires it more advanced preediting based
+on the text within the client.  This framework is called 
+<emphasis remap='I'>string conversion</emphasis> and is provided using <acronym>XIC</acronym> values. 
+The fundamental concept of string conversion
+is to allow the input method to manipulate the client's
+text independent of any user preediting operation.
+</para>
+<para>
+<!-- .LP -->
+The need for string conversion is based on 
+language needs and input method capabilities.
+The following are some examples of string conversion:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Transliteration conversion provides language-specific conversions
+within the input method.
+In the case of Korean input, users wish to convert a Hangul string 
+into a Hanja string while in preediting, after preediting,
+or in other situations (for example, on a selected string).
+The conversion is triggered when the user
+presses a Hangul-to-Hanja key sequence (which may be input method specific).
+Sometimes the user may want to invoke the conversion after finishing
+preediting or on a user-selected string.  
+Thus, the string to be converted is in an application buffer, not in 
+the preedit area of the input method.  The string conversion services
+allow the client to request this transliteration conversion from the 
+input method.
+There are many other transliteration conversions defined for 
+various languages, for example, Kana-to-Kanji conversion in Japanese.
+<!-- .sp -->
+The key to remember is that transliteration conversions are triggered
+at the request of the user and returned to the client 
+immediately without affecting the preedit area of the input method.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Reconversion of a previously committed string or 
+a selected string is supported by many input methods as a 
+convenience to the user.
+For example, a user tends to mistype the commit key while
+preediting.  In that case, some input methods provide a special
+key sequence to request a ``reconvert'' operation on the 
+committed string, similiar to the undo facility provided by most
+text editors.
+Another example is where the user is proofreading a document 
+that has some misconversions from preediting and wants to correct
+the misconverted text.  Such reconversion is again triggered
+by the user invoking some special action, but reconversions should
+not affect the state of the preedit area.  
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Context-sensitive conversion is required for some languages
+and input methods that need to retrieve text that surrounds the
+current spot location (cursor position) of the client's buffer.
+Such text is needed when the preediting operation depends on 
+some surrounding characters (usually preceding the spot location).
+For example, 
+in Thai language input, certain character sequences may be invalid and
+the input method may want to check whether characters constitute a
+valid word.  Input methods that do such context-dependent
+checking need to retrieve the characters surrounding the current
+cursor position to obtain complete words.
+<!-- .sp -->
+Unlike other conversions, this conversion is not explicitly 
+requested by the user.
+Input methods that provide such context-sensitive conversion 
+continuously need to request context from the client, and any change
+in the context of the spot location may affect such conversions.
+The client's context would be needed if the user moves the cursor
+and starts editing again.
+<!-- .sp -->
+For this reason, an input method supporting this type of conversion
+should take notice of when the client calls
+<function>XmbResetIC</function>
+or
+<function>XwcResetIC</function>,
+which is usually an indication of a context change.  
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Context-sensitive conversions just need a copy of the client's text,
+while other conversions replace the client's text with new text
+to achieve the reconversion or transliteration.   Yet in all
+cases the result of a conversion, either immediately or via preediting,
+is returned by the
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+functions.
+</para>
+<para>
+<!-- .LP -->
+String conversion support is dependent on the availability of the 
+<symbol>XNStringConversion</symbol>
+or 
+<symbol>XNStringConversionCallback</symbol>
+<acronym>XIC</acronym> values.
+Because the input method may not support string conversions,
+clients have to query the availability of string conversion
+operations by checking the supported <acronym>XIC</acronym> values list by calling
+<function>XGetIMValues</function>
+with the
+<symbol>XNQueryICValuesList</symbol>
+IM value.
+</para>
+<para>
+<!-- .LP -->
+The difference between these two values is whether the
+conversion is invoked by the client or the input method.  
+The 
+<symbol>XNStringConversion</symbol>
+<acronym>XIC</acronym> value is used by clients to request 
+a string conversion from the input method.  The client
+is responsible for determining which events are used 
+to trigger the string conversion and whether the string to be
+converted should be copied or deleted.  The type of conversion
+is determined by the input method; the client can only 
+pass the string to be converted.  The client is guaranteed that
+no
+<symbol>XNStringConversionCallback</symbol>
+will be issued when this value is set; thus, the client need
+only set one of these values.
+</para>
+<para>
+<!-- .LP -->
+The
+<symbol>XNStringConversionCallback</symbol>
+<acronym>XIC</acronym> value is used by the client to notify the input method that
+it will accept requests from the input method for string conversion.
+If this value is set,
+it is the input method's responsibility to determine which
+events are used to trigger the string conversion.
+When such events occur, the input method issues a call to the
+client-supplied procedure to retrieve the string to be converted.  The client's
+callback procedure is notified whether to copy or delete the string and 
+is provided with hints as to the amount of text needed.
+The
+<structname>XIMStringConversionCallbackStruct</structname>
+specifies which text should be passed back to the input method.
+</para>
+<para>
+<!-- .LP -->
+Finally, the input method may call the client's 
+<symbol>XNStringConversionCallback</symbol>
+procedure multiple times if the string returned from the callback is
+not sufficient to perform a successful conversion.   The arguments
+to the client's procedure allow the input method to define a
+position (in character units) relative to the client's cursor position 
+and the size of the text needed.  By varying the position and size of
+the desired text in subsequent callbacks, the input method can retrieve 
+additional text.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+</sect2>
+<sect2 id="Input_Method_Management">
+<title>Input Method Management</title>
+<!-- .XS -->
+<!-- (SN Input Method Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The interface to input methods might appear to be simply creating
+an input method
+(<function>XOpenIM</function>)
+and freeing an input method
+(<function>XCloseIM</function>).
+However, input methods may 
+require complex communication with input method servers (IM servers),
+for example:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+If the X server, IM server, and X clients are started asynchronously,
+some clients may attempt to connect to the IM server before it is
+fully operational, and fail.
+Therefore, some mechanism is needed to allow clients to detect when an IM 
+server has started.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+It is up to clients to decide what should be done when an IM server is 
+not available (for example, wait, or use some other IM server).
+</para>
+<para>
+<!-- .LP -->
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Some input methods may allow the underlying IM server to be switched. 
+Such customization may be desired without restarting the entire client.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To support management of input methods in these cases, the following 
+functions are provided:
+</para>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><function>XRegisterIMInstantiateCallback</function></entry>
+      <entry>This function allows clients to register a callback procedure
+      to be called when Xlib detects that an IM server is up and available.</entry>
+    </row>
+    <row>
+      <entry><function>XOpenIM</function></entry>
+      <entry>A client calls this function as a result of the callback procedure
+      being called.</entry>
+    </row>
+    <row>
+      <entry><function>XSetIMValues</function>, <function>XSetICValues</function></entry>
+      <entry>These functions use the <acronym>XIM</acronym> and <acronym>XIC</acronym> values,
+      <symbol>XNDestroyCallback</symbol>,
+      to allow a client 
+      to register a callback procedure to be called when Xlib detects that
+      an IM server that was associated with an opened 
+      input method is no longer available.
+      In addition, this function can be used to switch IM servers for those input 
+      methods that support such functionality.  The IM value for switching IM 
+      servers is implementation-dependent; see the description below about
+      switching IM servers.</entry>
+    </row>
+    <row>
+      <entry><function>XUnregisterIMInstantiateCallback</function></entry>
+      <entry>This function removes a callback procedure registered by the client.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+Input methods that support switching of IM servers may exhibit some
+side-effects:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The input method will ensure that any new IM server supports any of the 
+input styles being used by input contexts already associated with the
+input method.
+However, the list of supported input styles may be different.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Geometry management requests on previously created input contexts
+may be initiated by the new IM server.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+<sect3 id="Hot_Keys">
+<title>Hot Keys</title>
+<!-- .XS -->
+<!-- (SN Hot Keys -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some clients need to guarantee which keys can be used to escape from the
+input method, regardless of the input method state;
+for example, the client-specific Help key or the keys to move the
+input focus.
+The HotKey mechanism allows clients 
+to specify a set of keys for this purpose.  However, the input 
+method might not allow clients to specify hot keys.
+Therefore, clients have to query support of hot keys by checking the
+supported <acronym>XIC</acronym> values list by calling
+<function>XGetIMValues</function>
+with the
+<symbol>XNQueryICValuesList</symbol>
+IM value.
+When the hot keys specified conflict with the key bindings of the 
+input method, hot keys take precedence over the key bindings of the input 
+method.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Preedit_State_Operation">
+<title>Preedit State Operation</title>
+<!-- .XS -->
+<!-- (SN Preedit State Operation -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An input method may have several internal states, depending on its
+implementation and the locale.  However, one state that is
+independent of locale and implementation is whether the input method
+is currently performing a preediting operation.
+Xlib provides the ability for an application to manage the preedit state
+programmatically.  Two methods are provided for
+retrieving the preedit state of an input context.
+One method is to query the state by calling
+<function>XGetICValues</function>
+with the
+<symbol>XNPreeditState</symbol>
+<acronym>XIC</acronym> value.
+Another method is to receive notification whenever
+the preedit state is changed.  To receive such notification,
+an application needs to register a callback by calling
+<function>XSetICValues</function>
+with the
+<symbol>XNPreeditStateNotifyCallback</symbol>
+<acronym>XIC</acronym> value. 
+In order to change the preedit state programmatically, an application 
+needs to call 
+<function>XSetICValues</function>
+with
+<symbol>XNPreeditState</symbol>.
+</para>
+<para>
+<!-- .LP -->
+Availability of the preedit state is input method dependent.  The input 
+method may not provide the ability to set the state or to
+retrieve the state programmatically.  Therefore, clients have to 
+query availability of preedit state operations by checking the 
+supported <acronym>XIC</acronym> values list by calling
+<function>XGetIMValues</function>
+with the
+<symbol>XNQueryICValuesList</symbol>
+IM value.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Input_Method_Functions">
+<title>Input Method Functions</title>
+<!-- .XS -->
+<!-- (SN Input Method Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To open a connection, use
+<function>XOpenIM</function>.
+<indexterm significance="preferred"><primary>XOpenIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xopenim'>
+<funcprototype>
+  <funcdef>XIM <function>XOpenIM</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>
+  <paramdef>char<parameter> *res_name</parameter></paramdef>
+  <paramdef>char<parameter> *res_class</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>res_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the full resource name of the application.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>res_class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the full class name of the application.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XOpenIM</function>
+function opens an input method, 
+matching the current locale and modifiers specification.
+Current locale and modifiers are bound to the input method at opening time.
+The locale associated with an input method cannot be changed dynamically.
+This implies that the strings returned by
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>,
+for any input context affiliated with a given input method,
+will be encoded in the locale current at the time the input method is opened.
+</para>
+<para>
+<!-- .LP -->
+The specific input method to which this call will be routed
+is identified on the basis of the current locale. 
+<function>XOpenIM</function>
+will identify a default input method corresponding to the
+current locale.
+That default can be modified using 
+<function>XSetLocaleModifiers</function>
+for the input method modifier.
+</para>
+<para>
+<!-- .LP -->
+The db argument is the resource database to be used by the input method
+for looking up resources that are private to the input method.
+It is not intended that this database be used to look
+up values that can be set as IC values in an input context.
+If db is NULL,
+no database is passed to the input method.
+</para>
+<para>
+<!-- .LP -->
+The res_name and res_class arguments specify the resource name 
+and class of the application. 
+They are intended to be used as prefixes by the input method
+when looking up resources that are common to all input contexts
+that may be created for this input method.
+The characters used for resource names and classes must be in the
+X Portable Character Set.
+The resources looked up are not fully specified
+if res_name or res_class is NULL.
+</para>
+<para>
+<!-- .LP -->
+The res_name and res_class arguments are not assumed to exist beyond
+the call to
+<function>XOpenIM</function>.
+The specified resource database is assumed to exist for the lifetime
+of the input method.
+</para>
+<para>
+<!-- .LP -->
+<function>XOpenIM</function>
+returns NULL if no input method could be opened.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To close a connection, use
+<function>XCloseIM</function>.
+<indexterm significance="preferred"><primary>XCloseIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcloseim'>
+<funcprototype>
+  <funcdef>Status <function>XCloseIM</function></funcdef>
+  <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>im</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input method.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCloseIM</function>
+function closes the specified input method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set input method attributes, use
+<function>XSetIMValues</function>.
+<indexterm significance="preferred"><primary>XSetIMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetimvalues'>
+<funcprototype>
+  <funcdef>char *<function>XSetIMValues</function></funcdef>
+  <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>im</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input method.
+<!-- .ds Al \ to set <acronym>XIM</acronym> values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable-length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIMValues</function>
+function presents a variable argument list programming interface
+for setting attributes of the specified input method.
+It returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be set.
+Xlib does not attempt to set arguments from the supplied list that
+follow the failed argument;
+all arguments in the list preceding the failed argument have been set
+correctly.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To query an input method, use 
+<function>XGetIMValues</function>.
+<indexterm significance="preferred"><primary>XGetIMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetimvalues'>
+<funcprototype>
+  <funcdef>char *<function>XGetIMValues</function></funcdef>
+  <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>im</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input method.
+<!-- .ds Al \ to get XIM values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetIMValues</function>
+function presents a variable argument list programming interface
+for querying properties or features of the specified input method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+</para>
+<para>
+<!-- .LP -->
+Each <acronym>XIM</acronym> value argument (following a name) must point to
+a location where the <acronym>XIM</acronym> value is to be stored.
+That is, if the <acronym>XIM</acronym> value is of type T,
+the argument must be of type T*.
+If T itself is a pointer type,
+then
+<function>XGetIMValues</function>
+allocates memory to store the actual data,
+and the client is responsible for freeing this data by calling
+<function>XFree</function>
+with the returned pointer.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the display associated with an input method, use
+<function>XDisplayOfIM</function>.
+<indexterm significance="preferred"><primary>XDisplayOfIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplayofim'>
+<funcprototype>
+  <funcdef>Display *<function>XDisplayOfIM</function></funcdef>
+  <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>im</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input method.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayOfIM</function>
+function returns the display associated with the specified input method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the locale associated with an input method, use
+<function>XLocaleOfIM</function>.
+<indexterm significance="preferred"><primary>XLocaleOfIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlocaleofim'>
+<funcprototype>
+  <funcdef>char *<function>XLocaleOfIM</function></funcdef>
+  <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>im</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input method.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLocaleOfIM</function>
+function returns the locale associated with the specified input method.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To register an input method instantiate callback, use
+<function>XRegisterIMInstantiateCallback</function>.
+<indexterm significance="preferred"><primary>XRegisterIMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xregisteriminstantiatecallback'>
+<funcprototype>
+  <funcdef>Bool <function>XRegisterIMInstantiateCallback</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>
+  <paramdef>char<parameter> *res_name</parameter></paramdef>
+  <paramdef>char<parameter> *res_class</parameter></paramdef>
+  <paramdef>XIMProc<parameter> callback</parameter></paramdef>
+  <paramdef>XPointer<parameter> *client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>res_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the full resource name of the application.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>res_class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the full class name of the application.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>callback</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the input method instantiate callback.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRegisterIMInstantiateCallback</function>
+function registers a callback to be invoked whenever a new input method
+becomes available for the specified display that matches the current
+locale and modifiers.
+</para>
+<para>
+<!-- .LP -->
+The function returns 
+<symbol>True</symbol>
+ if it succeeds; otherwise, it returns 
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The generic prototype is as follows:
+<indexterm significance="preferred"><primary>IMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='iminstantiatecallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>IMInstantiateCallback</replaceable></function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Not used for this callback and always passed as NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To unregister an input method instantiation callback, use
+<function>XUnregisterIMInstantiateCallback</function>.
+<indexterm significance="preferred"><primary>XUnregisterIMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunregisteriminstantiatecallback'>
+<funcprototype>
+  <funcdef>Bool <function>XUnregisterIMInstantiateCallback</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XrmDatabase<parameter> db</parameter></paramdef>
+  <paramdef>char<parameter> *res_name</parameter></paramdef>
+  <paramdef>char<parameter> *res_class</parameter></paramdef>
+  <paramdef>XIMProc<parameter> callback</parameter></paramdef>
+  <paramdef>XPointer<parameter> *client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>res_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the full resource name of the application.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>res_class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the full class name of the application.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>callback</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a pointer to the input method instantiate callback.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnregisterIMInstantiateCallback</function>
+function removes an input method instantiation callback previously
+registered.
+The function returns
+<symbol>True</symbol>
+if it succeeds; otherwise, it returns 
+<symbol>False</symbol>.
+</para>
+</sect2>
+<sect2 id="Input_Method_Values">
+<title>Input Method Values</title>
+<!-- .XS -->
+<!-- (SN Input Method Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following table describes how <acronym>XIM</acronym> values are interpreted
+by an input method.
+The first column lists the <acronym>XIM</acronym> values.
+The second column indicates how each of the <acronym>XIM</acronym> values 
+are treated by that input style.
+</para>
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+The following keys apply to this table.
+</para>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry>Key</entry>
+      <entry>Explanation</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>D</entry>
+      <entry>This value may be set using
+      <function>XSetIMValues</function>.
+      If it is not set,
+      a default is provided.</entry>
+    </row>
+    <row>
+      <entry>S</entry>
+      <entry>This value may be set using <function>XSetIMValues</function>.</entry>
+    </row>
+    <row>
+      <entry>G</entry>
+      <entry>This value may be read using <function>XGetIMValues</function>.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<!-- .LP -->
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry><acronym>XIM</acronym> Value</entry>
+      <entry>Key</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry><symbol>XNQueryInputStyle</symbol></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNResourceName</symbol></entry>
+      <entry>D-S-G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNResourceClass</symbol></entry>
+      <entry>D-S-G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNDestroyCallback</symbol></entry>
+      <entry>D-S-G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNQueryIMValuesList</symbol></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNQueryICValuesList</symbol></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNVisiblePosition</symbol></entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry><symbol>XNR6PreeditCallback</symbol></entry>
+      <entry>D-S-G</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+<symbol>XNR6PreeditCallback</symbol>
+is obsolete and its use is not recommended (see section 13.5.4.6).
+</para>
+
+<sect3 id="Query_Input_Style">
+<title>Query Input Style</title>
+<!-- .XS -->
+<!-- (SN Query Input Style -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A client should always query the input method to determine which input 
+styles are supported.
+The client should then find an input style it is capable of supporting.
+</para>
+<para>
+<!-- .LP -->
+If the client cannot find an input style that it can support,
+it should negotiate with the user the continuation of the program
+(exit, choose another input method, and so on).
+</para>
+<para>
+<!-- .LP -->
+The argument value must be a pointer to a location
+where the returned value will be stored.
+The returned value is a pointer to a structure of type
+<structname>XIMStyles</structname>.
+Clients are responsible for freeing the 
+<structname>XIMStyles</structname>
+structure.
+To do so, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XIMStyles</structname>
+structure is defined as follows:
+</para>
+
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMStyle</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStyles</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+typedef unsigned long XIMStyle;
+
+
+#define     XIMPreeditArea             0x0001L
+#define     XIMPreeditCallbacks        0x0002L
+#define     XIMPreeditPosition         0x0004L
+#define     XIMPreeditNothing          0x0008L
+#define     XIMPreeditNone             0x0010L
+
+#define     XIMStatusArea              0x0100L
+#define     XIMStatusCallbacks         0x0200L
+#define     XIMStatusNothing           0x0400L
+#define     XIMStatusNone              0x0800L
+
+typedef struct {
+      unsigned short count_styles;
+      XIMStyle * supported_styles;
+} XIMStyles;
+
+</literallayout>
+
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+An 
+<structname>XIMStyles</structname>
+structure contains the number of input styles supported
+in its count_styles field.
+This is also the size of the supported_styles array.
+</para>
+<para>
+<!-- .LP -->
+The supported styles is a list of bitmask combinations,
+which indicate the combination of styles for each of the areas supported.
+These areas are described later.
+Each element in the list should select one of the bitmask values for
+each area.
+The list describes the complete set of combinations supported.
+Only these combinations are supported by the input method.
+</para>
+<para>
+<!-- .LP -->
+The preedit category defines what type of support is provided
+by the input method for preedit information.
+</para>
+<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>XIMPreeditArea</symbol></entry>
+      <entry>If chosen,
+      the input method would require the client to provide some area values
+      for it to do its preediting.
+      Refer to <acronym>XIC</acronym> values 
+      <symbol>XNArea</symbol>
+      and
+      <symbol>XNAreaNeeded</symbol>.</entry>
+    </row>
+    <row>
+      <entry><symbol>XIMPreeditPosition</symbol></entry>
+      <entry>If chosen,
+      the input method would require the client to provide positional values. 
+      Refer to <acronym>XIC</acronym> values 
+      <symbol>XNSpotLocation</symbol>
+      and
+      <symbol>XNFocusWindow</symbol>.</entry>
+    </row>
+    <row>
+      <entry><symbol>XIMPreeditCallbacks</symbol></entry>
+      <entry>If chosen,
+      the input method would require the client to define the set of preedit callbacks.
+      Refer to <acronym>XIC</acronym> values 
+      <symbol>XNPreeditStartCallback</symbol>,
+      <symbol>XNPreeditDoneCallback</symbol>,
+      <symbol>XNPreeditDrawCallback</symbol>,
+      and
+      <symbol>XNPreeditCaretCallback</symbol>.</entry>
+    </row>
+    <row>
+      <entry><symbol>XIMPreeditNothing</symbol></entry>
+      <entry>If chosen, the input method can function without any preedit values.</entry>
+    </row>
+    <row>
+      <entry><symbol>XIMPreeditNone</symbol></entry>
+      <entry>The input method does not provide any preedit feedback.
+      Any preedit value is ignored.
+      This style is mutually exclusive with the other preedit styles.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+The status category defines what type of support is provided
+by the input method for status information.
+</para>
+<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>XIMStatusArea</symbol></entry>
+      <entry>The input method requires the client to provide
+      some area values for it to do its status feedback.
+      See
+      <symbol>XNArea</symbol>
+      and
+      <symbol>XNAreaNeeded</symbol>.</entry>
+    </row>
+    <row>
+      <entry><symbol>XIMStatusCallbacks</symbol></entry>
+      <entry>The input method requires the client to define the set of status callbacks,
+      <symbol>XNStatusStartCallback</symbol>,
+      <symbol>XNStatusDoneCallback</symbol>,
+      and
+      <symbol>XNStatusDrawCallback</symbol>.</entry>
+    </row>
+    <row>
+      <entry><symbol>XIMStatusNothing</symbol></entry>
+      <entry>The input method can function without any status values.</entry>
+    </row>
+    <row>
+      <entry><symbol>XIMStatusNone</symbol></entry>
+      <entry>The input method does not provide any status feedback.
+      If chosen, any status value is ignored.
+      This style is mutually exclusive with the other status styles.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+</sect3>
+<sect3 id="Resource_Name_and_Class_c">
+<title>Resource Name and Class</title>
+<!-- .XS -->
+<!-- (SN Resource Name and Class -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNResourceName</symbol>
+and
+<symbol>XNResourceClass</symbol>
+arguments are strings that specify the full name and class
+used by the input method.
+These values should be used as prefixes for the name and class
+when looking up resources that may vary according to the input method.
+If these values are not set,
+the resources will not be fully specified.
+</para>
+<para>
+<!-- .LP -->
+It is not intended that values that can be set as <acronym>XIM</acronym> values be
+set as resources.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Destroy_Callback">
+<title>Destroy Callback</title>
+<!-- .XS -->
+<!-- (SN Destroy Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The 
+<symbol>XNDestroyCallback</symbol>
+argument is a pointer to a structure of type
+<structname>XIMCallback</structname>.
+<symbol>XNDestroyCallback</symbol>
+is triggered when an input method stops its service for any reason. 
+After the callback is invoked, the input method is closed and the
+associated input context(s) are destroyed by Xlib.
+Therefore, the client should not call
+<function>XCloseIM</function>
+or
+<function>XDestroyIC</function>.
+</para>
+<para>
+<!-- .LP -->
+The generic prototype of this callback function is as follows:
+<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='destroycallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>DestroyCallback</replaceable></function></funcdef>
+  <paramdef>XIM<parameter> im</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>im</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input method.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Not used for this callback and always passed as NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+A DestroyCallback is always called with a NULL call_data argument.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Query_IM_IC_Values_List">
+<title>Query IM/IC Values List</title>
+<!-- .XS -->
+<!-- (SN Query IM/IC Values List -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<symbol>XNQueryIMValuesList</symbol>
+and
+<symbol>XNQueryICValuesList</symbol>
+are used to query about <acronym>XIM</acronym> and <acronym>XIC</acronym> values supported by the input method.
+</para>
+<para>
+<!-- .LP -->
+The argument value must be a pointer to a location where the returned
+value will be stored.  The returned value is a pointer to a structure
+of type
+<structname>XIMValuesList</structname>.
+Clients are responsible for freeing the 
+<structname>XIMValuesList</structname>
+structure.
+To do so, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XIMValuesList</structname>
+structure is defined as follows:
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+     unsigned short count_values;
+     char **supported_values;
+} XIMValuesList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect3>
+<sect3 id="Visible_Position">
+<title>Visible Position</title>
+<!-- .XS -->
+<!-- (SN Visible Position -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The 
+<symbol>XNVisiblePosition</symbol>
+argument indicates whether the visible position masks of 
+<type>XIMFeedback</type>
+in
+<structname>XIMText</structname>
+are available.
+</para>
+<para>
+<!-- .LP -->
+The argument value must be a pointer to a location where the returned
+value will be stored.  The returned value is of type
+<type>Bool</type>.
+If the returned value is
+<symbol>True</symbol>,
+the input method uses the visible position masks of
+<type>XIMFeedback</type>
+in
+<structname>XIMText</structname>;
+otherwise, the input method does not use the masks.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIM</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<symbol>XNQueryIMValuesList</symbol>
+before using this argument.
+If the 
+<symbol>XNVisiblePosition</symbol>
+does not exist in the IM values list returned from 
+<symbol>XNQueryIMValuesList</symbol>,
+the visible position masks of
+<type>XIMFeedback</type>
+in
+<structname>XIMText</structname>
+are not used to indicate the visible position.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Preedit_Callback_Behavior">
+<title>Preedit Callback Behavior</title>
+<!-- .XS -->
+<!-- (SN Preedit Callback Behavior -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNR6PreeditCallback</symbol>
+argument originally included in the X11R6 specification has been
+deprecated.\(dg
+<!-- .\" If XNR6PreeditCallbackBehavior is not deprecated, then its type -->
+<!-- .\" should be changed from *Bool to Bool. -->
+<!-- .FS \(dg -->
+During formulation of the X11R6 specification, the behavior of
+the R6 PreeditDrawCallbacks was going to differ significantly from
+that of the R5 callbacks.
+Late changes to the specification converged the R5 and R6 behaviors,
+eliminating the need for
+<symbol>XNR6PreeditCallback</symbol>.
+Unfortunately, this argument was not removed from the R6 specification
+before it was published.
+<!-- .FE -->
+</para>
+<para>
+<!-- .LP -->
+The 
+<symbol>XNR6PreeditCallback</symbol>
+argument indicates whether the behavior of preedit callbacks regarding
+<structname>XIMPreeditDrawCallbackStruct</structname>
+values follows Release 5 or Release 6 semantics.
+</para>
+<para>
+<!-- .LP -->
+The value is of type
+<type>Bool</type>.
+When querying for
+<symbol>XNR6PreeditCallback</symbol>,
+if the returned value is
+<symbol>True</symbol>,
+the input method uses the Release 6 behavior;
+otherwise, it uses the Release 5 behavior.
+The default value is
+<symbol>False</symbol>.
+In order to use Release 6 semantics, the value of
+<symbol>XNR6PreeditCallback</symbol>
+must be set to
+<symbol>True</symbol>.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIM</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<symbol>XNQueryIMValuesList</symbol>
+before using this argument.
+If the
+<symbol>XNR6PreeditCallback</symbol>
+does not exist in the IM values list returned from
+<symbol>XNQueryIMValuesList</symbol>,
+the PreeditCallback behavior is Release 5 semantics.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+</sect2>
+<sect2 id="Input_Context_Functions">
+<title>Input Context Functions</title>
+<!-- .XS -->
+<!-- (SN Input Context Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An input context is an abstraction that is used to contain both the data
+required (if any) by an input method and the information required
+to display that data.
+There may be multiple input contexts for one input method.
+The programming interfaces for creating, reading, or modifying
+an input context use a variable argument list.
+The name elements of the argument lists are referred to as <acronym>XIC</acronym> values.
+It is intended that input methods be controlled by these <acronym>XIC</acronym> values.
+As new <acronym>XIC</acronym> values are created,
+they should be registered with the X Consortium.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create an input context, use
+<function>XCreateIC</function>.
+<indexterm significance="preferred"><primary>XCreateIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreateic'>
+<funcprototype>
+  <funcdef>XIC <function>XCreateIC</function></funcdef>
+  <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>im</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input method.
+<!-- .ds Al \ to set <acronym>XIC</acronym> values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateIC</function>
+function creates a context within the specified input method.
+</para>
+<para>
+<!-- .LP -->
+Some of the arguments are mandatory at creation time, and
+the input context will not be created if those arguments are not provided.
+The mandatory arguments are the input style and the set of text callbacks
+(if the input style selected requires callbacks).
+All other input context values can be set later.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateIC</function>
+returns a NULL value if no input context could be created.
+A NULL value could be returned for any of the following reasons:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+A required argument was not set.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A read-only argument was set (for example,
+<symbol>XNFilterEvents</symbol>).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The argument name is not recognized.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The input method encountered an input method implementation-dependent error.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XCreateIC</function>
+can generate
+<errorname>BadAtom</errorname>,
+<errorname>BadColor</errorname>,
+<errorname>BadPixmap</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy an input context, use
+<function>XDestroyIC</function>.
+<indexterm significance="preferred"><primary>XDestroyIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroyic'>
+<funcprototype>
+  <funcdef>void <function>XDestroyIC</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XDestroyIC</function>
+destroys the specified input context.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To communicate to and synchronize with input method
+for any changes in keyboard focus from the client side,
+use 
+<function>XSetICFocus</function>
+and
+<function>XUnsetICFocus</function>.
+<indexterm significance="preferred"><primary>XSetICFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xseticfocus'>
+<funcprototype>
+  <funcdef>void <function>XSetICFocus</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetICFocus</function>
+function allows a client to notify an input method that the focus window
+attached to the specified input context has received keyboard focus.
+The input method should take action to provide appropriate feedback.
+Complete feedback specification is a matter of user interface policy.
+</para>
+<para>
+<!-- .LP -->
+Calling
+<function>XSetICFocus</function>
+does not affect the focus window value.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XUnsetICFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunseticfocus'>
+<funcprototype>
+  <funcdef>void <function>XUnsetICFocus</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnsetICFocus</function>
+function allows a client to notify an input method that the specified input context
+has lost the keyboard focus and that no more input is expected on the focus window
+attached to that input context.
+The input method should take action to provide appropriate feedback.
+Complete feedback specification is a matter of user interface policy.
+</para>
+<para>
+<!-- .LP -->
+Calling
+<function>XUnsetICFocus</function>
+does not affect the focus window value;
+the client may still receive 
+events from the input method that are directed to the focus window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To reset the state of an input context to its initial state, use
+<function>XmbResetIC</function>
+or
+<function>XwcResetIC</function>.
+<indexterm significance="preferred"><primary>XmbResetIC</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcResetIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbresetic'>
+<funcprototype>
+  <funcdef>char *<function>XmbResetIC</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwcresetic'>
+<funcprototype>
+  <funcdef>wchar_t *<function>XwcResetIC</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When
+<symbol>XNResetState</symbol>
+is set to
+<symbol>XIMInitialState</symbol>,
+<function>XmbResetIC</function>
+and
+<function>XwcResetIC</function>
+reset an input context to its initial state;
+when
+<symbol>XNResetState</symbol>
+is set to
+<symbol>XIMPreserveState</symbol>,
+the current input context state is preserved.
+In both cases, any input pending on that context is deleted.
+The input method is required to clear the preedit area, if any,
+and update the status accordingly.
+Calling 
+<function>XmbResetIC</function>
+or
+<function>XwcResetIC</function>
+does not change the focus.
+</para>
+<para>
+<!-- .LP -->
+The return value of
+<function>XmbResetIC</function>
+is its current preedit string as a multibyte string.
+If there is any preedit text drawn or visible to the user,
+then these procedures must return a non-NULL string.
+If there is no visible preedit text, 
+then it is input method implementation-dependent 
+whether these procedures return a non-NULL string or NULL.
+</para>
+<para>
+<!-- .LP -->
+The client should free the returned string by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the input method associated with an input context, use
+<function>XIMOfIC</function>.
+<indexterm significance="preferred"><primary>XIMOfIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='ximofic'>
+<funcprototype>
+  <funcdef>XIM <function>XIMOfIC</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIMOfIC</function>
+function returns the input method associated with the specified input context.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Xlib provides two functions for setting and reading <acronym>XIC</acronym> values, respectively,
+<function>XSetICValues</function>
+and
+<function>XGetICValues</function>.
+Both functions have a variable-length argument list.
+In that argument list, any <acronym>XIC</acronym> value's name must be denoted
+with a character string using the X Portable Character Set.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set <acronym>XIC</acronym> values, use
+<function>XSetICValues</function>.
+<indexterm significance="preferred"><primary>XSetICValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xseticvalues'>
+<funcprototype>
+  <funcdef>char *<function>XSetICValues</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+<!-- .ds Al \ to set <acronym>XIC</acronym> values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetICValues</function>
+function returns NULL if no error occurred; 
+otherwise,
+it returns the name of the first argument that could not be set.
+An argument might not be set for any of the following reasons:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The argument is read-only (for example,
+<symbol>XNFilterEvents</symbol>).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The argument name is not recognized.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+An implementation-dependent error occurs.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Each value to be set must be an appropriate datum,
+matching the data type imposed by the semantics of the argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetICValues</function>
+can generate
+<errorname>BadAtom</errorname>,
+<errorname>BadColor</errorname>,
+<errorname>BadCursor</errorname>,
+<errorname>BadPixmap</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain <acronym>XIC</acronym> values, use
+<function>XGetICValues</function>.
+<indexterm significance="preferred"><primary>XGetICValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeticvalues'>
+<funcprototype>
+  <funcdef>char *<function>XGetICValues</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+<!-- .ds Al \ to get XIC values -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      ...
+    </term>
+    <listitem>
+      <para>
+Specifies the variable length argument list(Al.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetICValues</function>
+function returns NULL if no error occurred; otherwise,
+it returns the name of the first argument that could not be obtained.
+An argument could not be obtained for any of the following reasons:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The argument name is not recognized.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The input method encountered an implementation-dependent error.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Each IC attribute value argument (following a name) must point to
+a location where the IC value is to be stored.
+That is, if the IC value is of type T,
+the argument must be of type T*.
+If T itself is a pointer type,
+then
+<function>XGetICValues</function>
+allocates memory to store the actual data,
+and the client is responsible for freeing this data by calling
+<function>XFree</function>
+with the returned pointer.
+The exception to this rule is for an IC value of type
+<type>XVaNestedList</type>
+(for preedit and status attributes).
+In this case,  the argument must also be of type
+<type>XVaNestedList</type>.
+Then, the rule of changing type T to T* and freeing the allocated data
+applies to each element of the nested list.
+</para>
+</sect2>
+<sect2 id="Input_Context_Values">
+<title>Input Context Values</title>
+<!-- .XS -->
+<!-- (SN Input Context Values -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following tables describe how <acronym>XIC</acronym> values are interpreted
+by an input method depending on the input style chosen by the 
+user.
+</para>
+<para>
+<!-- .LP -->
+The first column lists the <acronym>XIC</acronym> values.
+The second column indicates which values are involved in affecting,
+negotiating, and setting the geometry of the input method windows.
+The subentries under the third column indicate the different
+input styles that are supported.
+Each of these columns indicates how each of the <acronym>XIC</acronym> values 
+are treated by that input style.
+</para>
+<para>
+<!-- .LP -->
+The following keys apply to these tables.
+</para>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry>Key</entry>
+      <entry>Explanation</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>C</entry>
+      <entry>This value must be set with <function>XCreateIC</function>.</entry>
+    </row>
+    <row>
+      <entry>D</entry>
+      <entry>This value may be set using 
+      <function>XCreateIC</function>.>
+      If it is not set,>
+      a default is provided.</entry>
+    </row>
+    <row>
+      <entry>G</entry>
+      <entry>This value may be read using 
+      <function>XGetICValues</function>.</entry>
+    </row>
+    <row>
+      <entry>GN</entry>
+      <entry>This value may cause geometry negotiation when its value is set by means of
+      <function>XCreateIC</function>
+      or
+      <function>XSetICValues</function>.</entry>
+    </row>
+    <row>
+      <entry>GR</entry>
+      <entry>This value will be the response of the input method when any 
+      GN value is changed.</entry>
+    </row>
+    <row>
+      <entry>GS</entry>
+      <entry>This value will cause the geometry of the input method window to be set.</entry>
+    </row>
+    <row>
+      <entry>O</entry>
+      <entry>This value must be set once and only once.
+      It need not be set at create time.</entry>
+    </row>
+    <row>
+      <entry>S</entry>
+      <entry>This value may be set with
+      <function>XSetICValues</function>.</entry>
+    </row>
+    <row>
+      <entry>Ignored</entry>
+      <entry>This value is ignored by the input method for the given input style.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<!-- .LP -->
+<informaltable>
+  <tgroup cols='7' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <colspec colname='c4'/>
+  <colspec colname='c5'/>
+  <colspec colname='c6'/>
+  <colspec colname='c7'/>
+  <tbody>
+    <row>
+      <entry><acronym>XIC</acronym> Value</entry>
+      <entry>Geometry Mangement</entry>
+      <entry>Preedit Callback</entry>
+      <entry>Preedit Position</entry>
+      <entry>Input Style Preedit Area</entry>
+      <entry>Preedit Nothing</entry>
+      <entry>Preedit None</entry>
+    </row>
+    <row>
+      <entry>Input Style</entry>
+      <entry></entry>
+      <entry>C-G</entry>
+      <entry>C-G</entry>
+      <entry>C-G</entry>
+      <entry>C-G</entry>
+      <entry>C-G</entry>
+    </row>
+    <row>
+      <entry>Client Window</entry>
+      <entry></entry>
+      <entry>O-G</entry>
+      <entry>O-G</entry>
+      <entry>O-G</entry>
+      <entry>O-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Focus Window</entry>
+      <entry>GN</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Resource Name</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Resource Class</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Geometry Callback</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Filter Events</entry>
+      <entry></entry>
+      <entry>G</entry>
+      <entry>G</entry>
+      <entry>G</entry>
+      <entry>G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Destroy Callback</entry>
+      <entry></entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+    </row>
+    <row>
+      <entry>String Conversion Callback</entry>
+      <entry></entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+    </row>
+    <row>
+      <entry>String Conversion</entry>
+      <entry></entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+    </row>
+    <row>
+      <entry>Reset State</entry>
+      <entry></entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>HotKey</entry>
+      <entry></entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>HotKeyState</entry>
+      <entry></entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry><function>Preedit</function></entry>
+    </row>
+    <row>
+      <entry>Area</entry>
+      <entry>GS</entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Area Needed</entry>
+      <entry>GN-GR</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+      <entry>S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Spot Location</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Colormap</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Foreground</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Background</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Background Pixmap</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Font Set</entry>
+      <entry>GN</entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Line Spacing</entry>
+      <entry>GN</entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Cursor</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Preedit State</entry>
+      <entry></entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Preedit State Notify Callback</entry>
+      <entry></entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Preedit Callbacks</entry>
+      <entry></entry>
+      <entry>C-S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<!-- .LP -->
+<informaltable>
+  <tgroup cols='6' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <colspec colname='c4'/>
+  <colspec colname='c5'/>
+  <colspec colname='c6'/>
+  <thead>
+    <row>
+      <entry><acronym>XIC</acronym> Value</entry>
+      <entry>Geomentry Management</entry>
+      <entry>Status Callback</entry>
+      <entry>Status Area</entry>
+      <entry>Status Nothing</entry>
+      <entry>Status None</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>Input Style</entry>
+      <entry></entry>
+      <entry>C-G</entry>
+      <entry>C-G</entry>
+      <entry>C-G</entry>
+      <entry>C-G</entry>
+    </row>
+    <row>
+      <entry>Client Window</entry>
+      <entry></entry>
+      <entry>O-G</entry>
+      <entry>O-G</entry>
+      <entry>O-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Focus Window</entry>
+      <entry>GN</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Resource Name</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Resource Class</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Geometry Callback</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Filter Events</entry>
+      <entry></entry>
+      <entry>G</entry>
+      <entry>G</entry>
+      <entry>G</entry>
+      <entry>G</entry>
+    </row>
+    <row>
+      <entry><type>Status</type></entry>
+    </row>
+    <row>
+      <entry>Area</entry>
+      <entry>GS</entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Area Needed</entry>
+      <entry>GN-GR</entry>
+      <entry>Ignored</entry>
+      <entry>S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Colormap</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Foreground</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Background</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Background Pixmap</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Font Set</entry>
+      <entry>GN</entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Line Spacing</entry>
+      <entry>GN</entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Cursor</entry>
+      <entry></entry>
+      <entry>Ignored</entry>
+      <entry>D-S-G</entry>
+      <entry>D-S-G</entry>
+      <entry>Ignored</entry>
+    </row>
+    <row>
+      <entry>Status Callbacks</entry>
+      <entry></entry>
+      <entry>C-S-G</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+      <entry>Ignored</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+<sect3 id="Input_Style">
+<title>Input Style</title>
+<!-- .XS -->
+<!-- (SN Input Style -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNInputStyle</symbol>
+argument specifies the input style to be used.
+The value of this argument must be one of the values returned by the
+<function>XGetIMValues</function>
+function with the
+<symbol>XNQueryInputStyle</symbol>
+argument specified in the supported_styles list.
+</para>
+<para>
+<!-- .LP -->
+Note that this argument must be set at creation time
+and cannot be changed.
+</para>
+</sect3>
+<sect3 id="Client_Window">
+<title>Client Window</title>
+<!-- .XS -->
+<!-- (SN Client Window -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNClientWindow</primary></indexterm>
+The
+<symbol>XNClientWindow</symbol>
+argument specifies to the input method the client window in
+which the input method
+can display data or create subwindows.
+Geometry values for input method areas are given with respect to the client
+window.
+Dynamic change of client window is not supported.
+This argument may be set only once and
+should be set before any input is done using this input context.
+If it is not set,
+the input method may not operate correctly.
+</para>
+<para>
+<!-- .LP -->
+If an attempt is made to set this value a second time with
+<function>XSetICValues</function>,
+the string
+<symbol>XNClientWindow</symbol>
+will be returned by
+<function>XSetICValues</function>,
+and the client window will not be changed.
+</para>
+<para>
+<!-- .LP -->
+If the client window is not a valid window ID on the display
+attached to the input method,
+a 
+<errorname>BadWindow</errorname>
+error can be generated when this value is used by the input method.
+</para>
+</sect3>
+<sect3 id="Focus_Window">
+<title>Focus Window</title>
+<!-- .XS -->
+<!-- (SN Focus Window -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNFocusWindow</primary></indexterm>
+The
+<symbol>XNFocusWindow</symbol>
+argument specifies the focus window.
+The primary purpose of the 
+<symbol>XNFocusWindow</symbol>
+is to identify the window that will receive the key event when input
+is composed.
+In addition, the input method may possibly affect the focus window
+as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Select events on it
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Send events to it
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Modify its properties
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Grab the keyboard within that window  
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The associated value must be of type 
+<type>Window</type>.
+If the focus window is not a valid window ID on the display 
+attached to the input method,
+a 
+<errorname>BadWindow</errorname>
+error can be generated when this value is used by the input method.
+</para>
+<para>
+<!-- .LP -->
+When this <acronym>XIC</acronym> value is left unspecified,
+the input method will use the client window as the default focus window.
+</para>
+</sect3>
+<sect3 id="Resource_Name_and_Class_b">
+<title>Resource Name and Class</title>
+<!-- .XS -->
+<!-- (SN Resource Name and Class -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNResourceName</primary></indexterm>
+<indexterm significance="preferred"><primary>XNResourceClass</primary></indexterm>
+The
+<symbol>XNResourceName</symbol>
+and
+<symbol>XNResourceClass</symbol>
+arguments are strings that specify the full name and class
+used by the client to obtain resources for the client window. 
+These values should be used as prefixes for name and class
+when looking up resources that may vary according to the input context.
+If these values are not set,
+the resources will not be fully specified.
+</para>
+<para>
+<!-- .LP -->
+It is not intended that values that can be set as <acronym>XIC</acronym> values be
+set as resources.
+</para>
+</sect3>
+<sect3 id="Geometry_Callback">
+<title>Geometry Callback</title>
+<!-- .XS -->
+<!-- (SN Geometry Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNGeometryCallback</primary></indexterm>
+The 
+<symbol>XNGeometryCallback</symbol>
+argument is a structure of type 
+<structname>XIMCallback</structname>
+(see section 13.5.6.13.12).
+</para>
+<para>
+<!-- .LP -->
+The 
+<symbol>XNGeometryCallback</symbol>
+argument specifies the geometry callback that a client can set.
+This callback is not required for correct operation of either 
+an input method or a client.
+It can be set for a client whose user interface policy permits
+an input method to request the dynamic change of that input 
+method's window.
+An input method that does dynamic change will need to filter any
+events that it uses to initiate the change.
+</para>
+</sect3>
+<sect3 id="Filter_Events">
+<title>Filter Events</title>
+<!-- .XS -->
+<!-- (SN Filter Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNFilterEvents</primary></indexterm>
+The 
+<symbol>XNFilterEvents</symbol>
+argument returns the event mask that an input method needs
+to have selected for.
+The client is expected to augment its own event mask 
+for the client window with this one.
+</para>
+<para>
+<!-- .LP -->
+This argument is read-only, is set by the input method at create time,
+and is never changed.
+</para>
+<para>
+<!-- .LP -->
+The type of this argument is 
+<type>unsigned</type>
+<type>long</type>.
+Setting this value will cause an error.
+</para>
+</sect3>
+<sect3 id="Destroy_Callback_b">
+<title>Destroy Callback</title>
+<!-- .XS -->
+<!-- (SN Destroy Callback  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The 
+<symbol>XNDestroyCallback</symbol>
+argument is a pointer to a structure of type
+<structname>XIMCallback</structname>
+(see section 13.5.6.13.12).  This callback is triggered when the input method 
+stops its service for any reason; for example, when a connection to an IM
+server is broken.  After the destroy callback is called, 
+the input context is destroyed and the input method is closed.
+Therefore, the client should not call 
+<function>XDestroyIC</function>
+and
+<function>XCloseIM</function>.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="String_Conversion_Callback">
+<title>String Conversion Callback</title>
+<!-- .XS -->
+<!-- (SN String Conversion Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNStringConversionCallback</symbol>
+argument is a structure of type
+<structname>XIMCallback</structname>
+(see section 13.5.6.13.12).
+</para>
+<para>
+<!-- .LP -->
+The
+<symbol>XNStringConversionCallback</symbol>
+argument specifies a string conversion callback.  This callback
+is not required for correct operation of
+either the input method or the client.  It can be set by a client
+to support string conversions that may be requested
+by the input method.  An input method that does string conversions
+will filter any events that it uses to initiate the conversion.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<symbol>XNQueryICValuesList</symbol>
+before using this argument.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="String_Conversion_">
+<title>String Conversion </title>
+<!-- .XS -->
+<!-- (SN String Conversion -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNStringConversion</symbol>
+argument is a structure of type
+<structname>XIMStringConversionText</structname>.
+</para>
+<para>
+<!-- .LP -->
+The
+<symbol>XNStringConversion</symbol>
+argument specifies the string to be converted by an input method.
+This argument is not required for correct operation of either
+the input method or the client.
+</para>
+<para>
+<!-- .LP -->
+String conversion facilitates the manipulation of text independent
+of preediting.
+It is essential for some input methods and clients to manipulate
+text by performing context-sensitive conversion,
+reconversion, or transliteration conversion on it.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<symbol>XNQueryICValuesList</symbol>
+before using this argument.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XIMStringConversionText</structname>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+
+typedef struct _XIMStringConversionText {
+     unsigned short              length;
+     XIMStringConversionFeedback *feedback;
+     Bool                        encoding_is_wchar;
+     union {
+          char     *mbs;
+          wchar_t  *wcs;
+     } string;
+} XIMStringConversionText;
+
+typedef unsigned long XIMStringConversionFeedback;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The feedback member is reserved for future use.  The text to be
+converted is defined by the string and length members.  The length
+is indicated in characters.  To prevent the library from freeing memory
+pointed to by an uninitialized pointer, the client should set the feedback
+element to NULL.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Reset_State">
+<title>Reset State</title>
+<!-- .XS -->
+<!-- (SN Reset State -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNResetState</symbol>
+argument specifies the state the input context will return to after calling
+<function>XmbResetIC</function>
+or
+<function>XwcResetIC</function>.
+</para>
+<para>
+<!-- .LP -->
+The <acronym>XIC</acronym> state may be set to its initial state, as specified by the
+<symbol>XNPreeditState</symbol>
+value when
+<function>XCreateIC</function>
+was called, or it may be set to preserve the current state.
+</para>
+<para>
+<!-- .LP -->
+The valid masks for
+<type>XIMResetState</type>
+are as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMInitialState</primary></indexterm>
+<indexterm significance="preferred"><primary>XINPreserveState</primary></indexterm>
+<!-- .sM -->
+</para>
+<literallayout class="monospaced">
+typedef unsigned long XIMResetState;
+
+#define XIMInitialState  (1L)
+#define XIMPreserveState (1L&lt;&lt;1)
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If
+<symbol>XIMInitialState</symbol>
+is set, then
+<function>XmbResetIC</function>
+and
+<function>XwcResetIC</function>
+will return to the initial
+<symbol>XNPreeditState</symbol>
+state of the <acronym>XIC</acronym>.
+</para>
+<para>
+<!-- .LP -->
+If
+<symbol>XIMPreserveState</symbol>
+is set, then 
+<function>XmbResetIC</function>
+and
+<function>XwcResetIC</function>
+will preserve the current state of the <acronym>XIC</acronym>.
+</para>
+<para>
+<!-- .LP -->
+If
+<symbol>XNResetState</symbol>
+is left unspecified, the default is
+<symbol>XIMInitialState</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<type>XIMResetState</type>
+values other than those specified above will default to
+<symbol>XIMInitialState</symbol>.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<symbol>XNQueryICValuesList</symbol>
+before using this argument.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Hot_Keys_b">
+<title>Hot Keys</title>
+<!-- .XS -->
+<!-- (SN Hot Keys -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNHotKey</symbol>
+argument specifies the hot key list to the <acronym>XIC</acronym>.
+The hot key list is a pointer to the structure of type
+<structname>XIMHotKeyTriggers</structname>,
+which specifies the key events that must be received
+without any interruption of the input method.
+For the hot key list set with this argument to be utilized, the client
+must also set
+<symbol>XNHotKeyState</symbol>
+to
+<symbol>XIMHotKeyStateON</symbol>.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<symbol>XNQueryICValuesList</symbol>
+before using this functionality.
+</para>
+<para>
+<!-- .LP -->
+The value of the argument is a pointer to a structure of type
+<structname>XIMHotKeyTriggers</structname>.
+</para>
+<para>
+<!-- .LP -->
+If an event for a key in the hot key list is found, then the process will
+receive the event and it will be processed inside the client.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+     KeySym keysym;
+     unsigned int modifier;
+     unsigned int modifier_mask;
+} XIMHotKeyTrigger;
+
+typedef struct {
+     int num_hot_key;
+     XIMHotKeyTrigger *key;
+} XIMHotKeyTriggers;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+<para>
+<!-- .LP -->
+The combination of modifier and modifier_mask are used to represent one of
+three states for each modifier:
+either the modifier must be on, or the modifier must be off, or the modifier
+is a ``don't care'' - it may be on or off.
+When a modifier_mask bit is set to 0, the state of the associated modifier
+is ignored when evaluating whether the key is hot or not.
+</para>
+
+<informaltable>
+  <tgroup cols='3' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <thead>
+    <row>
+      <entry>Modifier Bit</entry>
+      <entry>Mask Bit</entry>
+      <entry>Meaning</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>0</entry>
+      <entry>1</entry>
+      <entry>The modifier must be off.</entry>
+    </row>
+    <row>
+      <entry>1</entry>
+      <entry>1</entry>
+      <entry>The modifier must be on.</entry>
+    </row>
+    <row>
+      <entry>n/a</entry>
+      <entry>0</entry>
+      <entry>Do not care if the modifier is on or off.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+</sect3>
+<sect3 id="Hot_Key_State">
+<title>Hot Key State</title>
+<!-- .XS -->
+<!-- (SN Hot Key State -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNHotKeyState</symbol>
+argument specifies the hot key state of the input method.
+This is usually used to switch the input method between hot key
+operation and normal input processing.
+</para>
+<para>
+<!-- .LP -->
+The value of the argument is a pointer to a structure of type
+XIMHotKeyState .
+</para>
+<literallayout class="monospaced">
+typedef unsigned long XIMHotKeyState;
+
+#define XIMHotKeyStateON            (0x0001L)
+#define XIMHotKeyStateOFF           (0x0002L)
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+<para>
+<!-- .LP -->
+If not specified, the default is
+<symbol>XIMHotKeyStateOFF</symbol>.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+<sect3 id="Preedit_and_Status_Attributes">
+<title>Preedit and Status Attributes</title>
+<!-- .XS -->
+<!-- (SN Preedit and Status Attributes -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNPreeditAttributes</primary></indexterm>
+<indexterm significance="preferred"><primary>XNStatusAttributes</primary></indexterm>
+The
+<symbol>XNPreeditAttributes</symbol>
+and
+<symbol>XNStatusAttributes</symbol>
+arguments specify to an input method the attributes to be used for the 
+preedit and status areas,
+if any.
+Those attributes are passed to 
+<function>XSetICValues</function>
+or
+<function>XGetICValues</function>
+as a nested variable-length list.
+The names to be used in these lists are described in the following sections.
+</para>
+<sect4 id="Area">
+<title>Area</title>
+<!-- .XS -->
+<!-- (SN Area -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNArea</primary></indexterm>
+The value of the
+<symbol>XNArea</symbol>
+argument must be a pointer to a structure of type
+<structname>XRectangle</structname>.
+The interpretation of the
+<symbol>XNArea</symbol>
+argument is dependent on the input method style that has been set.
+</para>
+<para>
+<!-- .LP -->
+If the input method style is 
+<symbol>XIMPreeditPosition</symbol>,
+<symbol>XNArea</symbol>
+specifies the clipping region within which preediting will take place.
+If the focus window has been set,
+the coordinates are assumed to be relative to the focus window.
+Otherwise, the coordinates are assumed to be relative to the client window.
+If neither has been set,
+the results are undefined.
+</para>
+<para>
+<!-- .LP -->
+If 
+<symbol>XNArea</symbol>
+is not specified, is set to NULL, or is invalid,
+the input method will default the clipping region
+to the geometry of the
+<symbol>XNFocusWindow</symbol>.
+If the area specified is NULL or invalid,
+the results are undefined.
+</para>
+<para>
+<!-- .LP -->
+If the input style is 
+<symbol>XIMPreeditArea</symbol>
+or 
+<symbol>XIMStatusArea</symbol>,
+<symbol>XNArea</symbol>
+specifies the geometry provided by the client to the input method.
+The input method may use this area to display its data,
+either preedit or status depending on the area designated.
+The input method may create a window as a child of the client window
+with dimensions that fit the
+<symbol>XNArea</symbol>.
+The coordinates are relative to the client window.
+If the client window has not been set yet,
+the input method should save these values 
+and apply them when the client window is set.
+If 
+<symbol>XNArea</symbol>
+is not specified, is set to NULL, or is invalid,
+the results are undefined.
+</para>
+</sect4>
+<sect4 id="Area_Needed">
+<title>Area Needed</title>
+<!-- .XS -->
+<!-- (SN Area Needed -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNAreaNeeded</primary></indexterm>
+When set, the
+<symbol>XNAreaNeeded</symbol>
+argument specifies the geometry suggested by the client for this area
+(preedit or status).
+The value associated with the argument must be a pointer to a 
+structure of type 
+<structname>XRectangle</structname>.
+Note that the x, y values are not used
+and that nonzero values for width or height are the constraints 
+that the client wishes the input method to respect.
+</para>
+<para>
+<!-- .LP -->
+When read, the
+<symbol>XNAreaNeeded</symbol>
+argument specifies the preferred geometry desired by the input method
+for the area.
+</para>
+<para>
+<!-- .LP -->
+This argument is only valid if the input style is 
+<symbol>XIMPreeditArea</symbol>
+or 
+<symbol>XIMStatusArea</symbol>.
+It is used for geometry negotiation between the client and the input method
+and has no other effect on the input method 
+(see section 13.5.1.5).
+</para>
+</sect4>
+<sect4 id="Spot_Location">
+<title>Spot Location</title>
+<!-- .XS -->
+<!-- (SN Spot Location -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNSpotLocation</primary></indexterm>
+The
+<symbol>XNSpotLocation</symbol>
+argument specifies to the input method the coordinates of the spot
+to be used by an input method executing with 
+<symbol>XNInputStyle</symbol>
+set to 
+<symbol>XIMPreeditPosition</symbol>.
+When specified to any input method other than 
+<symbol>XIMPreeditPosition</symbol>,
+this <acronym>XIC</acronym> value is ignored.
+</para>
+<para>
+<!-- .LP -->
+The x coordinate specifies the position where the next character
+would be inserted.
+The y coordinate is the position of the baseline used
+by the current text line in the focus window.
+The x and y coordinates are relative to the focus window, if it has been set;
+otherwise, they are relative to the client window.
+If neither the focus window nor the client window has been set,
+the results are undefined.
+</para>
+<para>
+<!-- .LP -->
+The value of the argument is a pointer to a structure of type
+<structname>XPoint</structname>.
+</para>
+</sect4>
+<sect4 id="Colormap">
+<title>Colormap</title>
+<!-- .XS -->
+<!-- (SN Colormap -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Two different arguments can be used to indicate what colormap the input method
+should use to allocate colors, a colormap ID, or a standard colormap name.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNColormap</primary></indexterm>
+The
+<symbol>XNColormap</symbol>
+argument is used to specify a colormap ID.
+The argument value is of type
+<type>Colormap</type>.
+An invalid argument may generate a 
+<errorname>BadColor</errorname>
+error when it is used by the input method.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNStdColormap</primary></indexterm>
+The
+<symbol>XNStdColormap</symbol>
+argument is used to indicate the name of the standard colormap
+in which the input method should allocate colors.
+The argument value is an 
+<type>Atom</type>
+that should be a valid atom for calling
+<function>XGetRGBColormaps</function>.
+An invalid argument may generate a
+<errorname>BadAtom</errorname>
+error when it is used by the input method.
+</para>
+<para>
+<!-- .LP -->
+If the colormap is left unspecified,
+the client window colormap becomes the default.
+</para>
+</sect4>
+<sect4 id="Foreground_and_Background">
+<title>Foreground and Background</title>
+<!-- .XS -->
+<!-- (SN Foreground and Background -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNForeground</primary></indexterm>
+<indexterm significance="preferred"><primary>XNBackground</primary></indexterm>
+The
+<symbol>XNForeground</symbol>
+and
+<symbol>XNBackground</symbol>
+arguments specify the foreground and background pixel, respectively.
+The argument value is of type
+<type>unsigned</type>
+<type>long</type>.
+It must be a valid pixel in the input method colormap.
+</para>
+<para>
+<!-- .LP -->
+If these values are left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Background_Pixmap">
+<title>Background Pixmap</title>
+<!-- .XS -->
+<!-- (SN Background Pixmap -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNBackgroundPixmap</symbol>
+argument specifies a background pixmap to be used as the background of the
+window.
+The value must be of type 
+<type>Pixmap</type>.
+An invalid argument may generate a
+<errorname>BadPixmap</errorname>
+error when it is used by the input method.
+</para>
+<para>
+<!-- .LP -->
+If this value is left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Font_Set">
+<title>Font Set</title>
+<!-- .XS -->
+<!-- (SN Font Set -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNFontSet</primary></indexterm>
+The
+<symbol>XNFontSet</symbol>
+argument specifies to the input method what font set is to be used.
+The argument value is of type
+<type>XFontSet</type>.
+</para>
+<para>
+<!-- .LP -->
+If this value is left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Line_Spacing">
+<title>Line Spacing</title>
+<!-- .XS -->
+<!-- (SN Line Spacing -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNLineSpace</symbol>
+argument specifies to the input method what line spacing is to be used
+in the preedit window if more than one line is to be used.
+This argument is of type
+<type>int</type>.
+</para>
+<para>
+<!-- .LP -->
+If this value is left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Cursor">
+<title>Cursor</title>
+<!-- .XS -->
+<!-- (SN Cursor -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNCursor</primary></indexterm>
+The
+<symbol>XNCursor</symbol>
+argument specifies to the input method what cursor is to be used
+in the specified window.
+This argument is of type 
+<type>Cursor</type>.
+</para>
+<para>
+<!-- .LP -->
+An invalid argument may generate a
+<errorname>BadCursor</errorname>
+error when it is used by the input method.
+If this value is left unspecified,
+the default is determined by the input method.
+</para>
+</sect4>
+<sect4 id="Preedit_State">
+<title>Preedit State</title>
+<!-- .XS -->
+<!-- (SN Preedit State -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<symbol>XNPreeditState</symbol>
+argument specifies the state of input preediting for the input method.
+Input preediting can be on or off.
+</para>
+<para>
+<!-- .LP -->
+The valid mask names for
+<symbol>XNPreeditState</symbol>
+are as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMPreeditUnknown</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditEnable</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreeditDisable</primary></indexterm>
+<!-- .sM -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+typedef unsigned long XIMPreeditState;
+
+#define XIMPreeditUnknown    0L
+#define XIMPreeditEnable     1L
+#define XIMPreeditDisable    (1L&lt;&lt;1)
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If a value of
+<symbol>XIMPreeditEnable</symbol>
+is set, then input preediting is turned on by the input method.
+</para>
+<para>
+<!-- .LP -->
+If a value of
+<symbol>XIMPreeditDisable</symbol>
+is set, then input preediting is turned off by the input method.
+</para>
+<para>
+<!-- .LP -->
+If
+<symbol>XNPreeditState</symbol>
+is left unspecified, then the state will be implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+When
+<symbol>XNResetState</symbol>
+is set to
+<symbol>XIMInitialState</symbol>,
+the
+<symbol>XNPreeditState</symbol>
+value specified at the creation time will be reflected as the initial state for
+<function>XmbResetIC</function>
+and
+<function>XwcResetIC</function>.
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<symbol>XNQueryICValuesList</symbol>
+before using this argument.
+</para>
+</sect4>
+<sect4 id="Preedit_State_Notify_Callback">
+<title>Preedit State Notify Callback</title>
+<!-- .XS -->
+<!-- (SN Preedit State Notify Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The preedit state notify callback is triggered by the input method
+when the preediting state has changed.
+The value of the
+<symbol>XNPreeditStateNotifyCallback</symbol>
+argument is a pointer to a structure of type
+<structname>XIMCallback</structname>.
+The generic prototype is as follows:
+<indexterm significance="preferred"><primary>PreeditStateNotifyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditstatenotifycallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>PreeditStateNotifyCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XIMPreeditStateNotifyCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the current preedit state.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<structname>XIMPreeditStateNotifyCallbackStruct</structname>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMPreeditStateNotifyCallbackStruct</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XIMPreeditStateNotifyCallbackStruct {
+     XIMPreeditState state;
+} XIMPreeditStateNotifyCallbackStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+<para>
+<!-- .LP -->
+Because this <acronym>XIC</acronym> value is optional, a client should call
+<function>XGetIMValues</function>
+with argument
+<symbol>XNQueryICValuesList</symbol>
+before using this argument.
+</para>
+</sect4>
+<sect4 id="Preedit_and_Status_Callbacks">
+<title>Preedit and Status Callbacks</title>
+<!-- .XS -->
+<!-- (SN Preedit and Status Callbacks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A client that wants to support the input style
+<symbol>XIMPreeditCallbacks</symbol>
+must provide a set of preedit callbacks to the input method.
+The set of preedit callbacks is as follows:
+</para>
+<indexterm significance="preferred"><primary>XNPreeditStartCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNPreeditDoneCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNPreeditDrawCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNPreeditCaretCallback</primary></indexterm>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>XNPreeditStartCallback</symbol></entry>
+      <entry>This is called when the input method starts preedit.</entry>
+    </row>
+    <row>
+      <entry><symbol>XNPreeditDoneCallback</symbol></entry>
+      <entry>This is called when the input method stops preedit.</entry>
+    </row>
+    <row>
+      <entry><symbol>XNPreeditDrawCallback</symbol></entry>
+      <entry>This is called when a number of preedit keystrokes should be echoed.</entry>
+    </row>
+    <row>
+      <entry><symbol>XNPreeditCaretCallback</symbol></entry>
+      <entry>This is called to move the text insertion point within the preedit string.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+A client that wants to support the input style
+<symbol>XIMStatusCallbacks</symbol>
+must provide a set of status callbacks to the input method.
+The set of status callbacks is as follows:
+</para>
+
+<indexterm significance="preferred"><primary>XNStatusStartCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNStatusDoneCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XNStatusDrawCallback</primary></indexterm>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>XNStatusStartCallback</symbol></entry>
+      <entry>This is called when the input method initializes the status area.</entry>
+    </row>
+    <row>
+      <entry><symbol>XNStatusDoneCallback</symbol></entry>
+      <entry>This is called when the input method no longer needs the status area.</entry>
+    </row>
+    <row>
+      <entry><symbol>XNStatusDrawCallback</symbol></entry>
+      <entry>This is called when updating of the status area is required.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+<para>
+<!-- .LP -->
+The value of any status or preedit argument is a pointer
+to a structure of type
+<structname>XIMCallback</structname>.
+<indexterm significance="preferred"><primary>XIMProc</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMCallback</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef void (*XIMProc)();
+
+typedef struct {
+     XPointer client_data;
+     XIMProc callback;
+} XIMCallback;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Each callback has some particular semantics and will carry the data
+that expresses the environment necessary to the client 
+into a specific data structure.
+This paragraph only describes the arguments to be used to set
+the callback.
+</para>
+<para>
+<!-- .LP -->
+Setting any of these values while doing preedit
+may cause unexpected results.
+</para>
+</sect4>
+</sect3>
+</sect2>
+<sect2 id="Input_Method_Callback_Semantics">
+<title>Input Method Callback Semantics</title>
+<!-- .XS -->
+<!-- (SN Input Method Callback Semantics -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<acronym>XIM</acronym> callbacks are procedures defined by clients or text drawing packages
+that are to be called from the input method when selected events occur.
+Most clients will use a text editing package or a toolkit
+and, hence, will not need to define such callbacks.
+This section defines the callback semantics, when they are triggered,
+and what their arguments are.
+This information is mostly useful for X toolkit implementors.
+</para>
+<para>
+<!-- .LP -->
+Callbacks are mostly provided so that clients (or text editing
+packages) can implement on-the-spot preediting in their own window.
+In that case,
+the input method needs to communicate and synchronize with the client.
+The input method needs to communicate changes in the preedit window 
+when it is under control of the client.
+Those callbacks allow the client to initialize the preedit area,
+display a new preedit string,
+move the text insertion point during preedit,
+terminate preedit, or update the status area.
+</para>
+<para>
+<!-- .LP -->
+All callback procedures follow the generic prototype:
+<indexterm significance="preferred"><primary>CallbackPrototype</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function><replaceable>CallbackPrototype</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>SomeType<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies data specific to the callback.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The call_data argument is a structure that expresses the arguments needed
+to achieve the semantics;
+that is,
+it is a specific data structure appropriate to the callback.
+In cases where no data is needed in the callback,
+this call_data argument is NULL.
+The client_data argument is a closure that has been initially specified
+by the client when specifying the callback and passed back.
+It may serve, for example, to inherit application context in the callback.
+</para>
+<para>
+<!-- .LP -->
+The following paragraphs describe the programming semantics
+and specific data structure associated with the different reasons.
+</para>
+<sect3 id="Geometry_Callback_b">
+<title>Geometry Callback</title>
+<!-- .XS -->
+<!-- (SN Geometry Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The geometry callback is triggered by the input method 
+to indicate that it wants the client to negotiate geometry.
+The generic prototype is as follows:
+<indexterm significance="preferred"><primary>GeometryCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function><replaceable>GeometryCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Not used for this callback and always passed as NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback is called with a NULL call_data argument.
+</para>
+</sect3>
+<sect3 id="Destroy_Callback_c">
+<title>Destroy Callback</title>
+<!-- .XS -->
+<!-- (SN Destroy Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The destroy callback is triggered by the input method 
+when it stops service for any reason.
+After the callback is invoked, the input context will be freed by Xlib.
+The generic prototype is as follows:
+<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='destroycallback_xic'>
+<funcprototype>
+  <funcdef>void <function><replaceable>DestroyCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Not used for this callback and always passed as NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback is called with a NULL call_data argument.
+</para>
+</sect3>
+<sect3 id="String_Conversion_Callback_b">
+<title>String Conversion Callback</title>
+<!-- .XS -->
+<!-- (SN String Conversion Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The string conversion callback is triggered by the input method 
+to request the client to return the string to be converted.  The
+returned string may be either a multibyte or wide character string,
+with an encoding matching the locale bound to the input context.
+The callback prototype is as follows:
+<indexterm significance="preferred"><primary>StringConversionCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='stringconversioncallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>StringConversionCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XIMStringConversionCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input method.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the amount of the string to be converted.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback is passed an
+<structname>XIMStringConversionCallbackStruct</structname>
+structure in the call_data argument.
+The text member is an
+<structname>XIMStringConversionText</structname>
+structure (see section 13.5.6.9) to be filled in by the client
+and describes the text to be sent to the input method.
+The data pointed to by the 
+string and feedback elements of the
+<structname>XIMStringConversionText</structname>
+structure will be freed using
+<function>XFree</function>
+by the input method
+after the callback returns.  So the client should not point to 
+internal buffers that are critical to the client.
+Similarly, because the feedback element is currently reserved for future
+use, the client should set feedback to NULL to prevent the library from
+freeing memory at some random location due to an uninitialized pointer.
+</para>
+<para>
+<!-- .LP -->
+The 
+<structname>XIMStringConversionCallbackStruct</structname>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMStringConversionCallbackStruct</primary></indexterm>
+<!-- .sM -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+typedef struct _XIMStringConversionCallbackStruct {
+     XIMStringConversionPosition position;          
+     XIMCaretDirection direction;
+     short factor;
+     XIMStringConversionOperation operation;
+     XIMStringConversionText *text;
+} XIMStringConversionCallbackStruct;
+
+typedef short XIMStringConversionPosition;
+
+typedef unsigned short XIMStringConversionOperation;
+
+#define XIMStringConversionSubstitution       (0x0001)
+#define XIMStringConversionRetrieval          (0x0001)
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<type>XIMStringConversionPosition</type>
+specifies the starting position of the string to be returned
+in the
+<structname>XIMStringConversionText</structname>
+structure.  The value identifies a position, in units of characters,
+relative to the client's cursor position in the client's buffer.
+</para>
+<para>
+<!-- .LP -->
+The ending position of the text buffer is determined by
+the direction and factor members.  Specifically, it is the character position 
+relative to the starting point as defined by the
+<structname>XIMCaretDirection</structname>.
+The factor member of 
+<structname>XIMStringConversionCallbackStruct</structname>
+specifies the number of
+<structname>XIMCaretDirection</structname>
+positions to be applied.  For example, if the direction specifies
+<constant>XIMLineEnd</constant>
+and factor is 1, then all characters from the starting position to 
+the end of the current display line are returned.  If the direction
+specifies
+<constant>XIMForwardChar</constant>
+or
+<constant>XIMBackwardChar</constant>,
+then the factor specifies a relative position, indicated in characters, 
+from the starting position.
+</para>
+<para>
+<!-- .LP -->
+<type>XIMStringConversionOperation</type>
+specifies whether the string to be converted should be 
+deleted (substitution) or copied (retrieval) from the client's
+buffer.  When the
+<type>XIMStringConversionOperation</type>
+is
+<symbol>XIMStringConversionSubstitution</symbol>,
+the client must delete the string to be converted from its own buffer.
+When the
+<type>XIMStringConversionOperation</type>
+is
+<symbol>XIMStringConversionRetrieval</symbol>,
+the client must not delete the string to be converted from its buffer.
+The substitute operation is typically used for reconversion and
+transliteration conversion,
+while the retrieval operation is typically used for context-sensitive 
+conversion.
+</para>
+</sect3>
+<sect3 id="Preedit_State_Callbacks">
+<title>Preedit State Callbacks</title>
+<!-- .XS -->
+<!-- (SN Preedit State Callbacks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When the input method turns preediting on or off, a
+<function><replaceable>PreeditStartCallback</replaceable></function>
+or
+<function><replaceable>PreeditDoneCallback</replaceable></function>
+callback is triggered to let the toolkit do the setup
+or the cleanup for the preedit region.
+<indexterm significance="preferred"><primary>PreeditStartCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditstartcallback'>
+<funcprototype>
+  <funcdef>int <function><replaceable>PreeditStartCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Not used for this callback and always passed as NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When preedit starts on the specified input context,
+the callback is called with a NULL call_data argument.
+<function><replaceable>PreeditStartCallback</replaceable></function>
+will return the maximum size of the preedit string.
+A positive number indicates the maximum number of bytes allowed
+in the preedit string, 
+and a value of -1 indicates there is no limit.
+<indexterm significance="preferred"><primary>PreeditDoneCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditdonecallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>PreeditDoneCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Not used for this callback and always passed as NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When preedit stops on the specified input context,
+the callback is called with a NULL call_data argument.
+The client can release the data allocated by
+<function><replaceable>PreeditStartCallback</replaceable></function>.
+</para>
+<para>
+<!-- .LP -->
+<function><replaceable>PreeditStartCallback</replaceable></function>
+should initialize appropriate data needed for
+displaying preedit information and for handling further 
+<function><replaceable>PreeditDrawCallback</replaceable></function>
+calls.
+Once
+<function><replaceable>PreeditStartCallback</replaceable></function>
+is called, it will not be called again before
+<function><replaceable>PreeditDoneCallback</replaceable></function>
+has been called.
+</para>
+</sect3>
+<sect3 id="Preedit_Draw_Callback">
+<title>Preedit Draw Callback</title>
+<!-- .XS -->
+<!-- (SN Preedit Draw Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This callback is triggered to draw and insert, delete or replace,
+preedit text in the preedit region.
+The preedit text may include unconverted input text such as Japanese Kana,
+converted text such as Japanese Kanji characters, or characters of both kinds.
+That string is either a multibyte or wide character string, 
+whose encoding matches the locale bound to the input context.
+The callback prototype
+is as follows:
+<indexterm significance="preferred"><primary>PreeditDrawCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditdrawcallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>PreeditDrawCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XIMPreeditDrawCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the preedit drawing information.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback is passed an 
+<structname>XIMPreeditDrawCallbackStruct</structname>
+structure in the call_data argument.
+The text member of this structure contains the text to be drawn.
+After the string has been drawn,
+the caret should be moved to the specified location.
+</para>
+<para>
+<!-- .LP -->
+The 
+<structname>XIMPreeditDrawCallbackStruct</structname>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMPreeditDrawCallbackStruct</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XIMPreeditDrawCallbackStruct {
+     int caret;     /* Cursor offset within preedit string */
+     int chg_first;     /* Starting change position */
+     int chg_length;     /* Length of the change in character count */
+     XIMText *text;
+} XIMPreeditDrawCallbackStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The client must keep updating a buffer of the preedit text
+and the callback arguments referring to indexes in that buffer.
+The call_data fields have specific meanings according to the operation,
+as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+To indicate text deletion, 
+the call_data member specifies a NULL text field.
+The text to be deleted is then the current text in the buffer 
+from position chg_first (starting at zero) on a character length
+of chg_length.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+When text is non-NULL,
+it indicates insertion or replacement of text in the buffer.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The chg_length member
+identifies the number of characters in the current preedit buffer
+that are affected by this call.
+A positive chg_length indicates that chg_length number of characters, starting
+at chg_first, must be deleted or must be replaced by text, whose length is
+specified in the
+<structname>XIMText</structname>
+structure.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A chg_length value of zero indicates that text must be inserted
+right at the position specified by chg_first.
+A value of zero for chg_first specifies the first character in the buffer.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+chg_length and chg_first combine to identify the modification required to
+the preedit buffer; beginning at chg_first, replace chg_length number of
+characters with the text in the supplied
+<structname>XIMText</structname>
+structure. For example, suppose the preedit buffer contains the string "ABCDE".
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<literallayout class="monospaced">
+<!-- .ft C -->
+Text:      A B C D E
+          ^ ^ ^ ^ ^ ^
+CharPos:  0 1 2 3 4 5
+<!-- .sp -->
+<!-- .ft P -->
+</literallayout>
+The CharPos in the diagram shows the location of the character position
+relative to the character.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the value of chg_first is 1 and the value of chg_length is 3, this
+says to replace 3 characters beginning at character position 1 with the
+string in the
+<structname>XIMText</structname>
+structure.
+Hence, <acronym>BCD</acronym> would be replaced by the value in the structure.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Though chg_length and chg_first are both signed integers they will
+never have a negative value.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The caret member
+identifies the character position before which the cursor should
+be placed - after modification to the preedit buffer has been completed.
+For example, if caret is zero, the cursor is at
+the beginning of the buffer.  If the caret is one, the cursor is between
+the first and second character.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMText</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i 3i -->
+typedef struct _XIMText {
+     unsigned short length;
+     XIMFeedback * feedback;
+     Bool encoding_is_wchar; 
+     union {
+          char * multi_byte;
+          wchar_t * wide_char;
+     } string; 
+} XIMText;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The text string passed is actually a structure specifying as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+The length member is the text length in characters.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The encoding_is_wchar member is a value that indicates 
+if the text string is encoded in wide character or multibyte format.
+The text string may be passed either as multibyte or as wide character;
+the input method controls in which form data is passed.
+The client's
+callback routine must be able to handle data passed in either form.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The string member is the text string.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The feedback member indicates rendering type for each character in the
+string member.
+If string is NULL (indicating that only highlighting of the existing
+preedit buffer should be updated), feedback points to length highlight
+elements that should be applied to the existing preedit buffer, beginning
+at chg_first.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The feedback member expresses the types of rendering feedback
+the callback should apply when drawing text.
+Rendering of the text to be drawn is specified either in generic ways
+(for example, primary, secondary) or in specific ways (reverse, underline).
+When generic indications are given,
+the client is free to choose the rendering style.
+It is necessary, however, that primary and secondary be mapped 
+to two distinct rendering styles.
+</para>
+<para>
+<!-- .LP -->
+If an input method wants to control display of the preedit string, an 
+input method can indicate the visibility hints using feedbacks in
+a specific way.
+The 
+<symbol>XIMVisibleToForward</symbol>,
+<symbol>XIMVisibleToBackword</symbol>,
+and
+<symbol>XIMVisibleToCenter</symbol>
+masks are exclusively used for these visibility hints.
+The 
+<symbol>XIMVisibleToForward</symbol>
+mask
+indicates that the preedit text is preferably displayed in the
+primary draw direction from the
+caret position in the preedit area forward.
+The 
+<symbol>XIMVisibleToBackword</symbol>
+mask
+indicates that the preedit text is preferably displayed from
+the caret position in the preedit area backward, relative to the primary
+draw direction.
+The 
+<symbol>XIMVisibleToCenter</symbol>
+mask
+indicates that the preedit text is preferably displayed with
+the caret position in the preedit area centered.
+</para>
+<para>
+<!-- .LP -->
+The insertion point of the preedit string could exist outside of
+the visible area when visibility hints are used.
+Only one of the 
+masks
+is valid for the entire preedit string, and only one character
+can hold one of these feedbacks for a given input context at one time.
+This feedback may be OR'ed together with another highlight (such as
+<symbol>XIMReverse</symbol>).
+Only the most recently set feedback is valid, and any previous
+feedback is automatically canceled.  This is a hint to the client, and
+the client is free to choose how to display the preedit string.
+</para>
+<para>
+<!-- .LP -->
+The feedback member also specifies how rendering of the text argument
+should be performed.
+If the feedback is NULL,
+the callback should apply the same feedback as is used for the surrounding
+characters in the preedit buffer; if chg_first is at a highlight boundary,
+the client can choose which of the two highlights to use.
+If feedback is not NULL, feedback specifies an array defining the
+rendering for each
+character of the string, and the length of the array is thus length.
+</para>
+<para>
+<!-- .LP -->
+If an input method wants to indicate that it is only updating the feedback of
+the preedit text without changing the content of it, 
+the
+<structname>XIMText</structname>
+structure will contain a NULL value for the string field,
+the number of characters affected (relative to chg_first)
+will be in the length field,
+and the feedback field will point to an array of 
+<type>XIMFeedback</type>.
+</para>
+<para>
+<!-- .LP -->
+Each element in the feedback array is a bitmask represented by a value of type
+<type>XIMFeedback</type>.
+The valid mask names are as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMReverse</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMUnderline</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMHighlight</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPrimary</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMSecondary</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMTertiary</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMVisibleToForward</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMVisibleToBackward</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMVisibleToCenter</primary></indexterm>
+<!-- .sM -->
+</para>
+<literallayout class="monospaced">
+typedef unsigned long XIMFeedback;
+
+#define     XIMReverse                     1L
+#define     XIMUnderline                   (1L&lt;&lt;1)
+#define     XIMHighlight                   (1L&lt;&lt;2)
+#define     XIMPrimary                     (1L&lt;&lt;5)*
+#define     XIMSecondary                   (1L&lt;&lt;6)*
+#define     XIMTertiary                    (1L&lt;&lt;7)*
+#define     XIMVisibleToForward            (1L&lt;&lt;8)
+#define     XIMVisibleToBackward           (1L&lt;&lt;9)
+#define     XIMVisibleToCenter               (1L&lt;&lt;10)
+
+*† The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorrectly defined in
+the R5 specification. The X Consortium’s X11R5 implementation correctly
+implemented the values for these highlights. The value of these highlights has
+been corrected in this specification to agree with the values in the
+Consortium’s X11R5 and X11R6 implementations.
+
+</literallayout>
+
+<para>
+<!-- .LP -->
+Characters drawn with the
+<symbol>XIMReverse</symbol>
+highlight should be drawn by swapping the foreground and background colors
+used to draw normal, unhighlighted characters.
+Characters drawn with the
+<symbol>XIMUnderline</symbol>
+highlight should be underlined.
+Characters drawn with the
+<symbol>XIMHighlight</symbol>,
+<symbol>XIMPrimary</symbol>,
+<symbol>XIMSecondary</symbol>,
+and
+<symbol>XIMTertiary</symbol>
+highlights should be drawn in some unique manner that must be different
+from
+<symbol>XIMReverse</symbol>
+and
+<symbol>XIMUnderline</symbol>.
+<!-- .FS \(dg -->
+The values for
+<symbol>XIMPrimary</symbol>,
+<symbol>XIMSecondary</symbol>,
+and
+<symbol>XIMTertiary</symbol>
+were incorrectly defined in the R5 specification.
+The X Consortium's X11R5
+implementation correctly implemented the values for these highlights.
+The value of these highlights has been corrected in this specification
+to agree with the values in the Consortium's X11R5 and X11R6 implementations.
+<!-- .FE -->
+</para>
+</sect3>
+<sect3 id="Preedit_Caret_Callback">
+<title>Preedit Caret Callback</title>
+<!-- .XS -->
+<!-- (SN Preedit Caret Callback -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An input method may have its own navigation keys to allow the user
+to move the text insertion point in the preedit area 
+(for example, to move backward or forward). 
+Consequently, input method needs to indicate to the client that it
+should move the text insertion point.
+It then calls the PreeditCaretCallback.
+<indexterm significance="preferred"><primary>PreeditCaretCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditcaretcallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>PreeditCaretCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XIMPreeditCaretCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the preedit caret information.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The input method will trigger PreeditCaretCallback
+to move the text insertion point during preedit.
+The call_data argument contains a pointer to an 
+<structname>XIMPreeditCaretCallbackStruct</structname>
+structure,
+which indicates where the caret should be moved.
+The callback must move the insertion point to its new location
+and return, in field position, the new offset value from the initial position.  
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XIMPreeditCaretCallbackStruct</structname>
+structure is defined as follows:
+<indexterm significance="preferred"><primary>XIMPreeditCaretCallbackStruct</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct _XIMPreeditCaretCallbackStruct {
+     int position;     /* Caret offset within preedit string */
+     XIMCaretDirection direction;     /* Caret moves direction */
+     XIMCaretStyle style;     /* Feedback of the caret */
+} XIMPreeditCaretCallbackStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<structname>XIMCaretStyle</structname>
+structure is defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XIMCaretStyle</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef enum {
+     XIMIsInvisible,     /* Disable caret feedback */ 
+     XIMIsPrimary,     /* <acronym>UI</acronym> defined caret feedback */
+     XIMIsSecondary,     /* <acronym>UI</acronym> defined caret feedback */
+} XIMCaretStyle;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<structname>XIMCaretDirection</structname>
+structure is defined as follows:
+<indexterm significance="preferred"><primary>XIMCaretDirection</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef enum {
+     XIMForwardChar, XIMBackwardChar,
+     XIMForwardWord, XIMBackwardWord,
+     XIMCaretUp, XIMCaretDown,
+     XIMNextLine, XIMPreviousLine,
+     XIMLineStart, XIMLineEnd, 
+     XIMAbsolutePosition,
+     XIMDontChange,
+ } XIMCaretDirection;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+These values are defined as follows:
+</para>
+<indexterm significance="preferred"><primary>XIMForwardChar</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMBackwardChar</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMForwardWord</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMBackwardWord</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMCaretUp</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMCaretDown</primary></indexterm>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><constant>XIMForwardChar</constant></entry>
+      <entry>Move the caret forward one character position.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMBackwardChar</constant></entry>
+      <entry>Move the caret backward one character position.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMForwardWord</constant></entry>
+      <entry>Move the caret forward one word.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMBackwardWord</constant></entry>
+      <entry>Move the caret backward one word.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMCaretUp</constant></entry>
+      <entry>Move the caret up one line keeping the current horizontal offset.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMCaretDown</constant></entry>
+      <entry>Move the caret down one line keeping the current horizontal offset.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMPreviousLine</constant></entry>
+      <entry>Move the caret to the beginning of the previous line.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMNextLine</constant></entry>
+      <entry>Move the caret to the beginning of the next line.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMLineStart</constant></entry>
+      <entry>Move the caret to the beginning of the current display line that contains the caret.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMLineEnd</constant></entry>
+      <entry>Move the caret to the end of the current display line that contains the caret.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMAbsolutePosition</constant></entry>
+      <entry>The callback must move to the location specified by the position field
+      of the callback data, indicated in characters, starting from the beginning
+      of the preedit text.
+      Hence, a value of zero means move back to the beginning of the preedit text.</entry>
+    </row>
+    <row>
+      <entry><constant>XIMDontChange</constant></entry>
+      <entry>The caret position does not change.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<indexterm significance="preferred"><primary>XIMNextLine</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMPreviousLine</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMLineStart</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMLineEnd</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMAbsolutePosition</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMDontChange</primary></indexterm>
+</sect3>
+<sect3 id="Status_Callbacks">
+<title>Status Callbacks</title>
+<!-- .XS -->
+<!-- (SN Status Callbacks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An input method may communicate changes in the status of an input context
+(for example, created, destroyed, or focus changes) with three status
+callbacks:  StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+When the input context is created or gains focus, 
+the input method calls the StatusStartCallback callback.
+<indexterm significance="preferred"><primary>StatusStartCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='statusstartcallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>StatusStartCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Not used for this callback and always passed as NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback should initialize appropriate data for displaying status
+and for responding to StatusDrawCallback calls.  
+Once StatusStartCallback is called,
+it will not be called again before StatusDoneCallback has been called.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+When an input context
+is destroyed or when it loses focus, the input method calls StatusDoneCallback.
+<indexterm significance="preferred"><primary>StatusDoneCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='statusdonecallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>StatusDoneCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Not used for this callback and always passed as NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback may release any data allocated on 
+<function>StatusStart</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+When an input context status has to be updated, the input method calls
+StatusDrawCallback.
+<indexterm significance="preferred"><primary>StatusDrawCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='statusdrawcallback'>
+<funcprototype>
+  <funcdef>void <function><replaceable>StatusDrawCallback</replaceable></function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+  <paramdef>XIMStatusDrawCallbackStruct<parameter> *call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>client_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the additional client data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>call_data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the status drawing information.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The callback should update the status area by either drawing a string
+or imaging a bitmap in the status area.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XIMStatusDataType</structname>
+and
+<structname>XIMStatusDrawCallbackStruct</structname>
+structures are defined as follows:
+<indexterm significance="preferred"><primary>XIMStatusDataType</primary></indexterm>
+<indexterm significance="preferred"><primary>XIMStatusDrawCallbackStruct</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 3i -->
+<!-- .ta .5i 1i 3i -->
+typedef enum {
+     XIMTextType,
+     XIMBitmapType,
+} XIMStatusDataType;
+
+typedef struct _XIMStatusDrawCallbackStruct {
+     XIMStatusDataType type;
+     union {
+          XIMText *text;
+          Pixmap  bitmap;
+     } data;
+} XIMStatusDrawCallbackStruct;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+<para>
+<!-- .LP -->
+The feedback styles
+<symbol>XIMVisibleToForward</symbol>,
+<symbol>XIMVisibleToBackword</symbol>,
+and
+<symbol>XIMVisibleToCenter</symbol>
+are not relevant and will not appear in the
+<type>XIMFeedback</type>
+element of the
+<structname>XIMText</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect3>
+</sect2>
+<sect2 id="Event_Filtering_b">
+<title>Event Filtering</title>
+<!-- .XS -->
+<!-- (SN Event Filtering -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides the ability for an input method
+to register a filter internal to Xlib.
+This filter is called by a client (or toolkit) by calling
+<function>XFilterEvent</function>
+after calling 
+<function>XNextEvent</function>.
+Any client that uses the 
+<type>XIM</type>
+interface should call
+<function>XFilterEvent</function>
+to allow input methods to process their events without knowledge
+of the client's dispatching mechanism.
+A client's user interface policy may determine the priority
+of event filters with respect to other event-handling mechanisms
+(for example, modal grabs).
+</para>
+<para>
+<!-- .LP -->
+Clients may not know how many filters there are, if any,
+and what they do.
+They may only know if an event has been filtered on return of 
+<function>XFilterEvent</function>.
+Clients should discard filtered events.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To filter an event, use
+<function>XFilterEvent</function>.
+<indexterm significance="preferred"><primary>XFilterEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfilterevent'>
+<funcprototype>
+  <funcdef>Bool <function>XFilterEvent</function></funcdef>
+  <paramdef>XEvent<parameter> *event</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ev event to filter -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the (Ev.
+<!-- .ds Wi for which the filter is to be applied -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the window argument is
+<symbol>None</symbol>,
+<function>XFilterEvent</function>
+applies the filter to the window specified in the
+<structname>XEvent</structname>
+structure.
+The window argument is provided so that layers above Xlib
+that do event redirection can indicate to which window an event
+has been redirected.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XFilterEvent</function>
+returns
+<symbol>True</symbol>,
+then some input method has filtered the event,
+and the client should discard the event.
+If
+<function>XFilterEvent</function>
+returns
+<symbol>False</symbol>,
+then the client should continue processing the event.
+</para>
+<para>
+<!-- .LP -->
+If a grab has occurred in the client and
+<function>XFilterEvent</function>
+returns
+<symbol>True</symbol>,
+the client should ungrab the keyboard.
+</para>
+</sect2>
+<sect2 id="Getting_Keyboard_Input_b">
+<title>Getting Keyboard Input</title>
+<!-- .XS -->
+<!-- (SN Getting Keyboard Input -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To get composed input from an input method,
+use
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>.
+<indexterm significance="preferred"><primary>XmbLookupString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcLookupString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmblookupstring'>
+<funcprototype>
+  <funcdef>int <function>XmbLookupString</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>
+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+  <paramdef>int<parameter> bytes_buffer</parameter></paramdef>
+  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
+  <paramdef>Status<parameter> *status_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwclookupstring'>
+<funcprototype>
+  <funcdef>int <function>XwcLookupString</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+  <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>
+  <paramdef>wchar_t<parameter> *buffer_return</parameter></paramdef>
+  <paramdef>int<parameter> wchars_buffer</parameter></paramdef>
+  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
+  <paramdef>Status<parameter> *status_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ic</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the input context.
+<!-- .ds Ev key event to be used -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the (Ev.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buffer_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a multibyte string or wide character string (if any)
+from the input method.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bytes_buffer</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>wchars_buffer</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies space available in the return buffer.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the KeySym computed from the event if this argument is not NULL.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>status_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a value indicating what kind of data is returned.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+functions return the string from the input method specified
+in the buffer_return argument.
+If no string is returned,
+the buffer_return argument is unchanged.
+</para>
+<para>
+<!-- .LP -->
+The KeySym into which the KeyCode from the event was mapped is returned
+in the keysym_return argument if it is non-NULL and the status_return
+argument indicates that a KeySym was returned.
+If both a string and a KeySym are returned,
+the KeySym value does not necessarily correspond to the string returned.
+</para>
+<para>
+<!-- .LP -->
+<function>XmbLookupString</function>
+returns the length of the string in bytes, and
+<function>XwcLookupString</function>
+returns the length of the string in characters.
+Both
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+return text in the encoding of the locale bound to the input method
+of the specified input context.
+</para>
+<para>
+<!-- .LP -->
+Each string returned by
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+begins in the initial state of the encoding of the locale
+(if the encoding of the locale is state-dependent).
+<!-- .NT -->
+<note><para>
+To insure proper input processing,
+it is essential that the client pass only 
+<symbol>KeyPress</symbol>
+events to
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>.
+Their behavior when a client passes a 
+<symbol>KeyRelease</symbol>
+event is undefined.
+</para></note>
+<!-- .NE -->
+</para>
+<para>
+<!-- .LP -->
+Clients should check the status_return argument before
+using the other returned values.
+These two functions both return a value to status_return 
+that indicates what has been returned in the other arguments.
+The possible values returned are:
+</para>
+
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <tbody>
+    <row>
+      <entry><symbol>XBufferOverflow</symbol></entry>
+      <entry>The input string to be returned is too large for the supplied buffer_return.
+      The required size
+      (<function>XmbLookupString</function>
+      in bytes;
+      <function>XwcLookupString</function>
+      in characters) is returned as the value of the function,
+      and the contents of buffer_return and keysym_return are not modified.
+      The client should recall the function with the same event
+      and a buffer of adequate size to obtain the string.</entry>
+    </row>
+    <row>
+      <entry><symbol>XLookupNone</symbol></entry>
+      <entry>No consistent input has been composed so far.
+      The contents of buffer_return and keysym_return are not modified, 
+      and the function returns zero.</entry>
+    </row>
+    <row>
+      <entry><symbol>XLookupChars</symbol></entry>
+      <entry>Some input characters have been composed.
+      They are placed in the buffer_return argument,
+      and the string length is returned as the value of the function.
+      The string is encoded in the locale bound to the input context.
+      The content of the keysym_return argument is not modified.</entry>
+    </row>
+    <row>
+      <entry><symbol>XLookupKeySym</symbol></entry>
+      <entry>A KeySym has been returned instead of a string
+      and is returned in keysym_return.
+      The content of the buffer_return argument is not modified,
+      and the function returns zero.</entry>
+    </row>
+    <row>
+      <entry><symbol>XLookupBoth</symbol></entry>
+      <entry>Both a KeySym and a string are returned;
+      <symbol>XLookupChars</symbol>
+      and
+      <symbol>XLookupKeySym</symbol>
+      occur simultaneously.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+It does not make any difference if the input context passed as an argument to
+<function>XmbLookupString</function>
+and
+<function>XwcLookupString</function>
+is the one currently in possession of the focus or not.
+Input may have been composed within an input context before it lost the focus,
+and that input may be returned on subsequent calls to
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>
+even though it does not have any more keyboard focus.
+</para>
+</sect2>
+<sect2 id="Input_Method_Conventions">
+<title>Input Method Conventions</title>
+<!-- .XS -->
+<!-- (SN Input Method Conventions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The input method architecture is transparent to the client.
+However, clients should respect a number of conventions in order
+to work properly.
+Clients must also be aware of possible effects of synchronization
+between input method and library in the case of a remote input server.
+</para>
+<sect3 id="Client_Conventions">
+<title>Client Conventions</title>
+<!-- .XS -->
+<!-- (SN Client Conventions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A well-behaved client (or toolkit) should first query the input method style.
+If the client cannot satisfy the requirements of the supported styles
+(in terms of geometry management or callbacks),
+it should negotiate with the user continuation of the program
+or raise an exception or error of some sort.
+</para>
+</sect3>
+<sect3 id="Synchronization_Conventions">
+<title>Synchronization Conventions</title>
+<!-- .XS -->
+<!-- (SN Synchronization Conventions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A 
+<symbol>KeyPress</symbol>
+event with a KeyCode of zero is used exclusively as a
+signal that an input method has composed input that can be returned by
+<function>XmbLookupString</function>
+or
+<function>XwcLookupString</function>.
+No other use is made of a 
+<symbol>KeyPress</symbol>
+event with KeyCode of zero.
+</para>
+<para>
+<!-- .LP -->
+Such an event may be generated by either a front-end
+or a back-end input method in an implementation-dependent manner.
+Some possible ways to generate this event include:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+A synthetic event sent by an input method server
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+An artificial event created by a input method filter and pushed
+onto a client's event queue
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A 
+<symbol>KeyPress</symbol>
+event whose KeyCode value is modified by an input method filter
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+When callback support is specified by the client,
+input methods will not take action unless they explicitly
+called back the client and obtained no response
+(the callback is not specified or returned invalid data).
+</para>
+</sect3>
+</sect2>
+</sect1>
+<sect1 id="String_Constants">
+<title>String Constants</title>
+<!-- .XS -->
+<!-- (SN String Constants -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following symbols for string constants are defined in
+&lt;X11/Xlib.h&gt; .
+Although they are shown here with particular macro definitions,
+they may be implemented as macros, as global symbols, or as a
+mixture of the two.  The string pointer value itself
+is not significant; clients must not assume that inequality of two
+values implies inequality of the actual string data.
+</para>
+
+<literallayout class="monospaced">
+#define XNVaNestedList                       "XNVaNestedList"
+#define XNSeparatorofNestedList              "separatorofNestedList"
+#define XNQueryInputStyle                    "queryInputStyle"
+#define XNClientWindow                       "clientWindow"
+#define XNInputStyle                         "inputStyle"
+#define XNFocusWindow                        "focusWindow"
+#define XNResourceName                       "resourceName"
+#define XNResourceClass                      "resourceClass"
+#define XNGeometryCallback                   "geometryCallback"
+#define XNDestroyCallback                    "destroyCallback"
+#define XNFilterEvents                       "filterEvents"
+#define XNPreeditStartCallback               "preeditStartCallback"
+#define XNPreeditDoneCallback                "preeditDoneCallback"
+#define XNPreeditDrawCallback                "preeditDrawCallback"
+#define XNPreeditCaretCallback               "preeditCaretCallback"
+#define XNPreeditStateNotifyCallback         "preeditStateNotifyCallback"
+#define XNPreeditAttributes                  "preeditAttributes"
+#define XNStatusStartCallback                "statusStartCallback"
+#define XNStatusDoneCallback                 "statusDoneCallback"
+#define XNStatusDrawCallback                 "statusDrawCallback"
+#define XNStatusAttributes                   "statusAttributes"
+#define XNArea                               "area"
+#define XNAreaNeeded                         "areaNeeded"
+#define XNSpotLocation                       "spotLocation"
+#define XNColormap                           "colorMap"
+#define XNStdColormap                        "stdColorMap"
+#define XNForeground                         "foreground"
+#define XNBackground                         "background"
+#define XNBackgroundPixmap                   "backgroundPixmap"
+#define XNFontSet                            "fontSet"
+#define XNLineSpace                          "lineSpace"
+#define XNCursor                             "cursor"
+#define XNQueryIMValuesList                  "queryIMValuesList"
+#define XNQueryICValuesList                  "queryICValuesList"
+#define XNStringConversionCallback           "stringConversionCallback"
+#define XNStringConversion                   "stringConversion"
+#define XNResetState                         "resetState"
+#define XNHotKey                             "hotkey"
+#define XNHotKeyState                        "hotkeyState"
+#define XNPreeditState                       "preeditState"
+#define XNVisiblePosition                    "visiblePosition"
+#define XNR6PreeditCallbackBehavior          "r6PreeditCallback"
+#define XNRequiredCharSet                    "requiredCharSet"
+#define XNQueryOrientation                   "queryOrientation"
+#define XNDirectionalDependentDrawing        "directionalDependentDrawing"
+#define XNContextualDrawing                  "contextualDrawing"
+#define XNBaseFontName                       "baseFontName"
+#define XNMissingCharSet                     "missingCharSet"
+#define XNDefaultString                      "defaultString"
+#define XNOrientation                        "orientation"
+#define XNFontInfo                           "fontInfo"
+#define XNOMAutomatic                        "omAutomatic"
+
+</literallayout>
+
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH14.xml b/libX11/specs/libX11/CH14.xml
index 2baf6d5bf..d0eb36f10 100644
--- a/libX11/specs/libX11/CH14.xml
+++ b/libX11/specs/libX11/CH14.xml
@@ -1,5206 +1,5206 @@
-<?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="inter_client_communication_functions">

-<title>Inter-Client Communication Functions</title>

-<para>

-The Inter-Client Communication Conventions Manual, hereafter referred to as the <acronym>ICCCM</acronym>,

-details the X Consortium approved conventions that govern inter-client communications. These

-conventions ensure peer-to-peer client cooperation in the use of selections, cut buffers, and shared

-resources as well as client cooperation with window and session managers. For further information,

-see the Inter-Client Communication Conventions Manual.

-</para>

-<para>

-Xlib provides a number of standard properties and programming interfaces that are <acronym>ICCCM</acronym>

-compliant. The predefined atoms for some of these properties are defined in the &lt;X11/Xatom.h&gt;

-header file, where to avoid name conflicts with user symbols their #define name has an XA_ prefix.

-For further information about atoms and properties, see section 4.3.

-</para>

-<para>

-Xlib’s selection and cut buffer mechanisms provide the primary programming interfaces by which

-peer client applications communicate with each other (see sections 4.5 and 16.6). The functions

-discussed in this chapter provide the primary programming interfaces by which client applications

-communicate with their window and session managers as well as share standard colormaps.

-</para>

-<para>

-The standard properties that are of special interest for communicating with window and session

-managers are:

-</para>

-

-<informaltable>

-  <tgroup cols='4' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <colspec colname='c4'/>

-  <thead>

-    <row>

-      <entry>Name</entry>

-      <entry>Type</entry>

-      <entry>Format</entry>

-      <entry>Description</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry><property>WM_CLASS</property></entry>

-      <entry>STRING</entry>

-      <entry>8</entry>

-      <entry>Set by application programs to allow

-      window and session managers to

-      obtain the application’s resources

-      from the resource database.

-      </entry>

-    </row>

-    <row>

-      <entry><property>WM_CLIENT_MACHINE</property></entry>

-      <entry>TEXT</entry>

-      <entry></entry>

-      <entry>The string name of the machine on

-      which the client application is running.

-      </entry>

-    </row>

-    <row>

-      <entry><property>WM_COLORMAP_WINDOWS</property></entry>

-      <entry>WINDOWS</entry>

-      <entry>32</entry>

-      <entry>The list of window IDs that may

-      need a different colormap from that

-      of their top-level window.

-      </entry>

-    </row>

-    <row>

-      <entry><property>WM_COMMAND</property></entry>

-      <entry>TEXT</entry>

-      <entry></entry>

-      <entry>The command and arguments, null

-      separated, used to invoke the application.

-      </entry>

-    </row>

-    <row>

-      <entry><property>WM_HINTS</property></entry>

-      <entry><property>WM_HINTS</property></entry>

-      <entry>32</entry>

-      <entry>Additional hints set by the client for

-      use by the window manager. The C

-      type of this property is XWMHints.

-      </entry> 

-    </row>

-    <row>

-      <entry><property>WM_ICON_NAME</property></entry>

-      <entry>TEXT</entry>

-      <entry></entry>

-      <entry>The name to be used in an icon.</entry>

-    </row>

-    <row>

-      <entry><property>WM_ICON_SIZE</property></entry>

-      <entry><property>WM_ICON_SIZE</property></entry>

-      <entry>32</entry>

-      <entry>The window manager may set this

-      property on the root window to

-      specify the icon sizes it supports.

-      The C type of this property is

-      XIconSize.

-      </entry>

-    </row>

-    <row>

-      <entry><property>WM_NAME</property></entry>

-      <entry>TEXT</entry>

-      <entry></entry>

-      <entry>The name of the application.</entry>

-    </row>

-    <row>

-      <entry><property>WM_NORMAL_HINTS</property></entry>

-      <entry><property>WM_NORMAL_HINTS</property></entry>

-      <entry>32</entry>

-      <entry>Size hints for a window in its

-      normal state. The C type of this

-      property is XSizeHints.

-      </entry>

-    </row>

-    <row>

-      <entry><property>WM_PROTOCOLS</property></entry>

-      <entry>ATOM</entry>

-      <entry>32</entry>

-      <entry>List of atoms that identify the 

-      communications protocols between the

-      client and window manager in

-      which the client is willing to participate.

-      </entry>

-    </row>

-    <row>

-      <entry><property>WM_STATE</property></entry>

-      <entry><property>WM_STATE</property></entry>

-      <entry>32</entry>

-      <entry>Intended for communication

-      between window and session managers only.

-      </entry>

-    </row>

-    <row>

-      <entry><property>WM_TRANSIENT_FOR</property></entry>

-      <entry>WINDOW</entry>

-      <entry>32</entry>

-      <entry>Set by application programs to 

-      indicate to the window manager that a

-      transient top-level window, such as a

-      dialog box.

-      </entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para>

-The remainder of this chapter discusses:

-</para>

-

-<itemizedlist>

-  <listitem><para>Client to window manager communication</para></listitem>

-  <listitem><para>Client to session manager communication</para></listitem>

-  <listitem><para>Standard colormaps</para></listitem>

-</itemizedlist>

-

-<sect1 id="Client_to_Window_Manager_Communication">

-<title>Client to Window Manager Communication</title>

-<!-- .XS -->

-<!-- (SN Client to Window Manager Communication -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section discusses how to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Manipulate top-level windows

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Convert string lists

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read text properties

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_NAME</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_ICON_NAME</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_HINTS</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_NORMAL_HINTS</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_CLASS</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_TRANSIENT_FOR</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_PROTOCOLS</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_COLORMAP_WINDOWS</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_ICON_SIZE</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Use window manager convenience functions

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Manipulating_Top_Level_Windows">

-<title>Manipulating Top-Level Windows</title>

-<!-- .XS -->

-<!-- (SN Manipulating Top-Level Windows -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to change the visibility or size

-of top-level windows (that is, those that were created as children 

-of the root window).

-Note that the subwindows that you create are ignored by window managers.

-Therefore,

-you should use the basic window functions described in chapter 3

-to manipulate your application's subwindows.

-</para>

-<para>

-<!-- .LP -->

-To request that a top-level window be iconified, use

-<function>XIconifyWindow</function>.

-<indexterm significance="preferred"><primary>XIconifyWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XIconifyWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> screen_number</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the appropriate screen number on the host server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XIconifyWindow</function>

-function sends a <property>WM_CHANGE_STATE</property> 

-<symbol>ClientMessage</symbol>

-event with a format of 32 and a first data element of 

-<symbol>IconicState</symbol>

-(as described in section 4.1.4 of the 

-<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>)

-and a window of w

-to the root window of the specified screen

-with an event mask set to

-<symbol>SubstructureNotifyMask</symbol> |

-<symbol>SubstructureRedirectMask</symbol>.

-Window managers may elect to receive this message and

-if the window is in its normal state, 

-may treat it as a request to change the window's state from normal to iconic.

-If the <property>WM_CHANGE_STATE</property> property cannot be interned, 

-<function>XIconifyWindow</function>

-does not send a message and returns a zero status.

-It returns a nonzero status if the client message is sent successfully;

-otherwise, it returns a zero status.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To request that a top-level window be withdrawn, use

-<function>XWithdrawWindow</function>.

-<indexterm significance="preferred"><primary>XWithdrawWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XWithdrawWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> screen_number</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the appropriate screen number on the host server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XWithdrawWindow</function>

-function unmaps the specified window 

-and sends a synthetic 

-<symbol>UnmapNotify</symbol>

-event to the root window of the specified screen.

-Window managers may elect to receive this message 

-and may treat it as a request to change the window's state to withdrawn.

-When a window is in the withdrawn state, 

-neither its normal nor its iconic representations is visible.

-It returns a nonzero status if the 

-<symbol>UnmapNotify</symbol>

-event is successfully sent; 

-otherwise, it returns a zero status.

-</para>

-<para>

-<!-- .LP -->

-<function>XWithdrawWindow</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To request that a top-level window be reconfigured, use

-<function>XReconfigureWMWindow</function>.

-<indexterm significance="preferred"><primary>XReconfigureWMWindow</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XReconfigureWMWindow</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> screen_number</parameter></paramdef>

-  <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>

-  <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen_number</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the appropriate screen number on the host server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies which values are to be set using information in

-the values structure.

-This mask is the bitwise inclusive OR of the valid configure window values bits.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>values</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XWindowChanges</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XReconfigureWMWindow</function>

-function issues a 

-<systemitem>ConfigureWindow</systemitem>

-request on the specified top-level window.

-If the stacking mode is changed and the request fails with a 

-<errorname>BadMatch</errorname>

-error, 

-the error is trapped by Xlib and a synthetic 

-<systemitem class="event">ConfigureRequestEvent</systemitem>

-containing the same configuration parameters is sent to the root 

-of the specified window.

-Window managers may elect to receive this event 

-and treat it as a request to reconfigure the indicated window.

-It returns a nonzero status if the request or event is successfully sent;

-otherwise, it returns a zero status.

-</para>

-<para>

-<!-- .LP -->

-<function>XReconfigureWMWindow</function>

-can generate

-<errorname>BadValue</errorname>

-and 

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Converting_String_Lists">

-<title>Converting String Lists</title>

-<!-- .XS -->

-<!-- (SN Converting String Lists -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Many of the text properties allow a variety of types and formats.

-Because the data stored in these properties are not

-simple null-terminated strings, an

-<structname>XTextProperty</structname>

-structure is used to describe the encoding, type, and length of the text 

-as well as its value.

-The

-<structname>XTextProperty</structname>

-structure contains:

-<indexterm significance="preferred"><primary>XTextProperty</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	unsigned char *value;	/* property data */

-	Atom encoding;	/* type of property */

-	int format;	/* 8, 16, or 32 */

-	unsigned long nitems;	/* number of items in value */

-} XTextProperty;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Xlib provides functions to convert localized text to or from encodings

-that support the inter-client communication conventions for text.

-In addition, functions are provided for converting between lists of pointers 

-to character strings and text properties in the STRING encoding.

-</para>

-<para>

-<!-- .LP -->

-The functions for localized text return a signed integer error status 

-that encodes 

-<symbol>Success</symbol>

-as zero, specific error conditions as negative numbers, and partial conversion

-as a count of unconvertible characters.

-</para>

-

-<literallayout class="monospaced">

-

-#define #XNoMemory           -1

-#define #XLocaleNotSupported -2

-#define #XConverterNotFound  -3

-

-typedef enum {

-	XStringStyle,		/* STRING */

-	XCompoundTextStyle,	/* COMPOUND_TEXT */

-	XTextStyle,		/* text in owner's encoding (current locale) */

-	XStdICCTextStyle	/* STRING, else COMPOUND_TEXT */

-} XICCEncodingStyle;

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To convert a list of text strings to an 

-<structname>XTextProperty</structname>

-structure, use

-<function>XmbTextListToTextProperty</function>

-or

-<function>XwcTextListToTextProperty</function>.

-<indexterm significance="preferred"><primary>XmbTextListToTextProperty</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcTextListToTextProperty</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XmbTextListToTextProperty</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> **list</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-  <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XwcTextListToTextProperty</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>wchar_t<parameter> **list</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-  <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a list of null-terminated character strings.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of strings specified.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>style</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the manner in which the property is encoded.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the

-<structname>XTextProperty</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbTextListToTextProperty</function>

-and

-<function>XwcTextListToTextProperty</function>

-functions set the specified 

-<structname>XTextProperty</structname>

-value to a set of null-separated elements representing the concatenation

-of the specified list of null-terminated text strings.

-A final terminating null is stored at the end of the value field 

-of text_prop_return but is not included in the nitems member.

-</para>

-<para>

-<!-- .LP -->

-The functions set the encoding field of text_prop_return to an

-<type>Atom</type>

-for the specified display 

-naming the encoding determined by the specified style

-and convert the specified text list to this encoding for storage in

-the text_prop_return value field.

-If the style 

-<constant>XStringStyle</constant>

-or 

-<constant>XCompoundTextStyle</constant>

-is specified,

-this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.

-If the style 

-<constant>XTextStyle</constant>

-is specified,

-this encoding is the encoding of the current locale.

-If the style 

-<constant>XStdICCTextStyle</constant>

-is specified,

-this encoding is ``STRING'' if the text is fully convertible to STRING,

-else ``COMPOUND_TEXT''.

-</para>

-<para>

-<!-- .LP -->

-If insufficient memory is available for the new value string,

-the functions return 

-<symbol>XNoMemory</symbol>.

-If the current locale is not supported,

-the functions return 

-<symbol>XLocaleNotSupported</symbol>.

-In both of these error cases,

-the functions do not set text_prop_return.

-</para>

-<para>

-<!-- .LP -->

-To determine if the functions are guaranteed not to return

-<symbol>XLocaleNotSupported</symbol>,

-use

-<function>XSupportsLocale</function>.

-</para>

-<para>

-<!-- .LP -->

-If the supplied text is not fully convertible to the specified encoding,

-the functions return the number of unconvertible characters.

-Each unconvertible character is converted to an implementation-defined and

-encoding-specific default string.

-Otherwise, the functions return 

-<symbol>Success</symbol>.

-Note that full convertibility to all styles except 

-<constant>XStringStyle</constant>

-is guaranteed.

-</para>

-<para>

-<!-- .LP -->

-To free the storage for the value field, use

-<function>XFree</function>.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain a list of text strings from an 

-<structname>XTextProperty</structname>

-structure, use

-<function>XmbTextPropertyToTextList</function>

-or

-<function>XwcTextPropertyToTextList</function>.

-<indexterm significance="preferred"><primary>XmbTextPropertyToTextList</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcTextPropertyToTextList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XmbTextPropertyToTextList</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

-  <paramdef>char<parameter> ***list_return</parameter></paramdef>

-  <paramdef>int<parameter> *count_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XwcTextPropertyToTextList</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

-  <paramdef>wchar_t<parameter> ***list_return</parameter></paramdef>

-  <paramdef>int<parameter> *count_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XTextProperty</structname>

-structure to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a list of null-terminated character strings.

-<!-- .ds Cn strings -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of (Cn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XmbTextPropertyToTextList</function>

-and 

-<function>XwcTextPropertyToTextList</function>

-functions return a list of text strings in the current locale representing the

-null-separated elements of the specified

-<structname>XTextProperty</structname>

-structure.

-The data in text_prop must be format 8.

-</para>

-<para>

-<!-- .LP -->

-Multiple elements of the property (for example, the strings in a disjoint

-text selection) are separated by a null byte.

-The contents of the property are not required to be null-terminated;

-any terminating null should not be included in text_prop.nitems.

-</para>

-<para>

-<!-- .LP -->

-If insufficient memory is available for the list and its elements,

-<function>XmbTextPropertyToTextList</function>

-and

-<function>XwcTextPropertyToTextList</function>

-return 

-<symbol>XNoMemory</symbol>.

-If the current locale is not supported,

-the functions return

-<symbol>XLocaleNotSupported</symbol>.

-Otherwise, if the encoding field of text_prop is not convertible 

-to the encoding of the current locale,

-the functions return

-<symbol>XConverterNotFound</symbol>.

-For supported locales,

-existence of a converter from COMPOUND_TEXT, STRING

-or the encoding of the current locale is guaranteed if

-<function>XSupportsLocale</function>

-returns 

-<symbol>True</symbol>

-for the current locale (but the actual text

-may contain unconvertible characters).

-Conversion of other encodings is implementation-dependent.

-In all of these error cases,

-the functions do not set any return values.

-</para>

-<para>

-<!-- .LP -->

-Otherwise, 

-<function>XmbTextPropertyToTextList</function>

-and

-<function>XwcTextPropertyToTextList</function>

-return the list of null-terminated text strings to list_return

-and the number of text strings to count_return.

-</para>

-<para>

-<!-- .LP -->

-If the value field of text_prop is not fully convertible to the encoding of

-the current locale,

-the functions return the number of unconvertible characters.

-Each unconvertible character is converted to a string in the

-current locale that is specific to the current locale.

-To obtain the value of this string, 

-use

-<function>XDefaultString</function>.

-Otherwise,

-<function>XmbTextPropertyToTextList</function>

-and

-<function>XwcTextPropertyToTextList</function>

-return 

-<symbol>Success</symbol>.

-</para>

-<para>

-<!-- .LP -->

-To free the storage for the list and its contents returned by

-<function>XmbTextPropertyToTextList</function>,

-use

-<function>XFreeStringList</function>.

-To free the storage for the list and its contents returned by

-<function>XwcTextPropertyToTextList</function>,

-use

-<function>XwcFreeStringList</function>.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To free the in-memory data associated with the specified

-wide character string list, use

-<function>XwcFreeStringList</function>.

-<indexterm significance="preferred"><primary>XwcFreeStringList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XwcFreeStringList</function></funcdef>

-  <paramdef>wchar_t<parameter> **list</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the list of strings to be freed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XwcFreeStringList</function>

-function frees memory allocated by

-<function>XwcTextPropertyToTextList</function>.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the default string for text conversion in the current locale,

-use</para>

-

-<para>char *XDefaultString()</para>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDefaultString</function>

-function returns the default string used by Xlib for text conversion

-(for example, in 

-<function>XmbTextPropertyToTextList</function>).

-The default string is the string in the current locale that is output 

-when an unconvertible character is found during text conversion.

-If the string returned by

-<function>XDefaultString</function>

-is the empty string (""),

-no character is output in the converted text.

-<function>XDefaultString</function>

-does not return NULL.

-</para>

-<para>

-<!-- .LP -->

-The string returned by 

-<function>XDefaultString</function>

-is independent of the default string for text drawing;

-see 

-<function>XCreateFontSet</function>

-to obtain the default string for an

-<type>XFontSet</type>.

-</para>

-<para>

-<!-- .LP -->

-The behavior when an invalid codepoint is supplied to any Xlib function is

-undefined.

-</para>

-<para>

-<!-- .LP -->

-The returned string is null-terminated.

-It is owned by Xlib and should not be modified or freed by the client.

-It may be freed after the current locale is changed.

-Until freed, it will not be modified by Xlib.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set the specified list of strings in the STRING encoding to a 

-<structname>XTextProperty</structname>

-structure, use

-<function>XStringListToTextProperty</function>.

-<indexterm significance="preferred"><primary>XStringListToTextProperty</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XStringListToTextProperty</function></funcdef>

-  <paramdef>char<parameter> **list</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a list of null-terminated character strings.

-<!-- .ds Cn strings -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of (Cn.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the

-<structname>XTextProperty</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XStringListToTextProperty</function>

-function sets the specified 

-<structname>XTextProperty</structname>

-to be of type STRING (format 8) with a value representing the

-concatenation of the specified list of null-separated character strings.

-An extra null byte (which is not included in the nitems member) 

-is stored at the end of the value field of text_prop_return.

-The strings are assumed (without verification) to be in the STRING encoding.

-If insufficient memory is available for the new value string, 

-<function>XStringListToTextProperty</function>

-does not set any fields in the

-<structname>XTextProperty</structname>

-structure and returns a zero status.

-Otherwise, it returns a nonzero status.

-To free the storage for the value field, use 

-<function>XFree</function>.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain a list of strings from a specified

-<structname>XTextProperty</structname>

-structure in the STRING encoding, use

-<function>XTextPropertyToStringList</function>.

-<indexterm significance="preferred"><primary>XTextPropertyToStringList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XTextPropertyToStringList</function></funcdef>

-  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

-  <paramdef>char<parameter> ***list_return</parameter></paramdef>

-  <paramdef>int<parameter> *count_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XTextProperty</structname>

-structure to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a list of null-terminated character strings.

-<!-- .ds Cn strings -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of (Cn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XTextPropertyToStringList</function>

-function returns a list of strings representing the null-separated elements 

-of the specified

-<structname>XTextProperty</structname>

-structure.

-The data in text_prop must be of type STRING and format 8. 

-Multiple elements of the property 

-(for example, the strings in a disjoint text selection) 

-are separated by NULL (encoding 0).

-The contents of the property are not null-terminated.

-If insufficient memory is available for the list and its elements, 

-<function>XTextPropertyToStringList</function>

-sets no return values and returns a zero status.

-Otherwise, it returns a nonzero status.

-To free the storage for the list and its contents, use 

-<function>XFreeStringList</function>.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To free the in-memory data associated with the specified string list, use

-<function>XFreeStringList</function>.

-<indexterm significance="preferred"><primary>XFreeStringList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XFreeStringList</function></funcdef>

-  <paramdef>char<parameter> **list</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the list of strings to be freed.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XFreeStringList</function>

-function releases memory allocated by 

-<function>XmbTextPropertyToTextList</function>

-and

-<function>XTextPropertyToStringList</function>

-and the missing charset list allocated by 

-<function>XCreateFontSet</function>.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_Text_Properties">

-<title>Setting and Reading Text Properties</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading Text Properties -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides two functions that you can use to set and read

-the text properties for a given window.

-You can use these functions to set and read those properties of type TEXT

-(<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property>).

-In addition,

-Xlib provides separate convenience functions that you can use to set each 

-of these properties.

-For further information about these convenience functions,

-see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set one of a window's text properties, use

-<function>XSetTextProperty</function>.

-<indexterm significance="preferred"><primary>XSetTextProperty</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetTextProperty</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XTextProperty</structname>

-structure to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetTextProperty</function>

-function replaces the existing specified property for the named window 

-with the data, type, format, and number of items determined 

-by the value field, the encoding field, the format field, 

-and the nitems field, respectively, of the specified

-<structname>XTextProperty</structname>

-structure.

-If the property does not already exist,

-<function>XSetTextProperty</function>

-sets it for the specified window.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetTextProperty</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadAtom</errorname>,

-<errorname>BadValue</errorname>,

-and 

-<errorname>BadWindow</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read one of a window's text properties, use

-<function>XGetTextProperty</function>.

-<indexterm significance="preferred"><primary>XGetTextProperty</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetTextProperty</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the

-<structname>XTextProperty</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetTextProperty</function>

-function reads the specified property from the window

-and stores the data in the returned

-<structname>XTextProperty</structname>

-structure.

-It stores the data in the value field,

-the type of the data in the encoding field,

-the format of the data in the format field, 

-and the number of items of data in the nitems field.

-An extra byte containing null (which is not included in the nitems member) 

-is stored at the end of the value field of text_prop_return.

-The particular interpretation of the property's encoding 

-and data as text is left to the calling application.

-If the specified property does not exist on the window,

-<function>XGetTextProperty</function>

-sets the value field to NULL, 

-the encoding field to

-<symbol>None</symbol>,

-the format field to zero, 

-and the nitems field to zero.

-</para>

-<para>

-<!-- .LP -->

-If it was able to read and store the data in the

-<structname>XTextProperty</structname>

-structure,

-<function>XGetTextProperty</function>

-returns a nonzero status; 

-otherwise, it returns a zero status.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetTextProperty</function>

-can generate

-<errorname>BadAtom</errorname>

-and 

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_NAME_Property">

-<title>Setting and Reading the WM_NAME Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_NAME Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides convenience functions that you can use to set and read 

-the <property>WM_NAME</property> property for a given window.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set a window's <property>WM_NAME</property> property with the supplied convenience function, use

-<function>XSetWMName</function>.

-<indexterm significance="preferred"><primary>XSetWMName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetWMName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XTextProperty</structname>

-structure to be used.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWMName</function>

-convenience function calls

-<function>XSetTextProperty</function>

-to set the <property>WM_NAME</property> property.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read a window's <property>WM_NAME</property> property with the supplied convenience function, use

-<function>XGetWMName</function>.

-<indexterm significance="preferred"><primary>XGetWMName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetWMName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the

-<structname>XTextProperty</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetWMName</function>

-convenience function calls

-<function>XGetTextProperty</function>

-to obtain the <property>WM_NAME</property> property.

-It returns a nonzero status on success;

-otherwise, it returns a zero status.

-</para>

-<para>

-<!-- .LP -->

-The following two functions have been superseded by

-<function>XSetWMName</function>

-and

-<function>XGetWMName</function>,

-respectively. 

-You can use these additional convenience functions 

-for window names that are encoded as STRING properties.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To assign a name to a window, use

-<function>XStoreName</function>.

-<indexterm><primary>Window</primary><secondary>name</secondary></indexterm>

-<indexterm significance="preferred"><primary>XStoreName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XStoreName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>char<parameter> *window_name</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>window_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window name,

-which should be a null-terminated string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XStoreName</function>

-function assigns the name passed to window_name to the specified window.

-A window manager can display the window name in some prominent

-place, such as the title bar, to allow users to identify windows easily.

-Some window managers may display a window's name in the window's icon,

-although they are encouraged to use the window's icon name

-if one is provided by the application.

-If the string is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-<function>XStoreName</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the name of a window, use

-<function>XFetchName</function>.

-<indexterm significance="preferred"><primary>XFetchName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XFetchName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>char<parameter> **window_name_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>window_name_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the window name, which is a null-terminated string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFetchName</function>

-function returns the name of the specified window.

-If it succeeds,

-it returns a nonzero status; 

-otherwise, no name has been set for the window,

-and it returns zero.

-If the <property>WM_NAME</property> property has not been set for this window,

-<function>XFetchName</function>

-sets window_name_return to NULL.

-If the data returned by the server is in the Latin Portable Character Encoding,

-then the returned string is in the Host Portable Character Encoding.

-Otherwise, the result is implementation-dependent.

-When finished with it, a client must free

-the window name string using

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XFetchName</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_ICON_NAME_Property">

-<title>Setting and Reading the WM_ICON_NAME Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_ICON_NAME Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides convenience functions that you can use to set and read 

-the <property>WM_ICON_NAME</property> property for a given window.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set a window's <property>WM_ICON_NAME</property> property,

-use

-<function>XSetWMIconName</function>.

-<indexterm significance="preferred"><primary>XSetWMIconName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetWMIconName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XTextProperty</structname>

-structure to be used.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWMIconName</function>

-convenience function calls

-<function>XSetTextProperty</function>

-to set the <property>WM_ICON_NAME</property> property.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read a window's <property>WM_ICON_NAME</property> property,

-use

-<function>XGetWMIconName</function>.

-<indexterm significance="preferred"><primary>XGetWMIconName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetWMIconName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the

-<structname>XTextProperty</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetWMIconName</function>

-convenience function calls

-<function>XGetTextProperty</function>

-to obtain the <property>WM_ICON_NAME</property> property.

-It returns a nonzero status on success;

-otherwise, it returns a zero status.

-</para>

-<para>

-<!-- .LP -->

-The next two functions have been superseded by

-<function>XSetWMIconName</function>

-and

-<function>XGetWMIconName</function>,

-respectively.

-You can use these additional convenience functions 

-for window names that are encoded as STRING properties.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the name to be displayed in a window's icon, use

-<function>XSetIconName</function>.

-<indexterm><primary>Window</primary><secondary>icon name</secondary></indexterm>

-<indexterm significance="preferred"><primary>XSetIconName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetIconName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>char<parameter> *icon_name</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>icon_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the icon name,

-which should be a null-terminated string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If the string is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-<function>XSetIconName</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the name a window wants displayed in its icon, use

-<function>XGetIconName</function>.

-<indexterm significance="preferred"><primary>XGetIconName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetIconName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>char<parameter> **icon_name_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>icon_name_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the window's icon name,

-which is a null-terminated string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetIconName</function>

-function returns the name to be displayed in the specified window's icon.

-If it succeeds, it returns a nonzero status; otherwise, 

-if no icon name has been set for the window,

-it returns zero.

-If you never assigned a name to the window,

-<function>XGetIconName</function>

-sets icon_name_return to NULL.

-If the data returned by the server is in the Latin Portable Character Encoding,

-then the returned string is in the Host Portable Character Encoding.

-Otherwise, the result is implementation-dependent.

-When finished with it, a client must free

-the icon name string using

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetIconName</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_HINTS_Property">

-<title>Setting and Reading the WM_HINTS Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_HINTS Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and read 

-the <property>WM_HINTS</property> property for a given window.

-These functions use the flags and the

-<structname>XWMHints</structname>

-structure, as defined in the

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-header file.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To allocate an

-<structname>XWMHints</structname>

-structure, use

-<function>XAllocWMHints</function>.

-</para>

-

-<para>

-  XWMHints *XAllocWMHints()

-</para>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAllocWMHints</function>

-function allocates and returns a pointer to an

-<structname>XWMHints</structname>

-structure.

-Note that all fields in the

-<structname>XWMHints</structname>

-structure are initially set to zero.

-If insufficient memory is available, 

-<function>XAllocWMHints</function>

-returns NULL.

-To free the memory allocated to this structure,

-use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XWMHints</structname>

-structure contains:

-</para>

-

-<literallayout class="monospaced">

-/* Window manager hints mask bits */

-

-#define         InputHint             (1L&lt;&lt;0)

-#define         StateHint             (1L&lt;&lt;1)

-#define         IconPixmapHint        (1L&lt;&lt;2)

-#define         IconWindowHint        (1L&lt;&lt;3)

-#define         IconPositionHint      (1L&lt;&lt;4)

-#define         IconMaskHint          (1L&lt;&lt;5)

-#define         WindowGroupHint       (1L&lt;&lt;6)

-#define         UrgencyHint           (1L&lt;&lt;8)

-#define         AllHints              (InputHint|StateHint|IconPixmapHint|

-                                       IconWIndowHint|IconPositionHint|

-                                       IconMaskHint|WindowGroupHint)

-

-

-/* Values */

-

-typedef struct {

-	long flags;	        /* marks which fields in this structure are defined */

-	Bool input;	        /* does this application rely on the window manager to

-			           get keyboard input? */

-	int initial_state;	/* see below */

-	Pixmap icon_pixmap;	/* pixmap to be used as icon */

-	Window icon_window;	/* window to be used as icon */

-	int icon_x, icon_y;	/* initial position of icon */

-	Pixmap icon_mask;	/* pixmap to be used as mask for icon_pixmap */

-	XID window_group;	/* id of related window group */

-	/* this structure may be extended in the future */

-} XWMHints;

-</literallayout>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The input member is used to communicate to the window manager the input focus

-model used by the application.

-Applications that expect input but never explicitly set focus to any 

-of their subwindows (that is, use the push model of focus management), 

-such as X Version 10 style applications that use real-estate

-driven focus, should set this member to 

-<symbol>True</symbol>.

-Similarly, applications

-that set input focus to their subwindows only when it is given to their

-top-level window by a window manager should also set this member to 

-<symbol>True</symbol>.

-Applications that manage their own input focus by explicitly setting

-focus to one of their subwindows whenever they want keyboard input 

-(that is, use the pull model of focus management) should set this member to 

-<symbol>False</symbol>.

-Applications that never expect any keyboard input also should set this member

-to 

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-Pull model window managers should make it possible for push model

-applications to get input by setting input focus to the top-level windows of

-applications whose input member is 

-<symbol>True</symbol>.

-Push model window managers should

-make sure that pull model applications do not break them 

-by resetting input focus to 

-<symbol>PointerRoot</symbol>

-when it is appropriate (for example, whenever an application whose

-input member is 

-<symbol>False</symbol>

-sets input focus to one of its subwindows).

-</para>

-<para>

-<!-- .LP -->

-The definitions for the initial_state flag are:

-</para>

-

-<literallayout class="monospaced">

-#define      WithdrawnState 0

-#define      NormalState    1   /* most applications start this way */

-#define      IconicState    2   /* application wants to start as an icon */

-

-</literallayout>

-<para>

-The icon_mask specifies which pixels of the icon_pixmap should be used as the

-icon.  

-This allows for nonrectangular icons.

-Both icon_pixmap and icon_mask must be bitmaps.

-The icon_window lets an application provide a window for use as an icon

-for window managers that support such use.

-The window_group lets you specify that this window belongs to a group

-of other windows.

-For example, if a single application manipulates multiple 

-top-level windows, this allows you to provide enough

-information that a window manager can iconify all of the windows

-rather than just the one window.

-</para>

-<para>

-<!-- .LP -->

-The

-<symbol>UrgencyHint</symbol>

-flag, if set in the flags field, indicates that the client deems the window

-contents to be urgent, requiring the timely response of the user.  The

-window manager will make some effort to draw the user's attention to this

-window while this flag is set.  The client must provide some means by which the

-user can cause the urgency flag to be cleared (either mitigating

-the condition that made the window urgent or merely shutting off the alarm)

-or the window to be withdrawn.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set a window's <property>WM_HINTS</property> property, use

-<function>XSetWMHints</function>.

-<indexterm significance="preferred"><primary>XSetWMHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetWMHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XWMHints<parameter> *wmhints</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>wmhints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<structname>XWMHints</structname>

-structure to be used.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWMHints</function>

-function sets the window manager hints that include icon information and location,

-the initial state of the window, and whether the application relies on the

-window manager to get keyboard input.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWMHints</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To read a window's <property>WM_HINTS</property> property, use

-<function>XGetWMHints</function>.

-<indexterm significance="preferred"><primary>XGetWMHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XWMHints *<function>XGetWMHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetWMHints</function>

-function reads the window manager hints and 

-returns NULL if no <property>WM_HINTS</property> property was set on the window 

-or returns a pointer to an 

-<structname>XWMHints</structname>

-structure if it succeeds.

-When finished with the data,

-free the space used for it by calling

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetWMHints</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">

-<title>Setting and Reading the WM_NORMAL_HINTS Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_NORMAL_HINTS Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set or read 

-the <property>WM_NORMAL_HINTS</property> property for a given window.

-The functions use the flags and the

-<structname>XSizeHints</structname>

-structure, as defined in the

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-header file.

-</para>

-<para>

-<!-- .LP -->

-The size of the

-<structname>XSizeHints</structname>

-structure may grow in future releases, as new components are

-added to support new <acronym>ICCCM</acronym> features.

-Passing statically allocated instances of this structure into

-Xlib may result in memory corruption when running against a

-future release of the library.

-As such, it is recommended that only dynamically allocated

-instances of the structure be used.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To allocate an

-<structname>XSizeHints</structname>

-structure, use

-<function>XAllocSizeHints</function>.

-</para>

-

-<para>

-XSizeHints *XAllocSizeHints()

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAllocSizeHints</function>

-function allocates and returns a pointer to an

-<structname>XSizeHints</structname>

-structure.

-Note that all fields in the

-<structname>XSizeHints</structname>

-structure are initially set to zero.

-If insufficient memory is available, 

-<function>XAllocSizeHints</function>

-returns NULL.

-To free the memory allocated to this structure,

-use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XSizeHints</structname>

-structure contains:

-</para>

-

-

-<literallayout class="monospaced">

-/* Size hints mask bits */

-

-#define           USPosition         (1L&lt;&lt;0)  /* user specified x,y */

-#define           USSize             (1L&lt;&lt;1)  /* user specified width,height */

-#define           PPosition          (1L&lt;&lt;2)  /* program specified posistion */

-#define           PSize              (1L&lt;&lt;3)  /* program specified size */

-#define           PMinSize           (1L&lt;&lt;4)  /* program specified minimum size */

-#define           PMaxSize           (1L&lt;&lt;5)  /* program specified maximum size */

-#define           PResizeInc         (1L&lt;&lt;5)  /* program specified resize increments */

-#define           PAspect            (1L&lt;&lt;6)  /* program specified min and max aspect ratios */

-#define           PBaseSize          (1L&lt;&lt;8)

-#define           PWinGravity        (1L&lt;&lt;9)

-#define           PAllHints          (PPosition|Psize|

-                                      PMinSize|PMaxSize|

-                                      PResizeInc|PAspect)

-

-

-/* Values */

-

-typedef struct {

-	long flags;	        /* marks which fields in this structure are defined */

-	int x, y;	        /* Obsolete */

-	int width, height;	/* Obsolete */

-	int min_width, min_height;

-	int max_width, max_height;

-	int width_inc, height_inc;

-	struct {

-	       int x;	        /* numerator */

-	       int y;	        /* denominator */

-	} min_aspect, max_aspect;

-	int base_width, base_height;

-	int win_gravity;

-	/* this structure may be extended in the future */

-} XSizeHints;

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The x, y, width, and height members are now obsolete

-and are left solely for compatibility reasons.

-The min_width and min_height members specify the

-minimum window size that still allows the application to be useful.

-The max_width and max_height members specify the maximum window size.

-The width_inc and height_inc members define an arithmetic progression of

-sizes (minimum to maximum) into which the window prefers to be resized.

-The min_aspect and max_aspect members are expressed

-as ratios of x and y, 

-and they allow an application to specify the range of aspect

-ratios it prefers.

-The base_width and base_height members define the desired size of the window.

-The window manager will interpret the position of the window 

-and its border width to position the point of the outer rectangle 

-of the overall window specified by the win_gravity member.

-The outer rectangle of the window includes any borders or decorations

-supplied by the window manager.

-In other words,

-if the window manager decides to place the window where the client asked,

-the position on the parent window's border named by the win_gravity 

-will be placed where the client window would have been placed 

-in the absence of a window manager.

-</para>

-<para>

-<!-- .LP -->

-Note that use of the

-<symbol>PAllHints</symbol>

-macro is highly discouraged.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set a window's <property>WM_NORMAL_HINTS</property> property, use

-<function>XSetWMNormalHints</function>.

-<indexterm significance="preferred"><primary>XSetWMNormalHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetWMNormalHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size hints for the window in its normal state.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XSetWMNormalHints</function>

-function replaces the size hints for the <property>WM_NORMAL_HINTS</property> property 

-on the specified window.

-If the property does not already exist,

-<function>XSetWMNormalHints</function>

-sets the size hints for the <property>WM_NORMAL_HINTS</property> property on the specified window.

-The property is stored with a type of <property>WM_SIZE_HINTS</property> and a format of 32.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWMNormalHints</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read a window's <property>WM_NORMAL_HINTS</property> property, use

-<function>XGetWMNormalHints</function>.

-<indexterm significance="preferred"><primary>XGetWMNormalHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetWMNormalHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>

-  <paramdef>long<parameter> *supplied_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the size hints for the window in its normal state.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>supplied_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the hints that were supplied by the user.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetWMNormalHints</function>

-function returns the size hints stored in the <property>WM_NORMAL_HINTS</property> property 

-on the specified window.

-If the property is of type <property>WM_SIZE_HINTS</property>, is of format 32,

-and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>) 

-or new size hints structure, 

-<function>XGetWMNormalHints</function>

-sets the various fields of the 

-<structname>XSizeHints</structname>

-structure, sets the supplied_return argument to the list of fields 

-that were supplied by the user (whether or not they contained defined values),

-and returns a nonzero status.

-Otherwise, it returns a zero status.

-</para>

-<para>

-<!-- .LP -->

-If 

-<function>XGetWMNormalHints</function>

-returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read, 

-the supplied_return argument will contain the following bits:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-(USPosition|USSize|PPosition|PSize|PMinSize|

- PMaxSize|PResizeInc|PAspect)

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-If the property is large enough to contain the base size 

-and window gravity fields as well, 

-the supplied_return argument will also contain the following bits:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-PBaseSize|PWinGravity

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<function>XGetWMNormalHints</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set a window's <property>WM_SIZE_HINTS</property> property, use

-<function>XSetWMSizeHints</function>.

-<indexterm significance="preferred"><primary>XSetWMSizeHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetWMSizeHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XSizeHints</structname>

-structure to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XSetWMSizeHints</function>

-function replaces the size hints for the specified property 

-on the named window.

-If the specified property does not already exist,

-<function>XSetWMSizeHints</function>

-sets the size hints for the specified property

-on the named window.

-The property is stored with a type of <property>WM_SIZE_HINTS</property> and a format of 32.

-To set a window's normal size hints, 

-you can use the 

-<function>XSetWMNormalHints</function>

-function.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWMSizeHints</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadAtom</errorname>,

-and 

-<errorname>BadWindow</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read a window's <property>WM_SIZE_HINTS</property> property, use

-<function>XGetWMSizeHints</function>.

-<indexterm significance="preferred"><primary>XGetWMSizeHints</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetWMSizeHints</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>

-  <paramdef>long<parameter> *supplied_return</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the

-<structname>XSizeHints</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>supplied_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the hints that were supplied by the user.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetWMSizeHints</function>

-function returns the size hints stored in the specified property 

-on the named window.

-If the property is of type <property>WM_SIZE_HINTS</property>, is of format 32, 

-and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>) 

-or new size hints structure, 

-<function>XGetWMSizeHints</function>

-sets the various fields of the 

-<structname>XSizeHints</structname>

-structure, sets the supplied_return argument to the

-list of fields that were supplied by the user 

-(whether or not they contained defined values), 

-and returns a nonzero status.

-Otherwise, it returns a zero status.

-To get a window's normal size hints, 

-you can use the 

-<function>XGetWMNormalHints</function>

-function.

-</para>

-<para>

-<!-- .LP -->

-If 

-<function>XGetWMSizeHints</function>

-returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read, 

-the supplied_return argument will contain the following bits:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-(USPosition|USSize|PPosition|PSize|PMinSize|

- PMaxSize|PResizeInc|PAspect)

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-If the property is large enough to contain the base size 

-and window gravity fields as well, 

-the supplied_return argument will also contain the following bits:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-PBaseSize|PWinGravity

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<function>XGetWMSizeHints</function>

-can generate

-<errorname>BadAtom</errorname>

-and 

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_CLASS_Property">

-<title>Setting and Reading the WM_CLASS Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_CLASS Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and get 

-the <property>WM_CLASS</property> property for a given window.

-These functions use the

-<structname>XClassHint</structname>

-structure, which is defined in the

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-header file.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To allocate an

-<structname>XClassHint</structname>

-structure, use

-<function>XAllocClassHint</function>.

-<indexterm significance="preferred"><primary>XAllocClassHint</primary></indexterm>

-<!-- .sM -->

-</para>

-<para>

-

-  XClassHint *XAllocClassHint()

-</para>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAllocClassHint</function>

-function allocates and returns a pointer to an

-<structname>XClassHint</structname>

-structure.

-Note that the pointer fields in the

-<structname>XClassHint</structname>

-structure are initially set to NULL.

-If insufficient memory is available, 

-<function>XAllocClassHint</function>

-returns NULL.

-To free the memory allocated to this structure,

-use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XClassHint</structname>

-contains:

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<indexterm significance="preferred"><primary>XClassHint</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i -->

-<!-- .ta .5i -->

-typedef struct {

-	char *res_name;

-	char *res_class;

-} XClassHint;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The res_name member contains the application name, 

-and the res_class member contains the application class. 

-Note that the name set in this property may differ from the name set as <property>WM_NAME</property>.

-That is, <property>WM_NAME</property> specifies what should be displayed in the title bar and,

-therefore, can contain temporal information (for example, the name of

-a file currently in an editor's buffer).

-On the other hand, 

-the name specified as part of <property>WM_CLASS</property> is the formal name of the application

-that should be used when retrieving the application's resources from the 

-resource database.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set a window's <property>WM_CLASS</property> property, use

-<function>XSetClassHint</function>.

-<indexterm significance="preferred"><primary>XSetClassHint</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetClassHint</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class_hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XClassHint</structname>

-structure that is to be used.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetClassHint</function>

-function sets the class hint for the specified window.

-If the strings are not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetClassHint</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors. 

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To read a window's <property>WM_CLASS</property> property, use

-<function>XGetClassHint</function>.

-<indexterm significance="preferred"><primary>XGetClassHint</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetClassHint</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XClassHint<parameter> *class_hints_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class_hints_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the 

-<structname>XClassHint</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetClassHint</function>

-function returns the class hint of the specified window to the members

-of the supplied structure.

-If the data returned by the server is in the Latin Portable Character Encoding,

-then the returned strings are in the Host Portable Character Encoding.

-Otherwise, the result is implementation-dependent.

-It returns a nonzero status on success;

-otherwise, it returns a zero status.

-To free res_name and res_class when finished with the strings,

-use

-<function>XFree</function>

-on each individually.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetClassHint</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_TRANSIENT_FOR_Property">

-<title>Setting and Reading the WM_TRANSIENT_FOR Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_TRANSIENT_FOR Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and read

-the <property>WM_TRANSIENT_FOR</property> property for a given window.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set a window's <property>WM_TRANSIENT_FOR</property> property, use

-<function>XSetTransientForHint</function>.

-<indexterm significance="preferred"><primary>XSetTransientForHint</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetTransientForHint</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Window<parameter> prop_window</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>prop_window</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window that the <property>WM_TRANSIENT_FOR</property> property is to be set to.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetTransientForHint</function>

-function sets the <property>WM_TRANSIENT_FOR</property> property of the specified window to the 

-specified prop_window.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetTransientForHint</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To read a window's <property>WM_TRANSIENT_FOR</property> property, use

-<function>XGetTransientForHint</function>.

-<indexterm significance="preferred"><primary>XGetTransientForHint</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetTransientForHint</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Window<parameter> *prop_window_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>prop_window_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the <property>WM_TRANSIENT_FOR</property> property of the specified window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetTransientForHint</function>

-function returns the <property>WM_TRANSIENT_FOR</property> property for the specified window.

-It returns a nonzero status on success;

-otherwise, it returns a zero status.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetTransientForHint</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_PROTOCOLS_Property">

-<title>Setting and Reading the WM_PROTOCOLS Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_PROTOCOLS Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and read

-the <property>WM_PROTOCOLS</property> property for a given window.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set a window's <property>WM_PROTOCOLS</property> property, use

-<function>XSetWMProtocols</function>.

-<indexterm significance="preferred"><primary>XSetWMProtocols</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XSetWMProtocols</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Atom<parameter> *protocols</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>protocols</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the list of protocols.

-<!-- .ds Cn protocols in the list -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of (Cn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XSetWMProtocols</function>

-function replaces the <property>WM_PROTOCOLS</property> property on the specified window 

-with the list of atoms specified by the protocols argument.

-If the property does not already exist,

-<function>XSetWMProtocols</function>

-sets the <property>WM_PROTOCOLS</property> property on the specified window

-to the list of atoms specified by the protocols argument.

-The property is stored with a type of ATOM and a format of 32.

-If it cannot intern the <property>WM_PROTOCOLS</property> atom, 

-<function>XSetWMProtocols</function>

-returns a zero status.

-Otherwise, it returns a nonzero status.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWMProtocols</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read a window's <property>WM_PROTOCOLS</property> property, use

-<function>XGetWMProtocols</function>.

-<indexterm significance="preferred"><primary>XGetWMProtocols</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetWMProtocols</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Atom<parameter> **protocols_return</parameter></paramdef>

-  <paramdef>int<parameter> *count_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>protocols_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the list of protocols.

-<!-- .ds Cn protocols in the list -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of (Cn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetWMProtocols</function>

-function returns the list of atoms stored in the <property>WM_PROTOCOLS</property> property 

-on the specified window.

-These atoms describe window manager protocols in which the owner 

-of this window is willing to participate.

-If the property exists, is of type ATOM, is of format 32, 

-and the atom <property>WM_PROTOCOLS</property> can be interned, 

-<function>XGetWMProtocols</function>

-sets the protocols_return argument to a list of atoms, 

-sets the count_return argument to the number of elements in the list, 

-and returns a nonzero status.

-Otherwise, it sets neither of the return arguments

-and returns a zero status.

-To release the list of atoms, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetWMProtocols</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property">

-<title>Setting and Reading the WM_COLORMAP_WINDOWS Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_COLORMAP_WINDOWS Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and read

-the <property>WM_COLORMAP_WINDOWS</property> property for a given window.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set a window's <property>WM_COLORMAP_WINDOWS</property> property, use

-<function>XSetWMColormapWindows</function>.

-<indexterm significance="preferred"><primary>XSetWMColormapWindows</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XSetWMColormapWindows</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Window<parameter> *colormap_windows</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap_windows</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the list of windows.

-<!-- .ds Cn windows in the list -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of (Cn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XSetWMColormapWindows</function>

-function replaces the <property>WM_COLORMAP_WINDOWS</property> property on the specified

-window with the list of windows specified by the colormap_windows argument.

-If the property does not already exist,

-<function>XSetWMColormapWindows</function>

-sets the <property>WM_COLORMAP_WINDOWS</property> property on the specified

-window to the list of windows specified by the colormap_windows argument.

-The property is stored with a type of WINDOW and a format of 32.

-If it cannot intern the <property>WM_COLORMAP_WINDOWS</property> atom,

-<function>XSetWMColormapWindows</function>

-returns a zero status.

-Otherwise, it returns a nonzero status.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWMColormapWindows</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read a window's <property>WM_COLORMAP_WINDOWS</property> property, use

-<function>XGetWMColormapWindows</function>.

-<indexterm significance="preferred"><primary>XGetWMColormapWindows</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetWMColormapWindows</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Window<parameter> **colormap_windows_return</parameter></paramdef>

-  <paramdef>int<parameter> *count_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>colormap_windows_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the list of windows.

-<!-- .ds Cn windows in the list -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of (Cn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetWMColormapWindows</function>

-function returns the list of window identifiers stored 

-in the <property>WM_COLORMAP_WINDOWS</property> property on the specified window.

-These identifiers indicate the colormaps that the window manager

-may need to install for this window.

-If the property exists, is of type WINDOW, is of format 32, 

-and the atom <property>WM_COLORMAP_WINDOWS</property> can be interned, 

-<function>XGetWMColormapWindows</function>

-sets the windows_return argument to a list of window identifiers, 

-sets the count_return argument to the number of elements in the list, 

-and returns a nonzero status.

-Otherwise, it sets neither of the return arguments

-and returns a zero status.

-To release the list of window identifiers, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetWMColormapWindows</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_ICON_SIZE_Property">

-<title>Setting and Reading the WM_ICON_SIZE Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_ICON_SIZE Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and read 

-the <property>WM_ICON_SIZE</property> property for a given window.

-These functions use the 

-<structname>XIconSize</structname>

-<indexterm><primary>XIconSize</primary></indexterm>

-structure, which is defined in the

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-header file.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To allocate an

-<structname>XIconSize</structname>

-structure, use

-<function>XAllocIconSize</function>.

-</para>

-

-<para>

-  XIconSize *XAllocIconSize()

-</para>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAllocIconSize</function>

-function allocates and returns a pointer to an

-<structname>XIconSize</structname>

-structure.

-Note that all fields in the

-<structname>XIconSize</structname>

-structure are initially set to zero.

-If insufficient memory is available, 

-<function>XAllocIconSize</function>

-returns NULL.

-To free the memory allocated to this structure,

-use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XIconSize</structname>

-structure contains:

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<indexterm significance="preferred"><primary>XIconSize</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	int min_width, min_height;

-	int max_width, max_height;

-	int width_inc, height_inc;

-} XIconSize;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The width_inc and height_inc members define an arithmetic progression of

-sizes (minimum to maximum) that represent the supported icon sizes.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set a window's <property>WM_ICON_SIZE</property> property, use

-<function>XSetIconSizes</function>.

-<indexterm significance="preferred"><primary>XSetIconSizes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetIconSizes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XIconSize<parameter> *size_list</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>size_list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of items in the size list.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetIconSizes</function>

-function is used only by window managers to set the supported icon sizes.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetIconSizes</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To read a window's <property>WM_ICON_SIZE</property> property, use

-<function>XGetIconSizes</function>.

-<indexterm significance="preferred"><primary>XGetIconSizes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetIconSizes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XIconSize<parameter> **size_list_return</parameter></paramdef>

-  <paramdef>int<parameter> *count_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>size_list_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the size list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of items in the size list.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetIconSizes</function>

-function returns zero if a window manager has not set icon sizes;

-otherwise, it returns nonzero.

-<function>XGetIconSizes</function>

-should be called by an application that

-wants to find out what icon sizes would be most appreciated by the

-window manager under which the application is running.

-The application

-should then use

-<function>XSetWMHints</function>

-to supply the window manager with an icon pixmap or window in one of the

-supported sizes.

-To free the data allocated in size_list_return, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetIconSizes</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect2>

-<sect2 id="Using_Window_Manager_Convenience_Functions">

-<title>Using Window Manager Convenience Functions</title>

-<!-- .XS -->

-<!-- (SN Using Window Manager Convenience Functions -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The 

-<function>XmbSetWMProperties</function>

-function stores the standard set of window manager properties,

-with text properties in standard encodings

-for internationalized text communication.

-The standard window manager properties for a given window are

-<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_NORMAL_HINTS</property>, <property>WM_CLASS</property>,

-<property>WM_COMMAND</property>, <property>WM_CLIENT_MACHINE</property>, and <property>WM_LOCALE_NAME</property>.

-<indexterm significance="preferred"><primary>XmbSetWMProperties</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XmbSetWMProperties</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>char<parameter> *window_name</parameter></paramdef>

-  <paramdef>char<parameter> *icon_name</parameter></paramdef>

-  <paramdef>char<parameter> *argv[]</parameter></paramdef>

-  <paramdef>int<parameter> argc</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>

-  <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>

-  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>window_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window name,

-which should be a null-terminated string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>icon_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the icon name,

-which should be a null-terminated string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argv</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the application's argument list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of arguments.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size hints for the window in its normal state.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>wm_hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XWMHints</structname>

-structure to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class_hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XClassHint</structname>

-structure to be used.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XmbSetWMProperties</function>

-convenience function provides a simple programming interface 

-for setting those essential window properties that are used 

-for communicating with other clients

-(particularly window and session managers).

-</para>

-<para>

-<!-- .LP -->

-If the window_name argument is non-NULL,

-<function>XmbSetWMProperties</function>

-sets the <property>WM_NAME</property> property.

-If the icon_name argument is non-NULL,

-<function>XmbSetWMProperties</function>

-sets the <property>WM_ICON_NAME</property> property.

-The window_name and icon_name arguments are null-terminated strings

-in the encoding of the current locale.

-If the arguments can be fully converted to the STRING encoding,

-the properties are created with type ``STRING''; 

-otherwise, the arguments are converted to Compound Text, 

-and the properties are created with type ``COMPOUND_TEXT''.

-</para>

-<para>

-<!-- .LP -->

-If the normal_hints argument is non-NULL,

-<function>XmbSetWMProperties</function>

-calls

-<function>XSetWMNormalHints</function>,

-which sets the <property>WM_NORMAL_HINTS</property> property (see section 14.1.7).

-If the wm_hints argument is non-NULL, 

-<function>XmbSetWMProperties</function>

-calls

-<function>XSetWMHints</function>,

-which sets the <property>WM_HINTS</property> property (see section 14.1.6).

-</para>

-<para>

-<!-- .LP -->

-If the argv argument is non-NULL,

-<function>XmbSetWMProperties</function>

-sets the <property>WM_COMMAND</property> property from argv and argc.

-An argc of zero indicates a zero-length command.

-</para>

-<para>

-<!-- .LP -->

-The hostname of the machine is stored using 

-<function>XSetWMClientMachine</function>

-(see section 14.2.2).

-</para>

-<para>

-<!-- .LP -->

-If the class_hints argument is non-NULL,

-<function>XmbSetWMProperties</function>

-sets the <property>WM_CLASS</property> property.

-If the res_name member in the 

-<structname>XClassHint</structname>

-structure is set to the NULL pointer and the RESOURCE_NAME

-environment variable is set,

-the value of the environment variable is substituted for res_name.

-If the res_name member is NULL,

-the environment variable is not set, and argv and argv[0] are set,

-then the value of argv[0], stripped of any directory prefixes,

-is substituted for res_name.

-</para>

-<para>

-<!-- .LP -->

-It is assumed that the supplied class_hints.res_name and argv,

-the RESOURCE_NAME environment variable, and the hostname of the machine

-are in the encoding of the locale announced for the LC_CTYPE category

-(on <acronym>POSIX</acronym>-compliant systems, the LC_CTYPE, else LANG environment variable).

-The corresponding <property>WM_CLASS</property>, <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property> properties

-are typed according to the local host locale announcer.

-No encoding conversion is performed prior to storage in the properties.

-</para>

-<para>

-<!-- .LP -->

-For clients that need to process the property text in a locale,

-<function>XmbSetWMProperties</function>

-sets the <property>WM_LOCALE_NAME</property> property to be the name of the current locale.

-The name is assumed to be in the Host Portable Character Encoding

-and is converted to STRING for storage in the property.

-</para>

-<para>

-<!-- .LP -->

-<function>XmbSetWMProperties</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set a window's standard window manager properties

-with strings in client-specified encodings, use

-<function>XSetWMProperties</function>.

-The standard window manager properties for a given window are

-<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_NORMAL_HINTS</property>, <property>WM_CLASS</property>,

-<property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property>.

-<indexterm significance="preferred"><primary>XSetWMProperties</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetWMProperties</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *window_name</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *icon_name</parameter></paramdef>

-  <paramdef>char<parameter> **argv</parameter></paramdef>

-  <paramdef>int<parameter> argc</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>

-  <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>

-  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>window_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window name,

-which should be a null-terminated string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>icon_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the icon name,

-which should be a null-terminated string.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argv</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the application's argument list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of arguments.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>normal_hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size hints for the window in its normal state.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>wm_hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XWMHints</structname>

-structure to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class_hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XClassHint</structname>

-structure to be used.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XSetWMProperties</function>

-convenience function provides a single programming interface 

-for setting those essential window properties that are used 

-for communicating with other clients (particularly window and session

-managers).

-</para>

-<para>

-<!-- .LP -->

-If the window_name argument is non-NULL, 

-<function>XSetWMProperties</function>

-calls

-<function>XSetWMName</function>,

-which, in turn, sets the <property>WM_NAME</property> property (see section 14.1.4).

-If the icon_name argument is non-NULL,

-<function>XSetWMProperties</function>

-calls

-<function>XSetWMIconName</function>,

-which sets the <property>WM_ICON_NAME</property> property (see section 14.1.5).

-If the argv argument is non-NULL, 

-<function>XSetWMProperties</function>

-calls

-<function>XSetCommand</function>,

-which sets the <property>WM_COMMAND</property> property (see section 14.2.1).

-Note that an argc of zero is allowed to indicate a zero-length command.

-Note also that the hostname of this machine is stored using

-<function>XSetWMClientMachine</function>

-(see section 14.2.2).

-</para>

-<para>

-<!-- .LP -->

-If the normal_hints argument is non-NULL, 

-<function>XSetWMProperties</function>

-calls

-<function>XSetWMNormalHints</function>,

-which sets the <property>WM_NORMAL_HINTS</property> property (see section 14.1.7).

-If the wm_hints argument is non-NULL, 

-<function>XSetWMProperties</function>

-calls

-<function>XSetWMHints</function>,

-which sets the <property>WM_HINTS</property> property (see section 14.1.6).

-</para>

-<para>

-<!-- .LP -->

-If the class_hints argument is non-NULL, 

-<function>XSetWMProperties</function>

-calls

-<function>XSetClassHint</function>,

-which sets the <property>WM_CLASS</property> property (see section 14.1.8).

-If the res_name member in the

-<structname>XClassHint</structname>

-structure is set to the NULL pointer and the RESOURCE_NAME environment 

-variable is set, 

-then the value of the environment variable is substituted for res_name.

-If the res_name member is NULL, 

-the environment variable is not set, 

-and argv and argv[0] are set, 

-then the value of argv[0], stripped of

-any directory prefixes, is substituted for res_name.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetWMProperties</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Client_to_Session_Manager_Communication">

-<title>Client to Session Manager Communication</title>

-<!-- .XS -->

-<!-- (SN Client to Session Manager Communication -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section discusses how to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Set and read the <property>WM_COMMAND</property> property

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Set and read the <property>WM_CLIENT_MACHINE</property> property

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Setting_and_Reading_the_WM_COMMAND_Property">

-<title>Setting and Reading the WM_COMMAND Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_COMMAND Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and read

-the <property>WM_COMMAND</property> property for a given window.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set a window's <property>WM_COMMAND</property> property, use

-<function>XSetCommand</function>.

-<indexterm significance="preferred"><primary>XSetCommand</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetCommand</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>char<parameter> **argv</parameter></paramdef>

-  <paramdef>int<parameter> argc</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argv</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the application's argument list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of arguments.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetCommand</function>

-function sets the command and arguments used to invoke the

-application.

-(Typically, argv is the argv array of your main program.)

-If the strings are not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetCommand</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read a window's <property>WM_COMMAND</property> property, use

-<function>XGetCommand</function>.

-<indexterm significance="preferred"><primary>XGetCommand</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetCommand</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>char<parameter> ***argv_return</parameter></paramdef>

-  <paramdef>int<parameter> *argc_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argv_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the application's argument list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argc_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of arguments returned.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetCommand</function>

-function reads the <property>WM_COMMAND</property> property from the specified window 

-and returns a string list.

-If the <property>WM_COMMAND</property> property exists, 

-it is of type STRING and format 8.

-If sufficient memory can be allocated to contain the string list, 

-<function>XGetCommand</function>

-fills in the argv_return and argc_return arguments

-and returns a nonzero status.

-Otherwise, it returns a zero status.

-If the data returned by the server is in the Latin Portable Character Encoding,

-then the returned strings are in the Host Portable Character Encoding.

-Otherwise, the result is implementation-dependent.

-To free the memory allocated to the string list, use

-<function>XFreeStringList</function>.

-</para>

-</sect2>

-<sect2 id="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">

-<title>Setting and Reading the WM_CLIENT_MACHINE Property</title>

-<!-- .XS -->

-<!-- (SN Setting and Reading the WM_CLIENT_MACHINE Property -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and read 

-the <property>WM_CLIENT_MACHINE</property> property for a given window.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set a window's <property>WM_CLIENT_MACHINE</property> property, use

-<function>XSetWMClientMachine</function>.

-<indexterm significance="preferred"><primary>XSetWMClientMachine</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetWMClientMachine</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XTextProperty</structname>

-structure to be used.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetWMClientMachine</function>

-convenience function calls

-<function>XSetTextProperty</function>

-to set the <property>WM_CLIENT_MACHINE</property> property.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To read a window's <property>WM_CLIENT_MACHINE</property> property, use

-<function>XGetWMClientMachine</function>.

-<indexterm significance="preferred"><primary>XGetWMClientMachine</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetWMClientMachine</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>text_prop_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the

-<structname>XTextProperty</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetWMClientMachine</function>

-convenience function performs an 

-<function>XGetTextProperty</function>

-on the <property>WM_CLIENT_MACHINE</property> property.

-It returns a nonzero status on success;

-otherwise, it returns a zero status.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Standard_Colormaps">

-<title>Standard Colormaps</title>

-<!-- .XS -->

-<!-- (SN Standard Colormaps  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Applications with color palettes, smooth-shaded drawings, or digitized

-images demand large numbers of colors.  

-In addition, these applications often require an efficient mapping 

-from color triples to pixel values that display the appropriate colors.

-</para>

-<para>

-<!-- .LP -->

-As an example, consider a three-dimensional display program that wants 

-to draw a smoothly shaded sphere.  

-At each pixel in the image of the sphere, 

-the program computes the intensity and color of light

-reflected back to the viewer.  

-The result of each computation is a triple of red, green, and blue (<acronym>RGB</acronym>)

-coefficients in the range 0.0 to 1.0.  

-To draw the sphere, the program needs a colormap that provides a

-large range of uniformly distributed colors.  

-The colormap should be arranged so that the program can

-convert its <acronym>RGB</acronym> triples into pixel values very quickly,

-because drawing the entire sphere requires many such

-conversions.

-</para>

-<para>

-<!-- .LP -->

-On many current workstations,

-the display is limited to 256 or fewer colors.  

-Applications must allocate colors carefully, 

-not only to make sure they cover the entire range they need 

-but also to make use of as many of the available colors as possible.

-On a typical X display, 

-many applications are active at once.

-Most workstations have only one hardware look-up table for colors,

-so only one application colormap can be installed at a given time.

-The application using the installed colormap is displayed correctly, 

-and the other applications go technicolor and are

-displayed with false colors.

-</para>

-<para>

-<!-- .LP -->

-As another example, consider a user who is running an 

-image processing program to display earth-resources data.  

-The image processing program needs a colormap set up with 8 reds, 

-8 greens, and 4 blues, for a total of 256 colors.

-Because some colors are already in use in the default colormap, 

-the image processing program allocates and installs a new colormap.

-</para>

-<para>

-<!-- .LP -->

-The user decides to alter some of the colors in the image

-by invoking a color palette program to mix and choose colors.

-The color palette program also needs a

-colormap with eight reds, eight greens, and four blues, so just like

-the image processing program, it must allocate and

-install a new colormap.

-</para>

-<para>

-<!-- .LP -->

-Because only one colormap can be installed at a time,

-the color palette may be displayed incorrectly

-whenever the image processing program is active.

-Conversely, whenever the palette program is active, 

-the image may be displayed incorrectly.  

-The user can never match or compare colors in the palette and image.

-Contention for colormap resources can be reduced if applications

-with similar color needs share colormaps.

-</para>

-<para>

-<!-- .LP -->

-The image processing program and the color palette program 

-could share the same colormap if there existed a convention that described

-how the colormap was set up.  

-Whenever either program was active, 

-both would be displayed correctly.

-</para>

-<para>

-<!-- .LP -->

-The standard colormap properties define a set of commonly used

-colormaps.  

-Applications that share these colormaps and conventions display 

-true colors more often and provide a better interface to the user.

-</para>

-<para>

-<!-- .LP -->

-Standard colormaps allow applications to share commonly used color

-resources.  

-This allows many applications to be displayed in true colors

-simultaneously, even when each application needs an entirely filled

-colormap.

-</para>

-<para>

-<!-- .LP -->

-Several standard colormaps are described in this section.

-Usually, a window manager creates these colormaps.

-Applications should use the standard colormaps if they already exist.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To allocate an

-<structname>XStandardColormap</structname>

-structure, use

-<function>XAllocStandardColormap</function>.

-</para>

-

-<para>

-XStandardColormap *XAllocStandardColormap()

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAllocStandardColormap</function>

-function allocates and returns a pointer to an

-<structname>XStandardColormap</structname>

-structure.

-Note that all fields in the

-<structname>XStandardColormap</structname>

-structure are initially set to zero.

-If insufficient memory is available, 

-<function>XAllocStandardColormap</function>

-returns NULL.

-To free the memory allocated to this structure,

-use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-The 

-<structname>XStandardColormap</structname>

-structure contains:

-</para>

-<literallayout class="monospaced">

-/* Hints */

-

-#define       ReeaseByFreeingColormap  ((XID)1L)

-

-/* Values */

-

-typedef struct {

-	Colormap colormap;

-	unsigned long red_max;

-	unsigned long red_mult;

-	unsigned long green_max;

-	unsigned long green_mult;

-	unsigned long blue_max;

-	unsigned long blue_mult;

-	unsigned long base_pixel;

-	VisualID visualid;

-	XID killid;

-} XStandardColormap;

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The colormap member is the colormap created by the

-<function>XCreateColormap</function>

-function.

-The red_max, green_max, and blue_max members give the maximum

-red, green, and blue values, respectively.  

-Each color coefficient ranges from zero to its max, inclusive.  

-For example,

-a common colormap allocation is 3/3/2 (3 planes for red, 3

-planes for green, and 2 planes for blue).  

-This colormap would have red_max = 7, green_max = 7, 

-and blue_max = 3.  

-An alternate allocation that uses only 216 colors is red_max = 5, 

-green_max = 5, and blue_max = 5.

-</para>

-<para>

-<!-- .LP -->

-The red_mult, green_mult, and blue_mult members give the

-scale factors used to compose a full pixel value. 

-(See the discussion of the base_pixel members for further information.)

-For a 3/3/2 allocation, red_mult might be 32,

-green_mult might be 4, and blue_mult might be 1.  

-For a 6-colors-each allocation, red_mult might be 36, 

-green_mult might be 6, and blue_mult might be 1.

-</para>

-<para>

-<!-- .LP -->

-The base_pixel member gives the base pixel value used to

-compose a full pixel value.  

-Usually, the base_pixel is obtained from a call to the 

-<function>XAllocColorPlanes</function>

-function.  

-Given integer red, green, and blue coefficients in their appropriate 

-ranges, one then can compute a corresponding pixel value by

-using the following expression:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 1.5i -->

-<!-- .ta .5i 1.5i -->

-(r * red_mult + g * green_mult + b * blue_mult + base_pixel) &amp; 0xFFFFFFFF

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-For 

-<symbol>GrayScale</symbol>

-colormaps, 

-only the colormap, red_max, red_mult, 

-and base_pixel members are defined. 

-The other members are ignored.  

-To compute a 

-<symbol>GrayScale</symbol>

-pixel value, use the following expression:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .5i 1.5i -->

-<!-- .ta .5i 1.5i -->

-(gray * red_mult + base_pixel) &amp; 0xFFFFFFFF

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Negative multipliers can be represented by converting the 2's

-complement representation of the multiplier into an unsigned long and

-storing the result in the appropriate _mult field.

-The step of masking by 0xFFFFFFFF effectively converts the resulting

-positive multiplier into a negative one.

-The masking step will take place automatically on many machine architectures,

-depending on the size of the integer type used to do the computation.

-</para>

-<para>

-<!-- .LP -->

-The visualid member gives the ID number of the visual from which the

-colormap was created.

-The killid member gives a resource ID that indicates whether

-the cells held by this standard colormap are to be released 

-by freeing the colormap ID or by calling the

-<function>XKillClient</function>

-function on the indicated resource.

-(Note that this method is necessary for allocating out of an existing colormap.)

-</para>

-<para>

-<!-- .LP -->

-The properties containing the 

-<structname>XStandardColormap</structname>

-information have 

-the type RGB_COLOR_MAP.

-</para>

-<para>

-<!-- .LP -->

-The remainder of this section discusses standard colormap properties and atoms

-as well as how to manipulate standard colormaps.

-</para>

-<sect2 id="Standard_Colormap_Properties_and_Atoms">

-<title>Standard Colormap Properties and Atoms</title>

-<!-- .XS -->

-<!-- (SN Standard Colormap Properties and Atoms  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Standard Colormaps</primary></indexterm>

-<indexterm><primary>Colormaps</primary><secondary>standard</secondary></indexterm>

-Several standard colormaps are available.  

-Each standard colormap is defined by a property, 

-and each such property is identified by an atom.  

-The following list names the atoms and describes the colormap

-associated with each one.

-The

-<filename class="headerfile">&lt;X11/Xatom.h&gt;</filename>

-<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>

-header file contains the definitions for each of the following atoms,

-which are prefixed with XA_.

-</para>

-

-

-

-<variablelist>

-  <varlistentry>

-    <term>RGB_DEFAULT_MAP</term>

-    <listitem>

-      <para>

-This atom names a property.

-The value of the property is an array of

-<structname>XStandardColormap</structname>

-structures.

-Each entry in the array describes an <acronym>RGB</acronym> subset of the default color

-map for the Visual specified by visual_id.

-      </para>

-      <para>

-Some applications only need a few <acronym>RGB</acronym> colors and

-may be able to allocate them from the system default colormap.

-This is the ideal situation because the fewer colormaps that are

-active in the system the more applications are displayed

-with correct colors at all times.

-      </para>

-      <para>

-A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays

-is 6 reds, 6 greens, and 6 blues.  

-This gives 216 uniformly distributed colors 

-(6 intensities of 36 different hues) and still leaves 40 elements 

-of a 256-element colormap available for special-purpose colors 

-for text, borders, and so on.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>RGB_BEST_MAP</term>

-    <listitem>

-      <para>

-This atom names a property.  The value of the property is an 

-<structname>XStandardColormap</structname>.

-      </para>

-      <para>

-The property defines the best <acronym>RGB</acronym> colormap available on

-the screen.

-(Of course, this is a subjective evaluation.)

-Many image processing and three-dimensional applications need to

-use all available colormap cells and to distribute as many

-perceptually distinct colors as possible over those cells.

-This implies that there may be more green values available than

-red, as well as more green or red than blue.

-      </para>

-      <para>

-For an 8-plane 

-<symbol>PseudoColor</symbol>

-visual, 

-RGB_BEST_MAP is likely to be a 3/3/2 allocation.  

-For a 24-plane 

-<symbol>DirectColor</symbol>

-visual, 

-RGB_BEST_MAP is normally an 8/8/8 allocation.  

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP</term>

-    <listitem>

-      <para>

-These atoms name properties.

-The value of each property is an

-<structname>XStandardColormap</structname>.

-      </para>

-      <para>

-The properties define all-red, all-green, and all-blue

-colormaps, respectively.  

-These maps are used by applications that want to make color-separated 

-images.  

-For example, a user might generate a full-color image 

-on an 8-plane display both by rendering an image three times 

-(once with high color resolution in red, once with green, 

-and once with blue) and by multiply exposing a single frame in a camera.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry> 

-    <term>RGB_GRAY_MAP</term>

-    <listitem>

-      <para>

-This atom names a property.

-The value of the property is an 

-<structname>XStandardColormap</structname>.

-      </para>

-      <para>

-The property describes the best 

-<symbol>GrayScale</symbol>

-colormap available on the screen.  

-As previously mentioned, 

-only the colormap, red_max, red_mult, and base_pixel members of the

-<structname>XStandardColormap</structname>

-structure are used for 

-<symbol>GrayScale</symbol>

-colormaps.

-      </para>

-    </listitem>

-  </varlistentry>

-</variablelist>

-

-</sect2>

-

-<sect2 id="Setting_and_Obtaining_Standard_Colormaps">

-<title>Setting and Obtaining Standard Colormaps</title>

-<!-- .XS -->

-<!-- (SN Setting and Obtaining Standard Colormaps -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set and obtain an

-<structname>XStandardColormap</structname>

-structure.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To set an

-<structname>XStandardColormap</structname>

-structure, use

-<function>XSetRGBColormaps</function>.

-<indexterm significance="preferred"><primary>XSetRGBColormaps</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XSetRGBColormaps</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XStandardColormap<parameter> *std_colormap</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>std_colormap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XStandardColormap</structname>

-structure to be used.

-<!-- .ds Cn colormaps -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of (Cn.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XSetRGBColormaps</function>

-function replaces the <acronym>RGB</acronym> colormap definition in the specified property 

-on the named window.

-If the property does not already exist,

-<function>XSetRGBColormaps</function>

-sets the <acronym>RGB</acronym> colormap definition in the specified property

-on the named window.

-The property is stored with a type of RGB_COLOR_MAP and a format of 32.

-Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>

-restriction that only RGB_DEFAULT_MAP contain more than one definition.

-</para>

-<para>

-<!-- .LP -->

-The

-<function>XSetRGBColormaps</function>

-function usually is only used by window or session managers.

-To create a standard colormap, 

-follow this procedure:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Open a new connection to the same server.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Grab the server.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-See if the property is on the property list of the root window for the screen.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the desired property is not present:

-<!-- .RS -->

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Create a colormap (unless you are using the default colormap of the screen).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Determine the color characteristics of the visual.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Allocate cells in the colormap (or create it with

-<symbol>AllocAll</symbol>).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Call 

-<function>XStoreColors</function>

-to store appropriate color values in the colormap.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Fill in the descriptive members in the 

-<structname>XStandardColormap</structname>

-structure.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Attach the property to the root window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Use

-<function>XSetCloseDownMode</function>

-to make the resource permanent.

-<!-- .RE -->

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Ungrab the server.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-<function>XSetRGBColormaps</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadAtom</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To obtain the 

-<structname>XStandardColormap</structname>

-structure associated with the specified property, use

-<function>XGetRGBColormaps</function>.

-<indexterm significance="preferred"><primary>XGetRGBColormaps</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetRGBColormaps</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XStandardColormap<parameter> **std_colormap_return</parameter></paramdef>

-  <paramdef>int<parameter> *count_return</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>std_colormap_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the

-<structname>XStandardColormap</structname>

-structure.

-<!-- .ds Cn colormaps -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of (Cn.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XGetRGBColormaps</function>

-function returns the <acronym>RGB</acronym> colormap definitions stored 

-in the specified property on the named window.

-If the property exists, is of type RGB_COLOR_MAP, is of format 32, 

-and is long enough to contain a colormap definition,

-<function>XGetRGBColormaps</function>

-allocates and fills in space for the returned colormaps

-and returns a nonzero status.

-If the visualid is not present, 

-<function>XGetRGBColormaps</function>

-assumes the default visual for the screen on which the window is located; 

-if the killid is not present, 

-<symbol>None</symbol>

-is assumed, which indicates that the resources cannot be released.

-Otherwise, 

-none of the fields are set, and 

-<function>XGetRGBColormaps</function>

-returns a zero status.

-Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>

-restriction that only RGB_DEFAULT_MAP contain more than one definition.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetRGBColormaps</function>

-can generate

-<errorname>BadAtom</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-<!-- .bp -->

-

-</para>

-</sect2>

-</sect1>

-</chapter>

+<?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="inter_client_communication_functions">
+<title>Inter-Client Communication Functions</title>
+<para>
+The Inter-Client Communication Conventions Manual, hereafter referred to as the <acronym>ICCCM</acronym>,
+details the X Consortium approved conventions that govern inter-client communications. These
+conventions ensure peer-to-peer client cooperation in the use of selections, cut buffers, and shared
+resources as well as client cooperation with window and session managers. For further information,
+see the Inter-Client Communication Conventions Manual.
+</para>
+<para>
+Xlib provides a number of standard properties and programming interfaces that are <acronym>ICCCM</acronym>
+compliant. The predefined atoms for some of these properties are defined in the &lt;X11/Xatom.h&gt;
+header file, where to avoid name conflicts with user symbols their #define name has an XA_ prefix.
+For further information about atoms and properties, see section 4.3.
+</para>
+<para>
+Xlib’s selection and cut buffer mechanisms provide the primary programming interfaces by which
+peer client applications communicate with each other (see sections 4.5 and 16.6). The functions
+discussed in this chapter provide the primary programming interfaces by which client applications
+communicate with their window and session managers as well as share standard colormaps.
+</para>
+<para>
+The standard properties that are of special interest for communicating with window and session
+managers are:
+</para>
+
+<informaltable>
+  <tgroup cols='4' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <colspec colname='c4'/>
+  <thead>
+    <row>
+      <entry>Name</entry>
+      <entry>Type</entry>
+      <entry>Format</entry>
+      <entry>Description</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry><property>WM_CLASS</property></entry>
+      <entry>STRING</entry>
+      <entry>8</entry>
+      <entry>Set by application programs to allow
+      window and session managers to
+      obtain the application’s resources
+      from the resource database.
+      </entry>
+    </row>
+    <row>
+      <entry><property>WM_CLIENT_MACHINE</property></entry>
+      <entry>TEXT</entry>
+      <entry></entry>
+      <entry>The string name of the machine on
+      which the client application is running.
+      </entry>
+    </row>
+    <row>
+      <entry><property>WM_COLORMAP_WINDOWS</property></entry>
+      <entry>WINDOWS</entry>
+      <entry>32</entry>
+      <entry>The list of window IDs that may
+      need a different colormap from that
+      of their top-level window.
+      </entry>
+    </row>
+    <row>
+      <entry><property>WM_COMMAND</property></entry>
+      <entry>TEXT</entry>
+      <entry></entry>
+      <entry>The command and arguments, null
+      separated, used to invoke the application.
+      </entry>
+    </row>
+    <row>
+      <entry><property>WM_HINTS</property></entry>
+      <entry><property>WM_HINTS</property></entry>
+      <entry>32</entry>
+      <entry>Additional hints set by the client for
+      use by the window manager. The C
+      type of this property is XWMHints.
+      </entry> 
+    </row>
+    <row>
+      <entry><property>WM_ICON_NAME</property></entry>
+      <entry>TEXT</entry>
+      <entry></entry>
+      <entry>The name to be used in an icon.</entry>
+    </row>
+    <row>
+      <entry><property>WM_ICON_SIZE</property></entry>
+      <entry><property>WM_ICON_SIZE</property></entry>
+      <entry>32</entry>
+      <entry>The window manager may set this
+      property on the root window to
+      specify the icon sizes it supports.
+      The C type of this property is
+      XIconSize.
+      </entry>
+    </row>
+    <row>
+      <entry><property>WM_NAME</property></entry>
+      <entry>TEXT</entry>
+      <entry></entry>
+      <entry>The name of the application.</entry>
+    </row>
+    <row>
+      <entry><property>WM_NORMAL_HINTS</property></entry>
+      <entry><property>WM_NORMAL_HINTS</property></entry>
+      <entry>32</entry>
+      <entry>Size hints for a window in its
+      normal state. The C type of this
+      property is XSizeHints.
+      </entry>
+    </row>
+    <row>
+      <entry><property>WM_PROTOCOLS</property></entry>
+      <entry>ATOM</entry>
+      <entry>32</entry>
+      <entry>List of atoms that identify the 
+      communications protocols between the
+      client and window manager in
+      which the client is willing to participate.
+      </entry>
+    </row>
+    <row>
+      <entry><property>WM_STATE</property></entry>
+      <entry><property>WM_STATE</property></entry>
+      <entry>32</entry>
+      <entry>Intended for communication
+      between window and session managers only.
+      </entry>
+    </row>
+    <row>
+      <entry><property>WM_TRANSIENT_FOR</property></entry>
+      <entry>WINDOW</entry>
+      <entry>32</entry>
+      <entry>Set by application programs to 
+      indicate to the window manager that a
+      transient top-level window, such as a
+      dialog box.
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+The remainder of this chapter discusses:
+</para>
+
+<itemizedlist>
+  <listitem><para>Client to window manager communication</para></listitem>
+  <listitem><para>Client to session manager communication</para></listitem>
+  <listitem><para>Standard colormaps</para></listitem>
+</itemizedlist>
+
+<sect1 id="Client_to_Window_Manager_Communication">
+<title>Client to Window Manager Communication</title>
+<!-- .XS -->
+<!-- (SN Client to Window Manager Communication -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Manipulate top-level windows
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Convert string lists
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read text properties
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_NAME</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_ICON_NAME</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_HINTS</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_NORMAL_HINTS</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_CLASS</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_TRANSIENT_FOR</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_PROTOCOLS</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_COLORMAP_WINDOWS</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_ICON_SIZE</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Use window manager convenience functions
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Manipulating_Top_Level_Windows">
+<title>Manipulating Top-Level Windows</title>
+<!-- .XS -->
+<!-- (SN Manipulating Top-Level Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to change the visibility or size
+of top-level windows (that is, those that were created as children 
+of the root window).
+Note that the subwindows that you create are ignored by window managers.
+Therefore,
+you should use the basic window functions described in chapter 3
+to manipulate your application's subwindows.
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be iconified, use
+<function>XIconifyWindow</function>.
+<indexterm significance="preferred"><primary>XIconifyWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xiconifywindow'>
+<funcprototype>
+  <funcdef>Status <function>XIconifyWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the appropriate screen number on the host server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XIconifyWindow</function>
+function sends a <property>WM_CHANGE_STATE</property> 
+<symbol>ClientMessage</symbol>
+event with a format of 32 and a first data element of 
+<symbol>IconicState</symbol>
+(as described in section 4.1.4 of the 
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>)
+and a window of w
+to the root window of the specified screen
+with an event mask set to
+<symbol>SubstructureNotifyMask</symbol> |
+<symbol>SubstructureRedirectMask</symbol>.
+Window managers may elect to receive this message and
+if the window is in its normal state, 
+may treat it as a request to change the window's state from normal to iconic.
+If the <property>WM_CHANGE_STATE</property> property cannot be interned, 
+<function>XIconifyWindow</function>
+does not send a message and returns a zero status.
+It returns a nonzero status if the client message is sent successfully;
+otherwise, it returns a zero status.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be withdrawn, use
+<function>XWithdrawWindow</function>.
+<indexterm significance="preferred"><primary>XWithdrawWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xwithdrawwindow'>
+<funcprototype>
+  <funcdef>Status <function>XWithdrawWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the appropriate screen number on the host server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XWithdrawWindow</function>
+function unmaps the specified window 
+and sends a synthetic 
+<symbol>UnmapNotify</symbol>
+event to the root window of the specified screen.
+Window managers may elect to receive this message 
+and may treat it as a request to change the window's state to withdrawn.
+When a window is in the withdrawn state, 
+neither its normal nor its iconic representations is visible.
+It returns a nonzero status if the 
+<symbol>UnmapNotify</symbol>
+event is successfully sent; 
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XWithdrawWindow</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be reconfigured, use
+<function>XReconfigureWMWindow</function>.
+<indexterm significance="preferred"><primary>XReconfigureWMWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xreconfigurewmwindow'>
+<funcprototype>
+  <funcdef>Status <function>XReconfigureWMWindow</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> screen_number</parameter></paramdef>
+  <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>
+  <paramdef>XWindowChanges<parameter> *values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen_number</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the appropriate screen number on the host server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies which values are to be set using information in
+the values structure.
+This mask is the bitwise inclusive OR of the valid configure window values bits.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>values</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XWindowChanges</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XReconfigureWMWindow</function>
+function issues a 
+<systemitem>ConfigureWindow</systemitem>
+request on the specified top-level window.
+If the stacking mode is changed and the request fails with a 
+<errorname>BadMatch</errorname>
+error, 
+the error is trapped by Xlib and a synthetic 
+<systemitem class="event">ConfigureRequestEvent</systemitem>
+containing the same configuration parameters is sent to the root 
+of the specified window.
+Window managers may elect to receive this event 
+and treat it as a request to reconfigure the indicated window.
+It returns a nonzero status if the request or event is successfully sent;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XReconfigureWMWindow</function>
+can generate
+<errorname>BadValue</errorname>
+and 
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Converting_String_Lists">
+<title>Converting String Lists</title>
+<!-- .XS -->
+<!-- (SN Converting String Lists -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Many of the text properties allow a variety of types and formats.
+Because the data stored in these properties are not
+simple null-terminated strings, an
+<structname>XTextProperty</structname>
+structure is used to describe the encoding, type, and length of the text 
+as well as its value.
+The
+<structname>XTextProperty</structname>
+structure contains:
+<indexterm significance="preferred"><primary>XTextProperty</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	unsigned char *value;	/* property data */
+	Atom encoding;	/* type of property */
+	int format;	/* 8, 16, or 32 */
+	unsigned long nitems;	/* number of items in value */
+} XTextProperty;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Xlib provides functions to convert localized text to or from encodings
+that support the inter-client communication conventions for text.
+In addition, functions are provided for converting between lists of pointers 
+to character strings and text properties in the STRING encoding.
+</para>
+<para>
+<!-- .LP -->
+The functions for localized text return a signed integer error status 
+that encodes 
+<symbol>Success</symbol>
+as zero, specific error conditions as negative numbers, and partial conversion
+as a count of unconvertible characters.
+</para>
+
+<literallayout class="monospaced">
+
+#define #XNoMemory           -1
+#define #XLocaleNotSupported -2
+#define #XConverterNotFound  -3
+
+typedef enum {
+	XStringStyle,		/* STRING */
+	XCompoundTextStyle,	/* COMPOUND_TEXT */
+	XTextStyle,		/* text in owner's encoding (current locale) */
+	XStdICCTextStyle	/* STRING, else COMPOUND_TEXT */
+} XICCEncodingStyle;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To convert a list of text strings to an 
+<structname>XTextProperty</structname>
+structure, use
+<function>XmbTextListToTextProperty</function>
+or
+<function>XwcTextListToTextProperty</function>.
+<indexterm significance="preferred"><primary>XmbTextListToTextProperty</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextListToTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbtextlisttotextproperty'>
+<funcprototype>
+  <funcdef>int <function>XmbTextListToTextProperty</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> **list</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+  <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwctextlisttotextproperty'>
+<funcprototype>
+  <funcdef>int <function>XwcTextListToTextProperty</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>wchar_t<parameter> **list</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+  <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a list of null-terminated character strings.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of strings specified.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>style</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the manner in which the property is encoded.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the
+<structname>XTextProperty</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextListToTextProperty</function>
+and
+<function>XwcTextListToTextProperty</function>
+functions set the specified 
+<structname>XTextProperty</structname>
+value to a set of null-separated elements representing the concatenation
+of the specified list of null-terminated text strings.
+A final terminating null is stored at the end of the value field 
+of text_prop_return but is not included in the nitems member.
+</para>
+<para>
+<!-- .LP -->
+The functions set the encoding field of text_prop_return to an
+<type>Atom</type>
+for the specified display 
+naming the encoding determined by the specified style
+and convert the specified text list to this encoding for storage in
+the text_prop_return value field.
+If the style 
+<constant>XStringStyle</constant>
+or 
+<constant>XCompoundTextStyle</constant>
+is specified,
+this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
+If the style 
+<constant>XTextStyle</constant>
+is specified,
+this encoding is the encoding of the current locale.
+If the style 
+<constant>XStdICCTextStyle</constant>
+is specified,
+this encoding is ``STRING'' if the text is fully convertible to STRING,
+else ``COMPOUND_TEXT''.
+</para>
+<para>
+<!-- .LP -->
+If insufficient memory is available for the new value string,
+the functions return 
+<symbol>XNoMemory</symbol>.
+If the current locale is not supported,
+the functions return 
+<symbol>XLocaleNotSupported</symbol>.
+In both of these error cases,
+the functions do not set text_prop_return.
+</para>
+<para>
+<!-- .LP -->
+To determine if the functions are guaranteed not to return
+<symbol>XLocaleNotSupported</symbol>,
+use
+<function>XSupportsLocale</function>.
+</para>
+<para>
+<!-- .LP -->
+If the supplied text is not fully convertible to the specified encoding,
+the functions return the number of unconvertible characters.
+Each unconvertible character is converted to an implementation-defined and
+encoding-specific default string.
+Otherwise, the functions return 
+<symbol>Success</symbol>.
+Note that full convertibility to all styles except 
+<constant>XStringStyle</constant>
+is guaranteed.
+</para>
+<para>
+<!-- .LP -->
+To free the storage for the value field, use
+<function>XFree</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a list of text strings from an 
+<structname>XTextProperty</structname>
+structure, use
+<function>XmbTextPropertyToTextList</function>
+or
+<function>XwcTextPropertyToTextList</function>.
+<indexterm significance="preferred"><primary>XmbTextPropertyToTextList</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextPropertyToTextList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbtextpropertytotextlist'>
+<funcprototype>
+  <funcdef>int <function>XmbTextPropertyToTextList</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+  <paramdef>char<parameter> ***list_return</parameter></paramdef>
+  <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwctextpropertytotextlist'>
+<funcprototype>
+  <funcdef>int <function>XwcTextPropertyToTextList</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+  <paramdef>wchar_t<parameter> ***list_return</parameter></paramdef>
+  <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XTextProperty</structname>
+structure to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of (Cn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XmbTextPropertyToTextList</function>
+and 
+<function>XwcTextPropertyToTextList</function>
+functions return a list of text strings in the current locale representing the
+null-separated elements of the specified
+<structname>XTextProperty</structname>
+structure.
+The data in text_prop must be format 8.
+</para>
+<para>
+<!-- .LP -->
+Multiple elements of the property (for example, the strings in a disjoint
+text selection) are separated by a null byte.
+The contents of the property are not required to be null-terminated;
+any terminating null should not be included in text_prop.nitems.
+</para>
+<para>
+<!-- .LP -->
+If insufficient memory is available for the list and its elements,
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return 
+<symbol>XNoMemory</symbol>.
+If the current locale is not supported,
+the functions return
+<symbol>XLocaleNotSupported</symbol>.
+Otherwise, if the encoding field of text_prop is not convertible 
+to the encoding of the current locale,
+the functions return
+<symbol>XConverterNotFound</symbol>.
+For supported locales,
+existence of a converter from COMPOUND_TEXT, STRING
+or the encoding of the current locale is guaranteed if
+<function>XSupportsLocale</function>
+returns 
+<symbol>True</symbol>
+for the current locale (but the actual text
+may contain unconvertible characters).
+Conversion of other encodings is implementation-dependent.
+In all of these error cases,
+the functions do not set any return values.
+</para>
+<para>
+<!-- .LP -->
+Otherwise, 
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return the list of null-terminated text strings to list_return
+and the number of text strings to count_return.
+</para>
+<para>
+<!-- .LP -->
+If the value field of text_prop is not fully convertible to the encoding of
+the current locale,
+the functions return the number of unconvertible characters.
+Each unconvertible character is converted to a string in the
+current locale that is specific to the current locale.
+To obtain the value of this string, 
+use
+<function>XDefaultString</function>.
+Otherwise,
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return 
+<symbol>Success</symbol>.
+</para>
+<para>
+<!-- .LP -->
+To free the storage for the list and its contents returned by
+<function>XmbTextPropertyToTextList</function>,
+use
+<function>XFreeStringList</function>.
+To free the storage for the list and its contents returned by
+<function>XwcTextPropertyToTextList</function>,
+use
+<function>XwcFreeStringList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To free the in-memory data associated with the specified
+wide character string list, use
+<function>XwcFreeStringList</function>.
+<indexterm significance="preferred"><primary>XwcFreeStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xwcfreestringlist'>
+<funcprototype>
+  <funcdef>void <function>XwcFreeStringList</function></funcdef>
+  <paramdef>wchar_t<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the list of strings to be freed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XwcFreeStringList</function>
+function frees memory allocated by
+<function>XwcTextPropertyToTextList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the default string for text conversion in the current locale,
+use</para>
+
+<para>char *XDefaultString()</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDefaultString</function>
+function returns the default string used by Xlib for text conversion
+(for example, in 
+<function>XmbTextPropertyToTextList</function>).
+The default string is the string in the current locale that is output 
+when an unconvertible character is found during text conversion.
+If the string returned by
+<function>XDefaultString</function>
+is the empty string (""),
+no character is output in the converted text.
+<function>XDefaultString</function>
+does not return NULL.
+</para>
+<para>
+<!-- .LP -->
+The string returned by 
+<function>XDefaultString</function>
+is independent of the default string for text drawing;
+see 
+<function>XCreateFontSet</function>
+to obtain the default string for an
+<type>XFontSet</type>.
+</para>
+<para>
+<!-- .LP -->
+The behavior when an invalid codepoint is supplied to any Xlib function is
+undefined.
+</para>
+<para>
+<!-- .LP -->
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It may be freed after the current locale is changed.
+Until freed, it will not be modified by Xlib.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the specified list of strings in the STRING encoding to a 
+<structname>XTextProperty</structname>
+structure, use
+<function>XStringListToTextProperty</function>.
+<indexterm significance="preferred"><primary>XStringListToTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xstringlisttotextproperty'>
+<funcprototype>
+  <funcdef>Status <function>XStringListToTextProperty</function></funcdef>
+  <paramdef>char<parameter> **list</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of (Cn.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the
+<structname>XTextProperty</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XStringListToTextProperty</function>
+function sets the specified 
+<structname>XTextProperty</structname>
+to be of type STRING (format 8) with a value representing the
+concatenation of the specified list of null-separated character strings.
+An extra null byte (which is not included in the nitems member) 
+is stored at the end of the value field of text_prop_return.
+The strings are assumed (without verification) to be in the STRING encoding.
+If insufficient memory is available for the new value string, 
+<function>XStringListToTextProperty</function>
+does not set any fields in the
+<structname>XTextProperty</structname>
+structure and returns a zero status.
+Otherwise, it returns a nonzero status.
+To free the storage for the value field, use 
+<function>XFree</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a list of strings from a specified
+<structname>XTextProperty</structname>
+structure in the STRING encoding, use
+<function>XTextPropertyToStringList</function>.
+<indexterm significance="preferred"><primary>XTextPropertyToStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xtextpropertytostringlist'>
+<funcprototype>
+  <funcdef>Status <function>XTextPropertyToStringList</function></funcdef>
+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+  <paramdef>char<parameter> ***list_return</parameter></paramdef>
+  <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XTextProperty</structname>
+structure to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of (Cn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XTextPropertyToStringList</function>
+function returns a list of strings representing the null-separated elements 
+of the specified
+<structname>XTextProperty</structname>
+structure.
+The data in text_prop must be of type STRING and format 8. 
+Multiple elements of the property 
+(for example, the strings in a disjoint text selection) 
+are separated by NULL (encoding 0).
+The contents of the property are not null-terminated.
+If insufficient memory is available for the list and its elements, 
+<function>XTextPropertyToStringList</function>
+sets no return values and returns a zero status.
+Otherwise, it returns a nonzero status.
+To free the storage for the list and its contents, use 
+<function>XFreeStringList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To free the in-memory data associated with the specified string list, use
+<function>XFreeStringList</function>.
+<indexterm significance="preferred"><primary>XFreeStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreestringlist'>
+<funcprototype>
+  <funcdef>void <function>XFreeStringList</function></funcdef>
+  <paramdef>char<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the list of strings to be freed.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XFreeStringList</function>
+function releases memory allocated by 
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XTextPropertyToStringList</function>
+and the missing charset list allocated by 
+<function>XCreateFontSet</function>.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_Text_Properties">
+<title>Setting and Reading Text Properties</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading Text Properties -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides two functions that you can use to set and read
+the text properties for a given window.
+You can use these functions to set and read those properties of type TEXT
+(<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property>).
+In addition,
+Xlib provides separate convenience functions that you can use to set each 
+of these properties.
+For further information about these convenience functions,
+see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set one of a window's text properties, use
+<function>XSetTextProperty</function>.
+<indexterm significance="preferred"><primary>XSetTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsettextproperty'>
+<funcprototype>
+  <funcdef>void <function>XSetTextProperty</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XTextProperty</structname>
+structure to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetTextProperty</function>
+function replaces the existing specified property for the named window 
+with the data, type, format, and number of items determined 
+by the value field, the encoding field, the format field, 
+and the nitems field, respectively, of the specified
+<structname>XTextProperty</structname>
+structure.
+If the property does not already exist,
+<function>XSetTextProperty</function>
+sets it for the specified window.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTextProperty</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadAtom</errorname>,
+<errorname>BadValue</errorname>,
+and 
+<errorname>BadWindow</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read one of a window's text properties, use
+<function>XGetTextProperty</function>.
+<indexterm significance="preferred"><primary>XGetTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgettextproperty'>
+<funcprototype>
+  <funcdef>Status <function>XGetTextProperty</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the
+<structname>XTextProperty</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetTextProperty</function>
+function reads the specified property from the window
+and stores the data in the returned
+<structname>XTextProperty</structname>
+structure.
+It stores the data in the value field,
+the type of the data in the encoding field,
+the format of the data in the format field, 
+and the number of items of data in the nitems field.
+An extra byte containing null (which is not included in the nitems member) 
+is stored at the end of the value field of text_prop_return.
+The particular interpretation of the property's encoding 
+and data as text is left to the calling application.
+If the specified property does not exist on the window,
+<function>XGetTextProperty</function>
+sets the value field to NULL, 
+the encoding field to
+<symbol>None</symbol>,
+the format field to zero, 
+and the nitems field to zero.
+</para>
+<para>
+<!-- .LP -->
+If it was able to read and store the data in the
+<structname>XTextProperty</structname>
+structure,
+<function>XGetTextProperty</function>
+returns a nonzero status; 
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetTextProperty</function>
+can generate
+<errorname>BadAtom</errorname>
+and 
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_NAME_Property">
+<title>Setting and Reading the WM_NAME Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_NAME Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides convenience functions that you can use to set and read 
+the <property>WM_NAME</property> property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's <property>WM_NAME</property> property with the supplied convenience function, use
+<function>XSetWMName</function>.
+<indexterm significance="preferred"><primary>XSetWMName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmname'>
+<funcprototype>
+  <funcdef>void <function>XSetWMName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XTextProperty</structname>
+structure to be used.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMName</function>
+convenience function calls
+<function>XSetTextProperty</function>
+to set the <property>WM_NAME</property> property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's <property>WM_NAME</property> property with the supplied convenience function, use
+<function>XGetWMName</function>.
+<indexterm significance="preferred"><primary>XGetWMName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetwmname'>
+<funcprototype>
+  <funcdef>Status <function>XGetWMName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the
+<structname>XTextProperty</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMName</function>
+convenience function calls
+<function>XGetTextProperty</function>
+to obtain the <property>WM_NAME</property> property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+The following two functions have been superseded by
+<function>XSetWMName</function>
+and
+<function>XGetWMName</function>,
+respectively. 
+You can use these additional convenience functions 
+for window names that are encoded as STRING properties.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To assign a name to a window, use
+<function>XStoreName</function>.
+<indexterm><primary>Window</primary><secondary>name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xstorename'>
+<funcprototype>
+  <funcdef><function>XStoreName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>char<parameter> *window_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>window_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window name,
+which should be a null-terminated string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStoreName</function>
+function assigns the name passed to window_name to the specified window.
+A window manager can display the window name in some prominent
+place, such as the title bar, to allow users to identify windows easily.
+Some window managers may display a window's name in the window's icon,
+although they are encouraged to use the window's icon name
+if one is provided by the application.
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreName</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the name of a window, use
+<function>XFetchName</function>.
+<indexterm significance="preferred"><primary>XFetchName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfetchname'>
+<funcprototype>
+  <funcdef>Status <function>XFetchName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>char<parameter> **window_name_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>window_name_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the window name, which is a null-terminated string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFetchName</function>
+function returns the name of the specified window.
+If it succeeds,
+it returns a nonzero status; 
+otherwise, no name has been set for the window,
+and it returns zero.
+If the <property>WM_NAME</property> property has not been set for this window,
+<function>XFetchName</function>
+sets window_name_return to NULL.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+When finished with it, a client must free
+the window name string using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XFetchName</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_ICON_NAME_Property">
+<title>Setting and Reading the WM_ICON_NAME Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_ICON_NAME Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides convenience functions that you can use to set and read 
+the <property>WM_ICON_NAME</property> property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's <property>WM_ICON_NAME</property> property,
+use
+<function>XSetWMIconName</function>.
+<indexterm significance="preferred"><primary>XSetWMIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmiconname'>
+<funcprototype>
+  <funcdef>void <function>XSetWMIconName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XTextProperty</structname>
+structure to be used.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMIconName</function>
+convenience function calls
+<function>XSetTextProperty</function>
+to set the <property>WM_ICON_NAME</property> property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's <property>WM_ICON_NAME</property> property,
+use
+<function>XGetWMIconName</function>.
+<indexterm significance="preferred"><primary>XGetWMIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetwmiconname'>
+<funcprototype>
+  <funcdef>Status <function>XGetWMIconName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the
+<structname>XTextProperty</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetWMIconName</function>
+convenience function calls
+<function>XGetTextProperty</function>
+to obtain the <property>WM_ICON_NAME</property> property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+The next two functions have been superseded by
+<function>XSetWMIconName</function>
+and
+<function>XGetWMIconName</function>,
+respectively.
+You can use these additional convenience functions 
+for window names that are encoded as STRING properties.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the name to be displayed in a window's icon, use
+<function>XSetIconName</function>.
+<indexterm><primary>Window</primary><secondary>icon name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSetIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xseticonname'>
+<funcprototype>
+  <funcdef><function>XSetIconName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>char<parameter> *icon_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>icon_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the icon name,
+which should be a null-terminated string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+<function>XSetIconName</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the name a window wants displayed in its icon, use
+<function>XGetIconName</function>.
+<indexterm significance="preferred"><primary>XGetIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeticonname'>
+<funcprototype>
+  <funcdef>Status <function>XGetIconName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>char<parameter> **icon_name_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>icon_name_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the window's icon name,
+which is a null-terminated string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetIconName</function>
+function returns the name to be displayed in the specified window's icon.
+If it succeeds, it returns a nonzero status; otherwise, 
+if no icon name has been set for the window,
+it returns zero.
+If you never assigned a name to the window,
+<function>XGetIconName</function>
+sets icon_name_return to NULL.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+When finished with it, a client must free
+the icon name string using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetIconName</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_HINTS_Property">
+<title>Setting and Reading the WM_HINTS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_HINTS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read 
+the <property>WM_HINTS</property> property for a given window.
+These functions use the flags and the
+<structname>XWMHints</structname>
+structure, as defined in the
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<structname>XWMHints</structname>
+structure, use
+<function>XAllocWMHints</function>.
+</para>
+
+<para>
+  XWMHints *XAllocWMHints()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocWMHints</function>
+function allocates and returns a pointer to an
+<structname>XWMHints</structname>
+structure.
+Note that all fields in the
+<structname>XWMHints</structname>
+structure are initially set to zero.
+If insufficient memory is available, 
+<function>XAllocWMHints</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XWMHints</structname>
+structure contains:
+</para>
+
+<literallayout class="monospaced">
+/* Window manager hints mask bits */
+
+#define         InputHint             (1L&lt;&lt;0)
+#define         StateHint             (1L&lt;&lt;1)
+#define         IconPixmapHint        (1L&lt;&lt;2)
+#define         IconWindowHint        (1L&lt;&lt;3)
+#define         IconPositionHint      (1L&lt;&lt;4)
+#define         IconMaskHint          (1L&lt;&lt;5)
+#define         WindowGroupHint       (1L&lt;&lt;6)
+#define         UrgencyHint           (1L&lt;&lt;8)
+#define         AllHints              (InputHint|StateHint|IconPixmapHint|
+                                       IconWIndowHint|IconPositionHint|
+                                       IconMaskHint|WindowGroupHint)
+
+
+/* Values */
+
+typedef struct {
+	long flags;	        /* marks which fields in this structure are defined */
+	Bool input;	        /* does this application rely on the window manager to
+			           get keyboard input? */
+	int initial_state;	/* see below */
+	Pixmap icon_pixmap;	/* pixmap to be used as icon */
+	Window icon_window;	/* window to be used as icon */
+	int icon_x, icon_y;	/* initial position of icon */
+	Pixmap icon_mask;	/* pixmap to be used as mask for icon_pixmap */
+	XID window_group;	/* id of related window group */
+	/* this structure may be extended in the future */
+} XWMHints;
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The input member is used to communicate to the window manager the input focus
+model used by the application.
+Applications that expect input but never explicitly set focus to any 
+of their subwindows (that is, use the push model of focus management), 
+such as X Version 10 style applications that use real-estate
+driven focus, should set this member to 
+<symbol>True</symbol>.
+Similarly, applications
+that set input focus to their subwindows only when it is given to their
+top-level window by a window manager should also set this member to 
+<symbol>True</symbol>.
+Applications that manage their own input focus by explicitly setting
+focus to one of their subwindows whenever they want keyboard input 
+(that is, use the pull model of focus management) should set this member to 
+<symbol>False</symbol>.
+Applications that never expect any keyboard input also should set this member
+to 
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+Pull model window managers should make it possible for push model
+applications to get input by setting input focus to the top-level windows of
+applications whose input member is 
+<symbol>True</symbol>.
+Push model window managers should
+make sure that pull model applications do not break them 
+by resetting input focus to 
+<symbol>PointerRoot</symbol>
+when it is appropriate (for example, whenever an application whose
+input member is 
+<symbol>False</symbol>
+sets input focus to one of its subwindows).
+</para>
+<para>
+<!-- .LP -->
+The definitions for the initial_state flag are:
+</para>
+
+<literallayout class="monospaced">
+#define      WithdrawnState 0
+#define      NormalState    1   /* most applications start this way */
+#define      IconicState    2   /* application wants to start as an icon */
+
+</literallayout>
+<para>
+The icon_mask specifies which pixels of the icon_pixmap should be used as the
+icon.  
+This allows for nonrectangular icons.
+Both icon_pixmap and icon_mask must be bitmaps.
+The icon_window lets an application provide a window for use as an icon
+for window managers that support such use.
+The window_group lets you specify that this window belongs to a group
+of other windows.
+For example, if a single application manipulates multiple 
+top-level windows, this allows you to provide enough
+information that a window manager can iconify all of the windows
+rather than just the one window.
+</para>
+<para>
+<!-- .LP -->
+The
+<symbol>UrgencyHint</symbol>
+flag, if set in the flags field, indicates that the client deems the window
+contents to be urgent, requiring the timely response of the user.  The
+window manager will make some effort to draw the user's attention to this
+window while this flag is set.  The client must provide some means by which the
+user can cause the urgency flag to be cleared (either mitigating
+the condition that made the window urgent or merely shutting off the alarm)
+or the window to be withdrawn.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's <property>WM_HINTS</property> property, use
+<function>XSetWMHints</function>.
+<indexterm significance="preferred"><primary>XSetWMHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmhints'>
+<funcprototype>
+  <funcdef><function>XSetWMHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XWMHints<parameter> *wmhints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>wmhints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<structname>XWMHints</structname>
+structure to be used.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMHints</function>
+function sets the window manager hints that include icon information and location,
+the initial state of the window, and whether the application relies on the
+window manager to get keyboard input.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMHints</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's <property>WM_HINTS</property> property, use
+<function>XGetWMHints</function>.
+<indexterm significance="preferred"><primary>XGetWMHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetwmhints'>
+<funcprototype>
+  <funcdef>XWMHints *<function>XGetWMHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMHints</function>
+function reads the window manager hints and 
+returns NULL if no <property>WM_HINTS</property> property was set on the window 
+or returns a pointer to an 
+<structname>XWMHints</structname>
+structure if it succeeds.
+When finished with the data,
+free the space used for it by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMHints</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">
+<title>Setting and Reading the WM_NORMAL_HINTS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_NORMAL_HINTS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set or read 
+the <property>WM_NORMAL_HINTS</property> property for a given window.
+The functions use the flags and the
+<structname>XSizeHints</structname>
+structure, as defined in the
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+header file.
+</para>
+<para>
+<!-- .LP -->
+The size of the
+<structname>XSizeHints</structname>
+structure may grow in future releases, as new components are
+added to support new <acronym>ICCCM</acronym> features.
+Passing statically allocated instances of this structure into
+Xlib may result in memory corruption when running against a
+future release of the library.
+As such, it is recommended that only dynamically allocated
+instances of the structure be used.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<structname>XSizeHints</structname>
+structure, use
+<function>XAllocSizeHints</function>.
+</para>
+
+<para>
+XSizeHints *XAllocSizeHints()
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocSizeHints</function>
+function allocates and returns a pointer to an
+<structname>XSizeHints</structname>
+structure.
+Note that all fields in the
+<structname>XSizeHints</structname>
+structure are initially set to zero.
+If insufficient memory is available, 
+<function>XAllocSizeHints</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XSizeHints</structname>
+structure contains:
+</para>
+
+
+<literallayout class="monospaced">
+/* Size hints mask bits */
+
+#define           USPosition         (1L&lt;&lt;0)  /* user specified x,y */
+#define           USSize             (1L&lt;&lt;1)  /* user specified width,height */
+#define           PPosition          (1L&lt;&lt;2)  /* program specified posistion */
+#define           PSize              (1L&lt;&lt;3)  /* program specified size */
+#define           PMinSize           (1L&lt;&lt;4)  /* program specified minimum size */
+#define           PMaxSize           (1L&lt;&lt;5)  /* program specified maximum size */
+#define           PResizeInc         (1L&lt;&lt;5)  /* program specified resize increments */
+#define           PAspect            (1L&lt;&lt;6)  /* program specified min and max aspect ratios */
+#define           PBaseSize          (1L&lt;&lt;8)
+#define           PWinGravity        (1L&lt;&lt;9)
+#define           PAllHints          (PPosition|Psize|
+                                      PMinSize|PMaxSize|
+                                      PResizeInc|PAspect)
+
+
+/* Values */
+
+typedef struct {
+	long flags;	        /* marks which fields in this structure are defined */
+	int x, y;	        /* Obsolete */
+	int width, height;	/* Obsolete */
+	int min_width, min_height;
+	int max_width, max_height;
+	int width_inc, height_inc;
+	struct {
+	       int x;	        /* numerator */
+	       int y;	        /* denominator */
+	} min_aspect, max_aspect;
+	int base_width, base_height;
+	int win_gravity;
+	/* this structure may be extended in the future */
+} XSizeHints;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x, y, width, and height members are now obsolete
+and are left solely for compatibility reasons.
+The min_width and min_height members specify the
+minimum window size that still allows the application to be useful.
+The max_width and max_height members specify the maximum window size.
+The width_inc and height_inc members define an arithmetic progression of
+sizes (minimum to maximum) into which the window prefers to be resized.
+The min_aspect and max_aspect members are expressed
+as ratios of x and y, 
+and they allow an application to specify the range of aspect
+ratios it prefers.
+The base_width and base_height members define the desired size of the window.
+The window manager will interpret the position of the window 
+and its border width to position the point of the outer rectangle 
+of the overall window specified by the win_gravity member.
+The outer rectangle of the window includes any borders or decorations
+supplied by the window manager.
+In other words,
+if the window manager decides to place the window where the client asked,
+the position on the parent window's border named by the win_gravity 
+will be placed where the client window would have been placed 
+in the absence of a window manager.
+</para>
+<para>
+<!-- .LP -->
+Note that use of the
+<symbol>PAllHints</symbol>
+macro is highly discouraged.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's <property>WM_NORMAL_HINTS</property> property, use
+<function>XSetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XSetWMNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmnormalhints'>
+<funcprototype>
+  <funcdef>void <function>XSetWMNormalHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size hints for the window in its normal state.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XSetWMNormalHints</function>
+function replaces the size hints for the <property>WM_NORMAL_HINTS</property> property 
+on the specified window.
+If the property does not already exist,
+<function>XSetWMNormalHints</function>
+sets the size hints for the <property>WM_NORMAL_HINTS</property> property on the specified window.
+The property is stored with a type of <property>WM_SIZE_HINTS</property> and a format of 32.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMNormalHints</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's <property>WM_NORMAL_HINTS</property> property, use
+<function>XGetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XGetWMNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetwmnormalhints'>
+<funcprototype>
+  <funcdef>Status <function>XGetWMNormalHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+  <paramdef>long<parameter> *supplied_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the size hints for the window in its normal state.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>supplied_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the hints that were supplied by the user.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetWMNormalHints</function>
+function returns the size hints stored in the <property>WM_NORMAL_HINTS</property> property 
+on the specified window.
+If the property is of type <property>WM_SIZE_HINTS</property>, is of format 32,
+and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>) 
+or new size hints structure, 
+<function>XGetWMNormalHints</function>
+sets the various fields of the 
+<structname>XSizeHints</structname>
+structure, sets the supplied_return argument to the list of fields 
+that were supplied by the user (whether or not they contained defined values),
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+If 
+<function>XGetWMNormalHints</function>
+returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read, 
+the supplied_return argument will contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(USPosition|USSize|PPosition|PSize|PMinSize|
+ PMaxSize|PResizeInc|PAspect)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If the property is large enough to contain the base size 
+and window gravity fields as well, 
+the supplied_return argument will also contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+PBaseSize|PWinGravity
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMNormalHints</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's <property>WM_SIZE_HINTS</property> property, use
+<function>XSetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XSetWMSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmsizehints'>
+<funcprototype>
+  <funcdef>void <function>XSetWMSizeHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XSizeHints</structname>
+structure to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XSetWMSizeHints</function>
+function replaces the size hints for the specified property 
+on the named window.
+If the specified property does not already exist,
+<function>XSetWMSizeHints</function>
+sets the size hints for the specified property
+on the named window.
+The property is stored with a type of <property>WM_SIZE_HINTS</property> and a format of 32.
+To set a window's normal size hints, 
+you can use the 
+<function>XSetWMNormalHints</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMSizeHints</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadAtom</errorname>,
+and 
+<errorname>BadWindow</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's <property>WM_SIZE_HINTS</property> property, use
+<function>XGetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XGetWMSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetwmsizehints'>
+<funcprototype>
+  <funcdef>Status <function>XGetWMSizeHints</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+  <paramdef>long<parameter> *supplied_return</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the
+<structname>XSizeHints</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>supplied_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the hints that were supplied by the user.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetWMSizeHints</function>
+function returns the size hints stored in the specified property 
+on the named window.
+If the property is of type <property>WM_SIZE_HINTS</property>, is of format 32, 
+and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>) 
+or new size hints structure, 
+<function>XGetWMSizeHints</function>
+sets the various fields of the 
+<structname>XSizeHints</structname>
+structure, sets the supplied_return argument to the
+list of fields that were supplied by the user 
+(whether or not they contained defined values), 
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+To get a window's normal size hints, 
+you can use the 
+<function>XGetWMNormalHints</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+If 
+<function>XGetWMSizeHints</function>
+returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read, 
+the supplied_return argument will contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(USPosition|USSize|PPosition|PSize|PMinSize|
+ PMaxSize|PResizeInc|PAspect)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If the property is large enough to contain the base size 
+and window gravity fields as well, 
+the supplied_return argument will also contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+PBaseSize|PWinGravity
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMSizeHints</function>
+can generate
+<errorname>BadAtom</errorname>
+and 
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_CLASS_Property">
+<title>Setting and Reading the WM_CLASS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_CLASS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and get 
+the <property>WM_CLASS</property> property for a given window.
+These functions use the
+<structname>XClassHint</structname>
+structure, which is defined in the
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<structname>XClassHint</structname>
+structure, use
+<function>XAllocClassHint</function>.
+<indexterm significance="preferred"><primary>XAllocClassHint</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+
+  XClassHint *XAllocClassHint()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocClassHint</function>
+function allocates and returns a pointer to an
+<structname>XClassHint</structname>
+structure.
+Note that the pointer fields in the
+<structname>XClassHint</structname>
+structure are initially set to NULL.
+If insufficient memory is available, 
+<function>XAllocClassHint</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XClassHint</structname>
+contains:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XClassHint</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+	char *res_name;
+	char *res_class;
+} XClassHint;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The res_name member contains the application name, 
+and the res_class member contains the application class. 
+Note that the name set in this property may differ from the name set as <property>WM_NAME</property>.
+That is, <property>WM_NAME</property> specifies what should be displayed in the title bar and,
+therefore, can contain temporal information (for example, the name of
+a file currently in an editor's buffer).
+On the other hand, 
+the name specified as part of <property>WM_CLASS</property> is the formal name of the application
+that should be used when retrieving the application's resources from the 
+resource database.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's <property>WM_CLASS</property> property, use
+<function>XSetClassHint</function>.
+<indexterm significance="preferred"><primary>XSetClassHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetclasshint'>
+<funcprototype>
+  <funcdef><function>XSetClassHint</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class_hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XClassHint</structname>
+structure that is to be used.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetClassHint</function>
+function sets the class hint for the specified window.
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClassHint</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors. 
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's <property>WM_CLASS</property> property, use
+<function>XGetClassHint</function>.
+<indexterm significance="preferred"><primary>XGetClassHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetclasshint'>
+<funcprototype>
+  <funcdef>Status <function>XGetClassHint</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XClassHint<parameter> *class_hints_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class_hints_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the 
+<structname>XClassHint</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetClassHint</function>
+function returns the class hint of the specified window to the members
+of the supplied structure.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+To free res_name and res_class when finished with the strings,
+use
+<function>XFree</function>
+on each individually.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetClassHint</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_TRANSIENT_FOR_Property">
+<title>Setting and Reading the WM_TRANSIENT_FOR Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_TRANSIENT_FOR Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the <property>WM_TRANSIENT_FOR</property> property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's <property>WM_TRANSIENT_FOR</property> property, use
+<function>XSetTransientForHint</function>.
+<indexterm significance="preferred"><primary>XSetTransientForHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsettransientforhint'>
+<funcprototype>
+  <funcdef><function>XSetTransientForHint</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Window<parameter> prop_window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>prop_window</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window that the <property>WM_TRANSIENT_FOR</property> property is to be set to.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetTransientForHint</function>
+function sets the <property>WM_TRANSIENT_FOR</property> property of the specified window to the 
+specified prop_window.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTransientForHint</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's <property>WM_TRANSIENT_FOR</property> property, use
+<function>XGetTransientForHint</function>.
+<indexterm significance="preferred"><primary>XGetTransientForHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgettransientforhint'>
+<funcprototype>
+  <funcdef>Status <function>XGetTransientForHint</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Window<parameter> *prop_window_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>prop_window_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the <property>WM_TRANSIENT_FOR</property> property of the specified window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetTransientForHint</function>
+function returns the <property>WM_TRANSIENT_FOR</property> property for the specified window.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetTransientForHint</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_PROTOCOLS_Property">
+<title>Setting and Reading the WM_PROTOCOLS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_PROTOCOLS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the <property>WM_PROTOCOLS</property> property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's <property>WM_PROTOCOLS</property> property, use
+<function>XSetWMProtocols</function>.
+<indexterm significance="preferred"><primary>XSetWMProtocols</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmprotocols'>
+<funcprototype>
+  <funcdef>Status <function>XSetWMProtocols</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Atom<parameter> *protocols</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>protocols</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the list of protocols.
+<!-- .ds Cn protocols in the list -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of (Cn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XSetWMProtocols</function>
+function replaces the <property>WM_PROTOCOLS</property> property on the specified window 
+with the list of atoms specified by the protocols argument.
+If the property does not already exist,
+<function>XSetWMProtocols</function>
+sets the <property>WM_PROTOCOLS</property> property on the specified window
+to the list of atoms specified by the protocols argument.
+The property is stored with a type of ATOM and a format of 32.
+If it cannot intern the <property>WM_PROTOCOLS</property> atom, 
+<function>XSetWMProtocols</function>
+returns a zero status.
+Otherwise, it returns a nonzero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMProtocols</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's <property>WM_PROTOCOLS</property> property, use
+<function>XGetWMProtocols</function>.
+<indexterm significance="preferred"><primary>XGetWMProtocols</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetwmprotocols'>
+<funcprototype>
+  <funcdef>Status <function>XGetWMProtocols</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Atom<parameter> **protocols_return</parameter></paramdef>
+  <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>protocols_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the list of protocols.
+<!-- .ds Cn protocols in the list -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of (Cn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetWMProtocols</function>
+function returns the list of atoms stored in the <property>WM_PROTOCOLS</property> property 
+on the specified window.
+These atoms describe window manager protocols in which the owner 
+of this window is willing to participate.
+If the property exists, is of type ATOM, is of format 32, 
+and the atom <property>WM_PROTOCOLS</property> can be interned, 
+<function>XGetWMProtocols</function>
+sets the protocols_return argument to a list of atoms, 
+sets the count_return argument to the number of elements in the list, 
+and returns a nonzero status.
+Otherwise, it sets neither of the return arguments
+and returns a zero status.
+To release the list of atoms, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMProtocols</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property">
+<title>Setting and Reading the WM_COLORMAP_WINDOWS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_COLORMAP_WINDOWS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the <property>WM_COLORMAP_WINDOWS</property> property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's <property>WM_COLORMAP_WINDOWS</property> property, use
+<function>XSetWMColormapWindows</function>.
+<indexterm significance="preferred"><primary>XSetWMColormapWindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmcolormapwindows'>
+<funcprototype>
+  <funcdef>Status <function>XSetWMColormapWindows</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Window<parameter> *colormap_windows</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap_windows</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the list of windows.
+<!-- .ds Cn windows in the list -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of (Cn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XSetWMColormapWindows</function>
+function replaces the <property>WM_COLORMAP_WINDOWS</property> property on the specified
+window with the list of windows specified by the colormap_windows argument.
+If the property does not already exist,
+<function>XSetWMColormapWindows</function>
+sets the <property>WM_COLORMAP_WINDOWS</property> property on the specified
+window to the list of windows specified by the colormap_windows argument.
+The property is stored with a type of WINDOW and a format of 32.
+If it cannot intern the <property>WM_COLORMAP_WINDOWS</property> atom,
+<function>XSetWMColormapWindows</function>
+returns a zero status.
+Otherwise, it returns a nonzero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMColormapWindows</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's <property>WM_COLORMAP_WINDOWS</property> property, use
+<function>XGetWMColormapWindows</function>.
+<indexterm significance="preferred"><primary>XGetWMColormapWindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetwmcolormapwindows'>
+<funcprototype>
+  <funcdef>Status <function>XGetWMColormapWindows</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Window<parameter> **colormap_windows_return</parameter></paramdef>
+  <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>colormap_windows_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the list of windows.
+<!-- .ds Cn windows in the list -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of (Cn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetWMColormapWindows</function>
+function returns the list of window identifiers stored 
+in the <property>WM_COLORMAP_WINDOWS</property> property on the specified window.
+These identifiers indicate the colormaps that the window manager
+may need to install for this window.
+If the property exists, is of type WINDOW, is of format 32, 
+and the atom <property>WM_COLORMAP_WINDOWS</property> can be interned, 
+<function>XGetWMColormapWindows</function>
+sets the windows_return argument to a list of window identifiers, 
+sets the count_return argument to the number of elements in the list, 
+and returns a nonzero status.
+Otherwise, it sets neither of the return arguments
+and returns a zero status.
+To release the list of window identifiers, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMColormapWindows</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_ICON_SIZE_Property">
+<title>Setting and Reading the WM_ICON_SIZE Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_ICON_SIZE Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read 
+the <property>WM_ICON_SIZE</property> property for a given window.
+These functions use the 
+<structname>XIconSize</structname>
+<indexterm><primary>XIconSize</primary></indexterm>
+structure, which is defined in the
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<structname>XIconSize</structname>
+structure, use
+<function>XAllocIconSize</function>.
+</para>
+
+<para>
+  XIconSize *XAllocIconSize()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocIconSize</function>
+function allocates and returns a pointer to an
+<structname>XIconSize</structname>
+structure.
+Note that all fields in the
+<structname>XIconSize</structname>
+structure are initially set to zero.
+If insufficient memory is available, 
+<function>XAllocIconSize</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XIconSize</structname>
+structure contains:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XIconSize</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	int min_width, min_height;
+	int max_width, max_height;
+	int width_inc, height_inc;
+} XIconSize;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The width_inc and height_inc members define an arithmetic progression of
+sizes (minimum to maximum) that represent the supported icon sizes.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's <property>WM_ICON_SIZE</property> property, use
+<function>XSetIconSizes</function>.
+<indexterm significance="preferred"><primary>XSetIconSizes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xseticonsizes'>
+<funcprototype>
+  <funcdef><function>XSetIconSizes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XIconSize<parameter> *size_list</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>size_list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of items in the size list.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIconSizes</function>
+function is used only by window managers to set the supported icon sizes.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetIconSizes</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's <property>WM_ICON_SIZE</property> property, use
+<function>XGetIconSizes</function>.
+<indexterm significance="preferred"><primary>XGetIconSizes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeticonsizes'>
+<funcprototype>
+  <funcdef>Status <function>XGetIconSizes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XIconSize<parameter> **size_list_return</parameter></paramdef>
+  <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>size_list_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the size list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of items in the size list.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetIconSizes</function>
+function returns zero if a window manager has not set icon sizes;
+otherwise, it returns nonzero.
+<function>XGetIconSizes</function>
+should be called by an application that
+wants to find out what icon sizes would be most appreciated by the
+window manager under which the application is running.
+The application
+should then use
+<function>XSetWMHints</function>
+to supply the window manager with an icon pixmap or window in one of the
+supported sizes.
+To free the data allocated in size_list_return, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetIconSizes</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect2>
+<sect2 id="Using_Window_Manager_Convenience_Functions">
+<title>Using Window Manager Convenience Functions</title>
+<!-- .XS -->
+<!-- (SN Using Window Manager Convenience Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The 
+<function>XmbSetWMProperties</function>
+function stores the standard set of window manager properties,
+with text properties in standard encodings
+for internationalized text communication.
+The standard window manager properties for a given window are
+<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_NORMAL_HINTS</property>, <property>WM_CLASS</property>,
+<property>WM_COMMAND</property>, <property>WM_CLIENT_MACHINE</property>, and <property>WM_LOCALE_NAME</property>.
+<indexterm significance="preferred"><primary>XmbSetWMProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbsetwmproperties'>
+<funcprototype>
+  <funcdef>void <function>XmbSetWMProperties</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>char<parameter> *window_name</parameter></paramdef>
+  <paramdef>char<parameter> *icon_name</parameter></paramdef>
+  <paramdef>char<parameter> *argv[]</parameter></paramdef>
+  <paramdef>int<parameter> argc</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>
+  <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>
+  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>window_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window name,
+which should be a null-terminated string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>icon_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the icon name,
+which should be a null-terminated string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argv</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the application's argument list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of arguments.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size hints for the window in its normal state.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>wm_hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XWMHints</structname>
+structure to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class_hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XClassHint</structname>
+structure to be used.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbSetWMProperties</function>
+convenience function provides a simple programming interface 
+for setting those essential window properties that are used 
+for communicating with other clients
+(particularly window and session managers).
+</para>
+<para>
+<!-- .LP -->
+If the window_name argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the <property>WM_NAME</property> property.
+If the icon_name argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the <property>WM_ICON_NAME</property> property.
+The window_name and icon_name arguments are null-terminated strings
+in the encoding of the current locale.
+If the arguments can be fully converted to the STRING encoding,
+the properties are created with type ``STRING''; 
+otherwise, the arguments are converted to Compound Text, 
+and the properties are created with type ``COMPOUND_TEXT''.
+</para>
+<para>
+<!-- .LP -->
+If the normal_hints argument is non-NULL,
+<function>XmbSetWMProperties</function>
+calls
+<function>XSetWMNormalHints</function>,
+which sets the <property>WM_NORMAL_HINTS</property> property (see section 14.1.7).
+If the wm_hints argument is non-NULL, 
+<function>XmbSetWMProperties</function>
+calls
+<function>XSetWMHints</function>,
+which sets the <property>WM_HINTS</property> property (see section 14.1.6).
+</para>
+<para>
+<!-- .LP -->
+If the argv argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the <property>WM_COMMAND</property> property from argv and argc.
+An argc of zero indicates a zero-length command.
+</para>
+<para>
+<!-- .LP -->
+The hostname of the machine is stored using 
+<function>XSetWMClientMachine</function>
+(see section 14.2.2).
+</para>
+<para>
+<!-- .LP -->
+If the class_hints argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the <property>WM_CLASS</property> property.
+If the res_name member in the 
+<structname>XClassHint</structname>
+structure is set to the NULL pointer and the RESOURCE_NAME
+environment variable is set,
+the value of the environment variable is substituted for res_name.
+If the res_name member is NULL,
+the environment variable is not set, and argv and argv[0] are set,
+then the value of argv[0], stripped of any directory prefixes,
+is substituted for res_name.
+</para>
+<para>
+<!-- .LP -->
+It is assumed that the supplied class_hints.res_name and argv,
+the RESOURCE_NAME environment variable, and the hostname of the machine
+are in the encoding of the locale announced for the LC_CTYPE category
+(on <acronym>POSIX</acronym>-compliant systems, the LC_CTYPE, else LANG environment variable).
+The corresponding <property>WM_CLASS</property>, <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property> properties
+are typed according to the local host locale announcer.
+No encoding conversion is performed prior to storage in the properties.
+</para>
+<para>
+<!-- .LP -->
+For clients that need to process the property text in a locale,
+<function>XmbSetWMProperties</function>
+sets the <property>WM_LOCALE_NAME</property> property to be the name of the current locale.
+The name is assumed to be in the Host Portable Character Encoding
+and is converted to STRING for storage in the property.
+</para>
+<para>
+<!-- .LP -->
+<function>XmbSetWMProperties</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's standard window manager properties
+with strings in client-specified encodings, use
+<function>XSetWMProperties</function>.
+The standard window manager properties for a given window are
+<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_NORMAL_HINTS</property>, <property>WM_CLASS</property>,
+<property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property>.
+<indexterm significance="preferred"><primary>XSetWMProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmproperties'>
+<funcprototype>
+  <funcdef>void <function>XSetWMProperties</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *window_name</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *icon_name</parameter></paramdef>
+  <paramdef>char<parameter> **argv</parameter></paramdef>
+  <paramdef>int<parameter> argc</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>
+  <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>
+  <paramdef>XClassHint<parameter> *class_hints</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>window_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window name,
+which should be a null-terminated string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>icon_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the icon name,
+which should be a null-terminated string.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argv</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the application's argument list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of arguments.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>normal_hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size hints for the window in its normal state.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>wm_hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XWMHints</structname>
+structure to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class_hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XClassHint</structname>
+structure to be used.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XSetWMProperties</function>
+convenience function provides a single programming interface 
+for setting those essential window properties that are used 
+for communicating with other clients (particularly window and session
+managers).
+</para>
+<para>
+<!-- .LP -->
+If the window_name argument is non-NULL, 
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMName</function>,
+which, in turn, sets the <property>WM_NAME</property> property (see section 14.1.4).
+If the icon_name argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMIconName</function>,
+which sets the <property>WM_ICON_NAME</property> property (see section 14.1.5).
+If the argv argument is non-NULL, 
+<function>XSetWMProperties</function>
+calls
+<function>XSetCommand</function>,
+which sets the <property>WM_COMMAND</property> property (see section 14.2.1).
+Note that an argc of zero is allowed to indicate a zero-length command.
+Note also that the hostname of this machine is stored using
+<function>XSetWMClientMachine</function>
+(see section 14.2.2).
+</para>
+<para>
+<!-- .LP -->
+If the normal_hints argument is non-NULL, 
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMNormalHints</function>,
+which sets the <property>WM_NORMAL_HINTS</property> property (see section 14.1.7).
+If the wm_hints argument is non-NULL, 
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMHints</function>,
+which sets the <property>WM_HINTS</property> property (see section 14.1.6).
+</para>
+<para>
+<!-- .LP -->
+If the class_hints argument is non-NULL, 
+<function>XSetWMProperties</function>
+calls
+<function>XSetClassHint</function>,
+which sets the <property>WM_CLASS</property> property (see section 14.1.8).
+If the res_name member in the
+<structname>XClassHint</structname>
+structure is set to the NULL pointer and the RESOURCE_NAME environment 
+variable is set, 
+then the value of the environment variable is substituted for res_name.
+If the res_name member is NULL, 
+the environment variable is not set, 
+and argv and argv[0] are set, 
+then the value of argv[0], stripped of
+any directory prefixes, is substituted for res_name.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMProperties</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Client_to_Session_Manager_Communication">
+<title>Client to Session Manager Communication</title>
+<!-- .XS -->
+<!-- (SN Client to Session Manager Communication -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Set and read the <property>WM_COMMAND</property> property
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Set and read the <property>WM_CLIENT_MACHINE</property> property
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Setting_and_Reading_the_WM_COMMAND_Property">
+<title>Setting and Reading the WM_COMMAND Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_COMMAND Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the <property>WM_COMMAND</property> property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's <property>WM_COMMAND</property> property, use
+<function>XSetCommand</function>.
+<indexterm significance="preferred"><primary>XSetCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetcommand'>
+<funcprototype>
+  <funcdef><function>XSetCommand</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>char<parameter> **argv</parameter></paramdef>
+  <paramdef>int<parameter> argc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argv</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the application's argument list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of arguments.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetCommand</function>
+function sets the command and arguments used to invoke the
+application.
+(Typically, argv is the argv array of your main program.)
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetCommand</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's <property>WM_COMMAND</property> property, use
+<function>XGetCommand</function>.
+<indexterm significance="preferred"><primary>XGetCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetcommand'>
+<funcprototype>
+  <funcdef>Status <function>XGetCommand</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>char<parameter> ***argv_return</parameter></paramdef>
+  <paramdef>int<parameter> *argc_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argv_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the application's argument list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argc_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of arguments returned.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetCommand</function>
+function reads the <property>WM_COMMAND</property> property from the specified window 
+and returns a string list.
+If the <property>WM_COMMAND</property> property exists, 
+it is of type STRING and format 8.
+If sufficient memory can be allocated to contain the string list, 
+<function>XGetCommand</function>
+fills in the argv_return and argc_return arguments
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+To free the memory allocated to the string list, use
+<function>XFreeStringList</function>.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">
+<title>Setting and Reading the WM_CLIENT_MACHINE Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_CLIENT_MACHINE Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read 
+the <property>WM_CLIENT_MACHINE</property> property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's <property>WM_CLIENT_MACHINE</property> property, use
+<function>XSetWMClientMachine</function>.
+<indexterm significance="preferred"><primary>XSetWMClientMachine</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetwmclientmachine'>
+<funcprototype>
+  <funcdef>void <function>XSetWMClientMachine</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XTextProperty</structname>
+structure to be used.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMClientMachine</function>
+convenience function calls
+<function>XSetTextProperty</function>
+to set the <property>WM_CLIENT_MACHINE</property> property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's <property>WM_CLIENT_MACHINE</property> property, use
+<function>XGetWMClientMachine</function>.
+<indexterm significance="preferred"><primary>XGetWMClientMachine</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetwmclientmachine'>
+<funcprototype>
+  <funcdef>Status <function>XGetWMClientMachine</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>text_prop_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the
+<structname>XTextProperty</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMClientMachine</function>
+convenience function performs an 
+<function>XGetTextProperty</function>
+on the <property>WM_CLIENT_MACHINE</property> property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Standard_Colormaps">
+<title>Standard Colormaps</title>
+<!-- .XS -->
+<!-- (SN Standard Colormaps  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications with color palettes, smooth-shaded drawings, or digitized
+images demand large numbers of colors.  
+In addition, these applications often require an efficient mapping 
+from color triples to pixel values that display the appropriate colors.
+</para>
+<para>
+<!-- .LP -->
+As an example, consider a three-dimensional display program that wants 
+to draw a smoothly shaded sphere.  
+At each pixel in the image of the sphere, 
+the program computes the intensity and color of light
+reflected back to the viewer.  
+The result of each computation is a triple of red, green, and blue (<acronym>RGB</acronym>)
+coefficients in the range 0.0 to 1.0.  
+To draw the sphere, the program needs a colormap that provides a
+large range of uniformly distributed colors.  
+The colormap should be arranged so that the program can
+convert its <acronym>RGB</acronym> triples into pixel values very quickly,
+because drawing the entire sphere requires many such
+conversions.
+</para>
+<para>
+<!-- .LP -->
+On many current workstations,
+the display is limited to 256 or fewer colors.  
+Applications must allocate colors carefully, 
+not only to make sure they cover the entire range they need 
+but also to make use of as many of the available colors as possible.
+On a typical X display, 
+many applications are active at once.
+Most workstations have only one hardware look-up table for colors,
+so only one application colormap can be installed at a given time.
+The application using the installed colormap is displayed correctly, 
+and the other applications go technicolor and are
+displayed with false colors.
+</para>
+<para>
+<!-- .LP -->
+As another example, consider a user who is running an 
+image processing program to display earth-resources data.  
+The image processing program needs a colormap set up with 8 reds, 
+8 greens, and 4 blues, for a total of 256 colors.
+Because some colors are already in use in the default colormap, 
+the image processing program allocates and installs a new colormap.
+</para>
+<para>
+<!-- .LP -->
+The user decides to alter some of the colors in the image
+by invoking a color palette program to mix and choose colors.
+The color palette program also needs a
+colormap with eight reds, eight greens, and four blues, so just like
+the image processing program, it must allocate and
+install a new colormap.
+</para>
+<para>
+<!-- .LP -->
+Because only one colormap can be installed at a time,
+the color palette may be displayed incorrectly
+whenever the image processing program is active.
+Conversely, whenever the palette program is active, 
+the image may be displayed incorrectly.  
+The user can never match or compare colors in the palette and image.
+Contention for colormap resources can be reduced if applications
+with similar color needs share colormaps.
+</para>
+<para>
+<!-- .LP -->
+The image processing program and the color palette program 
+could share the same colormap if there existed a convention that described
+how the colormap was set up.  
+Whenever either program was active, 
+both would be displayed correctly.
+</para>
+<para>
+<!-- .LP -->
+The standard colormap properties define a set of commonly used
+colormaps.  
+Applications that share these colormaps and conventions display 
+true colors more often and provide a better interface to the user.
+</para>
+<para>
+<!-- .LP -->
+Standard colormaps allow applications to share commonly used color
+resources.  
+This allows many applications to be displayed in true colors
+simultaneously, even when each application needs an entirely filled
+colormap.
+</para>
+<para>
+<!-- .LP -->
+Several standard colormaps are described in this section.
+Usually, a window manager creates these colormaps.
+Applications should use the standard colormaps if they already exist.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<structname>XStandardColormap</structname>
+structure, use
+<function>XAllocStandardColormap</function>.
+</para>
+
+<para>
+XStandardColormap *XAllocStandardColormap()
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocStandardColormap</function>
+function allocates and returns a pointer to an
+<structname>XStandardColormap</structname>
+structure.
+Note that all fields in the
+<structname>XStandardColormap</structname>
+structure are initially set to zero.
+If insufficient memory is available, 
+<function>XAllocStandardColormap</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The 
+<structname>XStandardColormap</structname>
+structure contains:
+</para>
+<literallayout class="monospaced">
+/* Hints */
+
+#define       ReeaseByFreeingColormap  ((XID)1L)
+
+/* Values */
+
+typedef struct {
+	Colormap colormap;
+	unsigned long red_max;
+	unsigned long red_mult;
+	unsigned long green_max;
+	unsigned long green_mult;
+	unsigned long blue_max;
+	unsigned long blue_mult;
+	unsigned long base_pixel;
+	VisualID visualid;
+	XID killid;
+} XStandardColormap;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The colormap member is the colormap created by the
+<function>XCreateColormap</function>
+function.
+The red_max, green_max, and blue_max members give the maximum
+red, green, and blue values, respectively.  
+Each color coefficient ranges from zero to its max, inclusive.  
+For example,
+a common colormap allocation is 3/3/2 (3 planes for red, 3
+planes for green, and 2 planes for blue).  
+This colormap would have red_max = 7, green_max = 7, 
+and blue_max = 3.  
+An alternate allocation that uses only 216 colors is red_max = 5, 
+green_max = 5, and blue_max = 5.
+</para>
+<para>
+<!-- .LP -->
+The red_mult, green_mult, and blue_mult members give the
+scale factors used to compose a full pixel value. 
+(See the discussion of the base_pixel members for further information.)
+For a 3/3/2 allocation, red_mult might be 32,
+green_mult might be 4, and blue_mult might be 1.  
+For a 6-colors-each allocation, red_mult might be 36, 
+green_mult might be 6, and blue_mult might be 1.
+</para>
+<para>
+<!-- .LP -->
+The base_pixel member gives the base pixel value used to
+compose a full pixel value.  
+Usually, the base_pixel is obtained from a call to the 
+<function>XAllocColorPlanes</function>
+function.  
+Given integer red, green, and blue coefficients in their appropriate 
+ranges, one then can compute a corresponding pixel value by
+using the following expression:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+(r * red_mult + g * green_mult + b * blue_mult + base_pixel) &amp; 0xFFFFFFFF
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+For 
+<symbol>GrayScale</symbol>
+colormaps, 
+only the colormap, red_max, red_mult, 
+and base_pixel members are defined. 
+The other members are ignored.  
+To compute a 
+<symbol>GrayScale</symbol>
+pixel value, use the following expression:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+(gray * red_mult + base_pixel) &amp; 0xFFFFFFFF
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Negative multipliers can be represented by converting the 2's
+complement representation of the multiplier into an unsigned long and
+storing the result in the appropriate _mult field.
+The step of masking by 0xFFFFFFFF effectively converts the resulting
+positive multiplier into a negative one.
+The masking step will take place automatically on many machine architectures,
+depending on the size of the integer type used to do the computation.
+</para>
+<para>
+<!-- .LP -->
+The visualid member gives the ID number of the visual from which the
+colormap was created.
+The killid member gives a resource ID that indicates whether
+the cells held by this standard colormap are to be released 
+by freeing the colormap ID or by calling the
+<function>XKillClient</function>
+function on the indicated resource.
+(Note that this method is necessary for allocating out of an existing colormap.)
+</para>
+<para>
+<!-- .LP -->
+The properties containing the 
+<structname>XStandardColormap</structname>
+information have 
+the type RGB_COLOR_MAP.
+</para>
+<para>
+<!-- .LP -->
+The remainder of this section discusses standard colormap properties and atoms
+as well as how to manipulate standard colormaps.
+</para>
+<sect2 id="Standard_Colormap_Properties_and_Atoms">
+<title>Standard Colormap Properties and Atoms</title>
+<!-- .XS -->
+<!-- (SN Standard Colormap Properties and Atoms  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Standard Colormaps</primary></indexterm>
+<indexterm><primary>Colormaps</primary><secondary>standard</secondary></indexterm>
+Several standard colormaps are available.  
+Each standard colormap is defined by a property, 
+and each such property is identified by an atom.  
+The following list names the atoms and describes the colormap
+associated with each one.
+The
+<filename class="headerfile">&lt;X11/Xatom.h&gt;</filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>
+header file contains the definitions for each of the following atoms,
+which are prefixed with XA_.
+</para>
+
+
+
+<variablelist>
+  <varlistentry>
+    <term>RGB_DEFAULT_MAP</term>
+    <listitem>
+      <para>
+This atom names a property.
+The value of the property is an array of
+<structname>XStandardColormap</structname>
+structures.
+Each entry in the array describes an <acronym>RGB</acronym> subset of the default color
+map for the Visual specified by visual_id.
+      </para>
+      <para>
+Some applications only need a few <acronym>RGB</acronym> colors and
+may be able to allocate them from the system default colormap.
+This is the ideal situation because the fewer colormaps that are
+active in the system the more applications are displayed
+with correct colors at all times.
+      </para>
+      <para>
+A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays
+is 6 reds, 6 greens, and 6 blues.  
+This gives 216 uniformly distributed colors 
+(6 intensities of 36 different hues) and still leaves 40 elements 
+of a 256-element colormap available for special-purpose colors 
+for text, borders, and so on.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>RGB_BEST_MAP</term>
+    <listitem>
+      <para>
+This atom names a property.  The value of the property is an 
+<structname>XStandardColormap</structname>.
+      </para>
+      <para>
+The property defines the best <acronym>RGB</acronym> colormap available on
+the screen.
+(Of course, this is a subjective evaluation.)
+Many image processing and three-dimensional applications need to
+use all available colormap cells and to distribute as many
+perceptually distinct colors as possible over those cells.
+This implies that there may be more green values available than
+red, as well as more green or red than blue.
+      </para>
+      <para>
+For an 8-plane 
+<symbol>PseudoColor</symbol>
+visual, 
+RGB_BEST_MAP is likely to be a 3/3/2 allocation.  
+For a 24-plane 
+<symbol>DirectColor</symbol>
+visual, 
+RGB_BEST_MAP is normally an 8/8/8 allocation.  
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP</term>
+    <listitem>
+      <para>
+These atoms name properties.
+The value of each property is an
+<structname>XStandardColormap</structname>.
+      </para>
+      <para>
+The properties define all-red, all-green, and all-blue
+colormaps, respectively.  
+These maps are used by applications that want to make color-separated 
+images.  
+For example, a user might generate a full-color image 
+on an 8-plane display both by rendering an image three times 
+(once with high color resolution in red, once with green, 
+and once with blue) and by multiply exposing a single frame in a camera.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry> 
+    <term>RGB_GRAY_MAP</term>
+    <listitem>
+      <para>
+This atom names a property.
+The value of the property is an 
+<structname>XStandardColormap</structname>.
+      </para>
+      <para>
+The property describes the best 
+<symbol>GrayScale</symbol>
+colormap available on the screen.  
+As previously mentioned, 
+only the colormap, red_max, red_mult, and base_pixel members of the
+<structname>XStandardColormap</structname>
+structure are used for 
+<symbol>GrayScale</symbol>
+colormaps.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="Setting_and_Obtaining_Standard_Colormaps">
+<title>Setting and Obtaining Standard Colormaps</title>
+<!-- .XS -->
+<!-- (SN Setting and Obtaining Standard Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and obtain an
+<structname>XStandardColormap</structname>
+structure.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set an
+<structname>XStandardColormap</structname>
+structure, use
+<function>XSetRGBColormaps</function>.
+<indexterm significance="preferred"><primary>XSetRGBColormaps</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetrgbcolormaps'>
+<funcprototype>
+  <funcdef>void <function>XSetRGBColormaps</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XStandardColormap<parameter> *std_colormap</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>std_colormap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XStandardColormap</structname>
+structure to be used.
+<!-- .ds Cn colormaps -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of (Cn.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XSetRGBColormaps</function>
+function replaces the <acronym>RGB</acronym> colormap definition in the specified property 
+on the named window.
+If the property does not already exist,
+<function>XSetRGBColormaps</function>
+sets the <acronym>RGB</acronym> colormap definition in the specified property
+on the named window.
+The property is stored with a type of RGB_COLOR_MAP and a format of 32.
+Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>
+restriction that only RGB_DEFAULT_MAP contain more than one definition.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XSetRGBColormaps</function>
+function usually is only used by window or session managers.
+To create a standard colormap, 
+follow this procedure:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Open a new connection to the same server.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Grab the server.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+See if the property is on the property list of the root window for the screen.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the desired property is not present:
+<!-- .RS -->
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Create a colormap (unless you are using the default colormap of the screen).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Determine the color characteristics of the visual.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Allocate cells in the colormap (or create it with
+<symbol>AllocAll</symbol>).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Call 
+<function>XStoreColors</function>
+to store appropriate color values in the colormap.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Fill in the descriptive members in the 
+<structname>XStandardColormap</structname>
+structure.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Attach the property to the root window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Use
+<function>XSetCloseDownMode</function>
+to make the resource permanent.
+<!-- .RE -->
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Ungrab the server.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XSetRGBColormaps</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadAtom</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the 
+<structname>XStandardColormap</structname>
+structure associated with the specified property, use
+<function>XGetRGBColormaps</function>.
+<indexterm significance="preferred"><primary>XGetRGBColormaps</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetrgbcolormaps'>
+<funcprototype>
+  <funcdef>Status <function>XGetRGBColormaps</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XStandardColormap<parameter> **std_colormap_return</parameter></paramdef>
+  <paramdef>int<parameter> *count_return</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>std_colormap_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the
+<structname>XStandardColormap</structname>
+structure.
+<!-- .ds Cn colormaps -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of (Cn.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XGetRGBColormaps</function>
+function returns the <acronym>RGB</acronym> colormap definitions stored 
+in the specified property on the named window.
+If the property exists, is of type RGB_COLOR_MAP, is of format 32, 
+and is long enough to contain a colormap definition,
+<function>XGetRGBColormaps</function>
+allocates and fills in space for the returned colormaps
+and returns a nonzero status.
+If the visualid is not present, 
+<function>XGetRGBColormaps</function>
+assumes the default visual for the screen on which the window is located; 
+if the killid is not present, 
+<symbol>None</symbol>
+is assumed, which indicates that the resources cannot be released.
+Otherwise, 
+none of the fields are set, and 
+<function>XGetRGBColormaps</function>
+returns a zero status.
+Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>
+restriction that only RGB_DEFAULT_MAP contain more than one definition.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetRGBColormaps</function>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH15.xml b/libX11/specs/libX11/CH15.xml
index 753dff177..7abc6173e 100644
--- a/libX11/specs/libX11/CH15.xml
+++ b/libX11/specs/libX11/CH15.xml
@@ -1,2491 +1,2491 @@
-<?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="resource_manager_functions">

-<title>Resource Manager Functions</title>

-<!-- .sp 2 -->

-<!-- .nr H1 15 -->

-<!-- .nr H2 0 -->

-<!-- .nr H3 0 -->

-<!-- .nr H4 0 -->

-<!-- .nr H5 0 -->

-<!-- .na -->

-<para>

-<!-- .LP -->

-<!-- .XS -->

-<!-- Chapter 15: Resource Manager Functions -->

-<!-- .XE -->

-A program often needs a variety of options in the X environment

-(for example, fonts, colors, icons, and cursors).

-Specifying all of these options on the command line is awkward

-because users may want to customize many aspects of the program

-and need a convenient way to establish these customizations as

-the default settings.

-The resource manager is provided for this purpose.

-Resource specifications are usually stored in human-readable files

-and in server properties.

-</para>

-<para>

-<!-- .LP -->

-The resource manager is a database manager with a twist.

-In most database systems, 

-you perform a query using an imprecise specification,

-and you get back a set of records.

-The resource manager, however, allows you to specify a large

-set of values with an imprecise specification, to query the database 

-with a precise specification, and to get back only a single value.

-This should be used by applications that need to know what the

-user prefers for colors, fonts, and other resources.

-It is this use as a database for dealing with X resources that

-inspired the name "Resource Manager,"

-although the resource manager can be and is used in other ways.

-</para>

-<para>

-<!-- .LP -->

-For example, 

-a user of your application may want to specify 

-that all windows should have a blue background 

-but that all mail-reading windows should have a red background.

-With well-engineered and coordinated applications,

-a user can define this information using only two lines of specifications.

-</para>

-<para>

-<!-- .LP -->

-As an example of how the resource manager works,

-consider a mail-reading application called xmh.

-Assume that it is designed so that it uses a

-complex window hierarchy all the way down to individual command buttons,

-which may be actual small subwindows in some toolkits.

-These are often called objects or widgets.

-In such toolkit systems,

-each user interface object can be composed of other objects

-and can be assigned a name and a class.

-Fully qualified names or classes can have arbitrary numbers of component names,

-but a fully qualified name always has the same number of component names as a

-fully qualified class.

-This generally reflects the structure of the application as composed

-of these objects, starting with the application itself.

-</para>

-<para>

-<!-- .LP -->

-For example, the xmh mail program has a name "xmh" and is one

-of a class of "Mail" programs.

-By convention, the first character of class components is capitalized,

-and the first letter of name components is in lowercase.

-Each name and class finally has an attribute

-(for example, "foreground" or "font").

-If each window is properly assigned a name and class,

-it is easy for the user to specify attributes of any portion 

-of the application.

-</para>

-<para>

-<!-- .LP -->

-At the top level, 

-the application might consist of a paned window (that is, a window divided

-into several sections) named "toc".

-One pane of the paned window is a button box window named "buttons"

-and is filled with command buttons. 

-One of these command buttons is used to incorporate

-new mail and has the name "incorporate".

-This window has a fully qualified name, "xmh.toc.buttons.incorporate",

-and a fully qualified class, "Xmh.Paned.Box.Command".

-Its fully qualified name is the name of its parent, "xmh.toc.buttons", 

-followed by its name, "incorporate".

-Its class is the class of its parent, "Xmh.Paned.Box", 

-followed by its particular class, "Command".  

-The fully qualified name of a resource is

-the attribute's name appended to the object's fully qualified

-name, and the fully qualified class is its class appended to the object's

-class.

-</para>

-<para>

-<!-- .LP -->

-The incorporate button might need the following resources: 

-Title string,

-Font,

-Foreground color for its inactive state,

-Background color for its inactive state,

-Foreground color for its active state, and

-Background color for its active state.

-Each resource is considered

-to be an attribute of the button and, as such, has a name and a class.

-For example, the foreground color for the button in

-its active state might be named "activeForeground",

-and its class might be "Foreground".

-</para>

-<para>

-<!-- .LP -->

-When an application looks up a resource (for example, a color),

-it passes the complete name and complete class of the resource

-to a look-up routine.

-The resource manager compares this complete specification

-against the incomplete specifications of entries in the resource

-database, finds the best match, and returns the corresponding

-value for that entry.

-</para>

-<para>

-<!-- .LP -->

-The definitions for the resource manager are contained in

-<filename class="headerfile">&lt;X11/Xresource.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xresource.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xresource.h&gt;</filename></secondary></indexterm>

-</para>

-<sect1 id="Resource_File_Syntax">

-<title>Resource File Syntax</title>

-<!-- .XS -->

-<!-- (SN Resource File Syntax -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The syntax of a resource file is a sequence of resource lines

-terminated by newline characters or the end of the file.

-The syntax of an individual resource line is:

-</para>

-<para>

-<!-- .LP -->

-<!-- .\" Start marker code here -->

-<literallayout class="monospaced">

-<!-- .TA 1.5i 1.75i -->

-<!-- .ta 1.5i 1.75i -->

-ResourceLine     =     Comment | IncludeFile | ResourceSpec | &lt;empty line&gt;

-Comment     =     "!" {&lt;any character except null or newline&gt;}

-IncludeFile     =     "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace

-FileName     =     &lt;valid filename for operating system&gt;

-ResourceSpec     =     WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value

-ResourceName     =     [Binding] {Component Binding} ComponentName

-Binding     =     "." | "*"

-WhiteSpace     =     {&lt;space&gt; | &lt;horizontal tab&gt;}

-Component     =     "?" | ComponentName

-ComponentName     =     NameChar {NameChar}

-NameChar     =     "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"

-Value     =     {&lt;any character except null or unescaped newline&gt;}

-</literallayout>

-<!-- .\" End marker code here -->

-</para>

-<para>

-<!-- .LP -->

-Elements separated by vertical bar (|) are alternatives.

-Curly braces ({......}) indicate zero or more repetitions

-of the enclosed elements.

-Square brackets ([......]) indicate that the enclosed element is optional.

-Quotes ("......") are used around literal characters.

-</para>

-<para>

-<!-- .LP -->

-IncludeFile lines are interpreted by replacing the line with the

-contents of the specified file.

-The word "include" must be in lowercase.

-The file name is interpreted relative to the directory of the file in

-which the line occurs (for example, if the file name contains no

-directory or contains a relative directory specification).

-</para>

-<para>

-<!-- .LP -->

-If a ResourceName contains a contiguous sequence of two or more Binding

-characters, the sequence will be replaced with a single ".." character

-if the sequence contains only ".." characters;

-otherwise, the sequence will be replaced with a single "*" character.

-</para>

-<para>

-<!-- .LP -->

-A resource database never contains more than one entry for a given

-ResourceName.  If a resource file contains multiple lines with the

-same ResourceName, the last line in the file is used.

-</para>

-<para>

-<!-- .LP -->

-Any white space characters before or after the name or colon in a ResourceSpec

-are ignored.

-To allow a Value to begin with white space,

-the two-character sequence "\\<emphasis remap='I'>space</emphasis>" (backslash followed by space)

-is recognized and replaced by a space character,

-and the two-character sequence "\\<emphasis remap='I'>tab</emphasis>"

-(backslash followed by horizontal tab)

-is recognized and replaced by a horizontal tab character.

-To allow a Value to contain embedded newline characters,

-the two-character sequence "\\n" is recognized and replaced by a

-newline character.

-To allow a Value to be broken across multiple lines in a text file,

-the two-character sequence "\\<emphasis remap='I'>newline</emphasis>"

-(backslash followed by newline) is

-recognized and removed from the value.

-To allow a Value to contain arbitrary character codes,

-the four-character sequence "\\<emphasis remap='I'>nnn</emphasis>",

-where each <emphasis remap='I'>n</emphasis> is a digit character in the range of "0"-"7",

-is recognized and replaced with a single byte that contains

-the octal value specified by the sequence.

-Finally, the two-character sequence "\newline" is recognized

-and replaced with a single backslash.

-</para>

-<para>

-<!-- .LP -->

-As an example of these sequences,

-the following resource line contains a value consisting of four

-characters: a backslash, a null, a "z", and a newline:

-<literallayout class="monospaced">

-magic.values: \\000\

-z\n

-</literallayout>

-</para>

-</sect1>

-<sect1 id="Resource_Manager_Matching_Rules">

-<title>Resource Manager Matching Rules</title>

-<!-- .XS -->

-<!-- (SN Resource Manager Matching Rules -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The algorithm for determining which resource database entry

-matches a given query is the heart of the resource manager.

-All queries must fully specify the name and class of the desired resource

-(use of the characters "*" and "?" is not permitted).

-The library supports up to 100 components in a full name or class.

-Resources are stored in the database with only partially specified

-names and classes, using pattern matching constructs.

-An asterisk (*) is a loose binding and is used to represent any number

-of intervening components, including none.

-A period (.) is a tight binding and is used to separate immediately

-adjacent components.

-A question mark (?) is used to match any single component name or class.

-A database entry cannot end in a loose binding;

-the final component (which cannot be the character "?") must be specified.

-The lookup algorithm searches the database for the entry that most

-closely matches (is most specific for) the full name and class being queried.

-When more than one database entry matches the full name and class,

-precedence rules are used to select just one.

-</para>

-<para>

-<!-- .LP -->

-The full name and class are scanned from left to right (from highest

-level in the hierarchy to lowest), one component at a time.

-At each level, the corresponding component and/or binding of each

-matching entry is determined, and these matching components and

-bindings are compared according to precedence rules.

-Each of the rules is applied at each level before moving to the next level,

-until a rule selects a single entry over all others.

-The rules, in order of precedence, are:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-An entry that contains a matching component (whether name, class,

-or the character "?")

-takes precedence over entries that elide the level (that is, entries

-that match the level in a loose binding).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-An entry with a matching name takes precedence over both

-entries with a matching class and entries that match using the character "?".

-An entry with a matching class takes precedence over

-entries that match using the character "?".

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-An entry preceded by a tight binding takes precedence over entries

-preceded by a loose binding.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-To illustrate these rules,

-consider the following resource database entries:

-<literallayout class="monospaced">

-<!-- .TA 2.5i 3.5i -->

-<!-- .ta 2.5i 3.5i -->

-xmh*Paned*activeForeground:     red     <emphasis remap='I'>(entry A)</emphasis>

-*incorporate.Foreground:     blue     <emphasis remap='I'>(entry B)</emphasis>

-xmh.toc*Command*activeForeground:     green     <emphasis remap='I'>(entry C)</emphasis>

-xmh.toc*?.Foreground:     white     <emphasis remap='I'>(entry D)</emphasis>

-xmh.toc*Command.activeForeground:     black     <emphasis remap='I'>(entry E)</emphasis>

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-Consider a query for the resource:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA 3.5i -->

-<!-- .ta 3.5i -->

-xmh.toc.messagefunctions.incorporate.activeForeground     <emphasis remap='I'>(name)</emphasis>

-Xmh.Paned.Box.Command.Foreground     <emphasis remap='I'>(class)</emphasis>

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-At the first level (xmh, Xmh), rule 1 eliminates entry B.

-At the second level (toc, Paned), rule 2 eliminates entry A.

-At the third level (messagefunctions, Box), no entries are eliminated.

-At the fourth level (incorporate, Command), rule 2 eliminates entry D.

-At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.

-</para>

-</sect1>

-<sect1 id="Quarks">

-<title>Quarks</title>

-<!-- .XS -->

-<!-- (SN Quarks -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Most uses of the resource manager involve defining names,

-classes, and representation types as string constants.

-However, always referring to strings in the resource manager can be slow,

-because it is so heavily used in some toolkits.

-To solve this problem, 

-a shorthand for a string is used in place of the string

-in many of the resource manager functions.

-Simple comparisons can be performed rather than string comparisons.

-The shorthand name for a string is called a quark and is the

-type 

-<type>XrmQuark</type>.

-On some occasions,

-you may want to allocate a quark that has no string equivalent.

-</para>

-<para>

-<!-- .LP -->

-A quark is to a string what an atom is to a string in the server,

-but its use is entirely local to your application.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate a new quark, use

-<function>XrmUniqueQuark</function>.

-</para>

-<indexterm significance="preferred"><primary>XrmUniqueQuark</primary></indexterm>

-<!-- .sM -->

-<para>XrmQuark XrmUniqueQuark()</para>

-<!-- .FN -->

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmUniqueQuark</function>

-function allocates a quark that is guaranteed not to represent any string that

-is known to the resource manager.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-Each name, class, and representation type is typedef'd as an

-<type>XrmQuark</type>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-typedef int XrmQuark, *XrmQuarkList;

-typedef XrmQuark XrmName;

-typedef XrmQuark XrmClass;

-typedef XrmQuark XrmRepresentation;

-#define NULLQUARK ((XrmQuark) 0)

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Lists are represented as null-terminated arrays of quarks.

-The size of the array must be large enough for the number of components used.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-typedef XrmQuarkList XrmNameList;

-typedef XrmQuarkList XrmClassList;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To convert a string to a quark, use

-<function>XrmStringToQuark</function>

-or

-<function>XrmPermStringToQuark</function>.

-</para>

-<literallayout class="monospaced">

-#define XrmStringToName(string) XrmStringToQuark(string)

-#define XrmStringToClass(string) XrmStringToQuark(string)

-#define XrmStringToRepresentation(string) XrmStringToQuark(string)

-</literallayout>

-

-<indexterm significance="preferred"><primary>XrmStringToQuark</primary></indexterm>

-<indexterm significance="preferred"><primary>XrmPermStringToQuark</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XrmQuark <function>XrmStringToQuark</function></funcdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<!-- .ds Ql -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the string for which a quark(Ql is to be allocated.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-These functions can be used to convert from string to quark representation.

-If the string is not in the Host Portable Character Encoding,

-the conversion is implementation-dependent.

-The string argument to

-<function>XrmStringToQuark</function>

-need not be permanently allocated storage.

-<function>XrmPermStringToQuark</function>

-is just like

-<function>XrmStringToQuark</function>,

-except that Xlib is permitted to assume the string argument is permanently

-allocated,

-and, hence, that it can be used as the value to be returned by

-<function>XrmQuarkToString</function>.

-</para>

-<para>

-<!-- .LP -->

-For any given quark, if

-<function>XrmStringToQuark</function>

-returns a non-NULL value,

-all future calls will return the same value (identical address).

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To convert a quark to a string, use 

-<function>XrmQuarkToString</function>.

-</para>

-

-<literallayout class="monospaced">

-#define XrmNameToString(name)  XrmQuarkToString(name)

-#define XrmClassToString(class)  XrmQuarkToString(name)

-#define XrmRepresentationToString(type)  XrmQuarkToString(type)

-</literallayout>

-<indexterm significance="preferred"><primary>XrmQuarkToString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XrmQuarkToString</function></funcdef>

-  <paramdef>XrmQuark<parameter> quark</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>quark</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the quark for which the equivalent string is desired.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-<!-- AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -->

-<para>

-These functions can be used to convert from quark representation to string.

-The string pointed to by the return value must not be modified or freed.

-The returned string is byte-for-byte equal to the original

-string passed to one of the string-to-quark routines.

-If no string exists for that quark,

-<function>XrmQuarkToString</function>

-returns NULL.

-For any given quark, if

-<function>XrmQuarkToString</function>

-returns a non-NULL value,

-all future calls will return the same value (identical address).

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To convert a string with one or more components to a quark list, use

-<function>XrmStringToQuarkList</function>.

-</para>

-

-<literallayout class="monospaced">

-#define XrmStringToNameList(str,name)  XrmStringToQuarkList((str), (name))

-#define XrmStringToClassList(str,class)  XrmStringToQuarkList((str), (class))

-</literallayout>

-

-<indexterm significance="preferred"><primary>XrmStringToQuarkList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmStringToQuarkList</function></funcdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<!-- .ds Ql \ list -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the string for which a quark(Ql is to be allocated.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>quarks_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the list of quarks.

-The caller must allocate sufficient space for the quarks list before calling 

-<function>XrmStringToQuarkList</function>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmStringToQuarkList</function>

-function converts the null-terminated string (generally a fully qualified name)

-to a list of quarks.

-Note that the string must be in the valid ResourceName format 

-(see section 15.1).

-If the string is not in the Host Portable Character Encoding,

-the conversion is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-A binding list is a list of type

-<type>XrmBindingList</type>

-and indicates if components of name or class lists are bound tightly or loosely

-(that is, if wildcarding of intermediate components is specified).

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<constant>XrmBindTightly</constant>

-indicates that a period separates the components, and

-<constant>XrmBindLoosely</constant>

-indicates that an asterisk separates the components.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To convert a string with one or more components to a binding list

-and a quark list, use

-<function>XrmStringToBindingQuarkList</function>.

-<indexterm significance="preferred"><primary>XrmStringToBindingQuarkList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XrmStringToBindingQuarkList</function></funcdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-  <paramdef>XrmBindingList<parameter> bindings_return</parameter></paramdef>

-  <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<!-- .ds Ql \ list -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the string for which a quark(Ql is to be allocated.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bindings_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the binding list.

-The caller must allocate sufficient space for the binding list before calling 

-<function>XrmStringToBindingQuarkList</function>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>quarks_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the list of quarks.

-The caller must allocate sufficient space for the quarks list before calling 

-<function>XrmStringToBindingQuarkList</function>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Component names in the list are separated by a period or 

-an asterisk character.

-The string must be in the format of a valid ResourceName (see section 15.1).

-If the string does not start with a period or an asterisk, 

-a tight binding is assumed.

-For example, the string ``*a.b*c'' becomes:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA .75i 1.5i 2.25i -->

-<!-- .ta .75i 1.5i 2.25i -->

-quarks:       a         b         c

-bindings:     loose     tight     loose

-</literallayout>

-</para>

-</sect1>

-<sect1 id="Creating_and_Storing_Databases">

-<title>Creating and Storing Databases</title>

-<!-- .XS -->

-<!-- (SN Creating and Storing Databases -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XrmDatabase</primary></indexterm>

-A resource database is an opaque type,

-<type>XrmDatabase</type>.

-Each database value is stored in an

-<type>XrmValue</type>

-structure.

-This structure consists of a size, an address, and a representation type.

-The size is specified in bytes.

-The representation type is a way for you to store data tagged by some 

-application-defined type (for example, the strings ``font'' or ``color'').

-It has nothing to do with the C data type or with its class. 

-The

-<type>XrmValue</type>

-structure is defined as:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XrmValue</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     unsigned int size;

-     XPointer addr;

-} XrmValue, *XrmValuePtr;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To initialize the resource manager, use

-<function>XrmInitialize</function>.

-<indexterm significance="preferred"><primary>XrmInitialize</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmInitialize</function></funcdef>

-  <paramdef>void<parameter> XrmInitialize(\|)</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-To retrieve a database from disk, use

-<function>XrmGetFileDatabase</function>.

-<indexterm significance="preferred"><primary>XrmGetFileDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XrmDatabase <function>XrmGetFileDatabase</function></funcdef>

-  <paramdef>char<parameter> *filename</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>filename</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database file name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmGetFileDatabase</function>

-function opens the specified file,

-creates a new resource database, and loads it with the specifications

-read in from the specified file.

-The specified file should contain a sequence of entries in valid ResourceLine

-format (see section 15.1); the database that results from reading a file

-with incorrect syntax is implementation-dependent.

-The file is parsed in the current locale, 

-and the database is created in the current locale.

-If it cannot open the specified file,

-<function>XrmGetFileDatabase</function>

-returns NULL.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To store a copy of a database to disk, use

-<function>XrmPutFileDatabase</function>.

-<indexterm significance="preferred"><primary>XrmPutFileDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmPutFileDatabase</function></funcdef>

-  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

-  <paramdef>char<parameter> *stored_db</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the database that is to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>stored_db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the file name for the stored database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmPutFileDatabase</function>

-function stores a copy of the specified database in the specified file.

-Text is written to the file as a sequence of entries in valid

-ResourceLine format (see section 15.1).

-The file is written in the locale of the database.

-Entries containing resource names that are not in the Host Portable Character

-Encoding or containing values that are not in the encoding of the database

-locale, are written in an implementation-dependent manner.

-The order in which entries are written is implementation-dependent.

-Entries with representation types other than ``String'' are ignored.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a pointer to the screen-independent resources of a display, use

-<function>XResourceManagerString</function>.

-<indexterm significance="preferred"><primary>XResourceManagerString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XResourceManagerString</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XResourceManagerString</function>

-function returns the RESOURCE_MANAGER property from the server's root

-window of screen zero, which was returned when the connection was opened using

-<function>XOpenDisplay</function>.

-The property is converted from type STRING to the current locale.

-The conversion is identical to that produced by 

-<function>XmbTextPropertyToTextList</function>

-for a single element STRING property.

-The returned string is owned by Xlib and should not be freed by the client.

-The property value must be in a format that is acceptable to

-<function>XrmGetStringDatabase</function>.

-If no property exists, NULL is returned.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a pointer to the screen-specific resources of a screen, use

-<function>XScreenResourceString</function>.

-<indexterm significance="preferred"><primary>XScreenResourceString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XScreenResourceString</function></funcdef>

-  <paramdef>Screen<parameter> *screen</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the screen.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XScreenResourceString</function>

-function returns the SCREEN_RESOURCES property from the root window of the

-specified screen.

-The property is converted from type STRING to the current locale.

-The conversion is identical to that produced by 

-<function>XmbTextPropertyToTextList</function>

-for a single element STRING property.

-The property value must be in a format that is acceptable to

-<function>XrmGetStringDatabase</function>.

-If no property exists, NULL is returned.

-The caller is responsible for freeing the returned string by using

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a database from a string, use

-<function>XrmGetStringDatabase</function>.

-<indexterm significance="preferred"><primary>XrmGetStringDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XrmDatabase <function>XrmGetStringDatabase</function></funcdef>

-  <paramdef>char<parameter> *data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the database contents using a string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmGetStringDatabase</function>

-function creates a new database and stores the resources specified

-in the specified null-terminated string.

-<function>XrmGetStringDatabase</function>

-is similar to

-<function>XrmGetFileDatabase</function>

-except that it reads the information out of a string instead of out of a file.

-The string should contain a sequence of entries in valid ResourceLine

-format (see section 15.1) terminated by a null character;

-the database that results from using a string

-with incorrect syntax is implementation-dependent.

-The string is parsed in the current locale, 

-and the database is created in the current locale.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the locale name of a database, use

-<function>XrmLocaleOfDatabase</function>.

-<indexterm significance="preferred"><primary>XrmLocaleOfDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XrmLocaleOfDatabase</function></funcdef>

-  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmLocaleOfDatabase</function>

-function returns the name of the locale bound to the specified

-database, as a null-terminated string.

-The returned locale name string is owned by Xlib and should not be

-modified or freed by the client.

-Xlib is not permitted to free the string until the database is destroyed.

-Until the string is freed,

-it will not be modified by Xlib.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To destroy a resource database and free its allocated memory, use

-<function>XrmDestroyDatabase</function>.

-<indexterm significance="preferred"><primary>XrmDestroyDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmDestroyDatabase</function></funcdef>

-  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If database is NULL,

-<function>XrmDestroyDatabase</function>

-returns immediately.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To associate a resource database with a display, use

-<function>XrmSetDatabase</function>.

-<indexterm significance="preferred"><primary>XrmSetDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmSetDatabase</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmSetDatabase</function>

-function associates the specified resource database (or NULL)

-with the specified display.

-The database previously associated with the display (if any) is not destroyed.

-A client or toolkit may find this function convenient for retaining a database

-once it is constructed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the resource database associated with a display, use

-<function>XrmGetDatabase</function>.

-<indexterm significance="preferred"><primary>XrmGetDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XrmDatabase <function>XrmGetDatabase</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmGetDatabase</function>

-function returns the database associated with the specified display.

-It returns NULL if a database has not yet been set.

-</para>

-</sect1>

-<sect1 id="Merging_Resource_Databases">

-<title>Merging Resource Databases</title>

-<!-- .XS -->

-<!-- (SN Merging Resource Databases -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To merge the contents of a resource file into a database, use

-<function>XrmCombineFileDatabase</function>.

-<indexterm significance="preferred"><primary>XrmCombineFileDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XrmCombineFileDatabase</function></funcdef>

-  <paramdef>char<parameter> *filename</parameter></paramdef>

-  <paramdef>XrmDatabase<parameter> *target_db</parameter></paramdef>

-  <paramdef>Bool<parameter> override</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>filename</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database file name.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database into which the source 

-database is to be merged.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>override</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies whether source entries override target ones.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XrmCombineFileDatabase</function>

-function merges the contents of a resource file into a database.

-If the same specifier is used for an entry in both the file and

-the database,

-the entry in the file will replace the entry in the database

-if override is

-<symbol>True</symbol>;

-otherwise, the entry in the file is discarded.

-The file is parsed in the current locale.

-If the file cannot be read,

-a zero status is returned;

-otherwise, a nonzero status is returned.

-If target_db contains NULL,

-<function>XrmCombineFileDatabase</function>

-creates and returns a new database to it.

-Otherwise, the database pointed to by target_db is not destroyed by the merge.

-The database entries are merged without changing values or types,

-regardless of the locale of the database.

-The locale of the target database is not modified.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To merge the contents of one database into another database, use

-<function>XrmCombineDatabase</function>.

-<indexterm significance="preferred"><primary>XrmCombineDatabase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmCombineDatabase</function></funcdef>

-  <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>

-  <paramdef>Bool<parameter> override</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>source_db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database that is to be merged into the target database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database into which the source 

-database is to be merged.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>override</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies whether source entries override target ones.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XrmCombineDatabase</function>

-function merges the contents of one database into another.

-If the same specifier is used for an entry in both databases,

-the entry in the source_db will replace the entry in the target_db

-if override is

-<symbol>True</symbol>;

-otherwise, the entry in source_db is discarded.

-If target_db contains NULL,

-<function>XrmCombineDatabase</function>

-simply stores source_db in it.

-Otherwise, source_db is destroyed by the merge, but the database pointed

-to by target_db is not destroyed.

-The database entries are merged without changing values or types,

-regardless of the locales of the databases.

-The locale of the target database is not modified.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To merge the contents of one database into another database with override

-semantics, use

-<function>XrmMergeDatabases</function>.

-<indexterm significance="preferred"><primary>XrmMergeDatabases</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmMergeDatabases</function></funcdef>

-  <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>source_db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database that is to be merged into the target database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target_db</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database into which the source 

-database is to be merged.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-Calling the

-<function>XrmMergeDatabases</function>

-function is equivalent to calling the

-<function>XrmCombineDatabase</function>

-function with an override argument of

-<symbol>True</symbol>.

-</para>

-</sect1>

-<sect1 id="Looking_Up_Resources">

-<title>Looking Up Resources</title>

-<!-- .XS -->

-<!-- (SN Looking Up Resources -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To retrieve a resource from a resource database, use

-<function>XrmGetResource</function>,

-<function>XrmQGetResource</function>,

-or

-<function>XrmQGetSearchResource</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-<indexterm significance="preferred"><primary>XrmGetResource</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XrmGetResource</function></funcdef>

-  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

-  <paramdef>char<parameter> *str_name</parameter></paramdef>

-  <paramdef>char<parameter> *str_class</parameter></paramdef>

-  <paramdef>char<parameter> **str_type_return</parameter></paramdef>

-  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the database that is to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>str_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the fully qualified name of the value being retrieved (as a string).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>str_class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the fully qualified class of the value being retrieved (as a string).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>str_type_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the representation type of the destination (as a string).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the value in the database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-<indexterm significance="preferred"><primary>XrmQGetResource</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XrmQGetResource</function></funcdef>

-  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

-  <paramdef>XrmNameList<parameter> quark_name</parameter></paramdef>

-  <paramdef>XrmClassList<parameter> quark_class</parameter></paramdef>

-  <paramdef>XrmRepresentation<parameter> *quark_type_return</parameter></paramdef>

-  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the database that is to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>quark_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the fully qualified name of the value being retrieved (as a quark).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>quark_class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the fully qualified class of the value being retrieved (as a quark).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>quark_type_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the representation type of the destination (as a quark).

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the value in the database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XrmGetResource</function>

-and 

-<function>XrmQGetResource</function>

-functions retrieve a resource from the specified database.

-Both take a fully qualified name/class pair, a destination

-resource representation, and the address of a value

-(size/address pair).  

-The value and returned type point into database memory;

-therefore, you must not modify the data.

-</para>

-<para>

-<!-- .LP -->

-The database only frees or overwrites entries on

-<function>XrmPutResource</function>,

-<function>XrmQPutResource</function>,

-or 

-<function>XrmMergeDatabases</function>.

-A client that is not storing new values into the database or

-is not merging the database should be safe using the address passed 

-back at any time until it exits.

-If a resource was found, both

-<function>XrmGetResource</function>

-and

-<function>XrmQGetResource</function>

-return 

-<symbol>True</symbol>;

-otherwise, they return 

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-Most applications and toolkits do not make random probes

-into a resource database to fetch resources.

-The X toolkit access pattern for a resource database is quite stylized.

-A series of from 1 to 20 probes is made with only the 

-last name/class differing in each probe.

-The 

-<function>XrmGetResource</function>

-function is at worst a

-2<superscript><emphasis remap='I'>n</emphasis></superscript> algorithm,

-where <emphasis remap='I'>n</emphasis> is the length of the name/class list.

-This can be improved upon by the application programmer by prefetching a list

-of database levels that might match the first part of a name/class list.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a list of database levels, use

-<function>XrmQGetSearchList</function>.

-<indexterm significance="preferred"><primary>XrmQGetSearchList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>

-  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

-  <paramdef>XrmNameList<parameter> names</parameter></paramdef>

-  <paramdef>XrmClassList<parameter> classes</parameter></paramdef>

-  <paramdef>XrmSearchList<parameter> list_return</parameter></paramdef>

-  <paramdef>int<parameter> list_length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the database that is to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>names</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a list of resource names.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>classes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a list of resource classes.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a search list for further use.

-The caller must allocate sufficient space for the list before calling 

-<function>XrmQGetSearchList</function>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list_length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of entries (not the byte size) allocated for list_return.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmQGetSearchList</function>

-function takes a list of names and classes

-and returns a list of database levels where a match might occur.

-The returned list is in best-to-worst order and

-uses the same algorithm as 

-<function>XrmGetResource</function>

-for determining precedence.

-If list_return was large enough for the search list,

-<function>XrmQGetSearchList</function>

-returns 

-<symbol>True</symbol>;

-otherwise, it returns

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-The size of the search list that the caller must allocate is

-dependent upon the number of levels and wildcards in the resource specifiers 

-that are stored in the database.

-The worst case length is

-3<superscript><emphasis remap='I'>n</emphasis></superscript>,

-where <emphasis remap='I'>n</emphasis> is the number of name or class

-components in names or classes.

-</para>

-<para>

-<!-- .LP -->

-When using 

-<function>XrmQGetSearchList</function>

-followed by multiple probes for resources with a common name and class prefix,

-only the common prefix should be specified in the name and class list to 

-<function>XrmQGetSearchList</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To search resource database levels for a given resource, use

-<function>XrmQGetSearchResource</function>.

-<indexterm significance="preferred"><primary>XrmQGetSearchResource</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>

-  <paramdef>XrmSearchList<parameter> list</parameter></paramdef>

-  <paramdef>XrmName<parameter> name</parameter></paramdef>

-  <paramdef>XrmClass<parameter> class</parameter></paramdef>

-  <paramdef>XrmRepresentation<parameter> *type_return</parameter></paramdef>

-  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the search list returned by

-<function>XrmQGetSearchList</function>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource name.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource class.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>type_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns data representation type.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the value in the database.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmQGetSearchResource</function>

-function searches the specified database levels for the resource 

-that is fully identified by the specified name and class.

-The search stops with the first match.

-<function>XrmQGetSearchResource</function>

-returns 

-<symbol>True</symbol>

-if the resource was found;

-otherwise, it returns

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-A call to 

-<function>XrmQGetSearchList</function>

-with a name and class list containing all but the last component 

-of a resource name followed by a call to 

-<function>XrmQGetSearchResource</function>

-with the last component name and class returns the same database entry as 

-<function>XrmGetResource</function>

-and 

-<function>XrmQGetResource</function>

-with the fully qualified name and class.

-</para>

-</sect1>

-<sect1 id="Storing_into_a_Resource_Database">

-<title>Storing into a Resource Database</title>

-<!-- .XS -->

-<!-- (SN Storing into a Resource Database -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To store resources into the database, use

-<function>XrmPutResource</function>

-or

-<function>XrmQPutResource</function>.

-Both functions take a partial resource specification, a

-representation type, and a value.

-This value is copied into the specified database.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-<indexterm significance="preferred"><primary>XrmPutResource</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmPutResource</function></funcdef>

-  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

-  <paramdef>char<parameter> *specifier</parameter></paramdef>

-  <paramdef>char<parameter> *type</parameter></paramdef>

-  <paramdef>XrmValue<parameter> *value</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>specifier</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a complete or partial specification of the resource.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>type</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the type of the resource.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the value of the resource, which is specified as a string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If database contains NULL,

-<function>XrmPutResource</function>

-creates a new database and returns a pointer to it.

-<function>XrmPutResource</function>

-is a convenience function that calls

-<function>XrmStringToBindingQuarkList</function>

-followed by:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)

-</literallayout>

-If the specifier and type are not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-The value is stored in the database without modification.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-<indexterm significance="preferred"><primary>XrmQPutResource</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmQPutResource</function></funcdef>

-  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

-  <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>

-  <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>

-  <paramdef>XrmRepresentation<parameter> type</parameter></paramdef>

-  <paramdef>XrmValue<parameter> *value</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bindings</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a list of bindings.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>quarks</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the complete or partial name or the class list of the resource.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>type</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the type of the resource.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the value of the resource, which is specified as a string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If database contains NULL,

-<function>XrmQPutResource</function>

-creates a new database and returns a pointer to it.

-If a resource entry with the identical bindings and quarks already

-exists in the database, the previous type and value are replaced by the new

-specified type and value.

-The value is stored in the database without modification.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To add a resource that is specified as a string, use

-<function>XrmPutStringResource</function>.

-<indexterm significance="preferred"><primary>XrmPutStringResource</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmPutStringResource</function></funcdef>

-  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

-  <paramdef>char<parameter> *specifier</parameter></paramdef>

-  <paramdef>char<parameter> *value</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>specifier</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a complete or partial specification of the resource.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the value of the resource, which is specified as a string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If database contains NULL,

-<function>XrmPutStringResource</function>

-creates a new database and returns a pointer to it.

-<function>XrmPutStringResource</function>

-adds a resource with the specified value to the specified database.

-<function>XrmPutStringResource</function>

-is a convenience function that first calls

-<function>XrmStringToBindingQuarkList</function>

-on the specifier and then calls

-<function>XrmQPutResource</function>,

-using a ``String'' representation type.

-If the specifier is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-The value is stored in the database without modification.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To add a string resource using quarks as a specification, use

-<function>XrmQPutStringResource</function>.

-<indexterm significance="preferred"><primary>XrmQPutStringResource</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmQPutStringResource</function></funcdef>

-  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

-  <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>

-  <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>

-  <paramdef>char<parameter> *value</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bindings</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a list of bindings.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>quarks</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the complete or partial name or the class list of the resource.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the value of the resource, which is specified as a string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If database contains NULL,

-<function>XrmQPutStringResource</function>

-creates a new database and returns a pointer to it.

-<function>XrmQPutStringResource</function>

-is a convenience routine that constructs an

-<type>XrmValue</type>

-for the value string (by calling

-<function>strlen</function>

-to compute the size) and

-then calls

-<function>XrmQPutResource</function>,

-using a ``String'' representation type.

-The value is stored in the database without modification.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To add a single resource entry that is specified as a string that contains

-both a name and a value, use

-<function>XrmPutLineResource</function>.

-<indexterm significance="preferred"><primary>XrmPutLineResource</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmPutLineResource</function></funcdef>

-  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

-  <paramdef>char<parameter> *line</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>line</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource name and value pair as a single string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If database contains NULL,

-<function>XrmPutLineResource</function>

-creates a new database and returns a pointer to it.

-<function>XrmPutLineResource</function>

-adds a single resource entry to the specified database.

-The line should be in valid ResourceLine format (see section 15.1)

-terminated by a newline or null character;

-the database that results from using a string

-with incorrect syntax is implementation-dependent.

-The string is parsed in the locale of the database.

-If the

-<replaceable>ResourceName</replaceable>

-is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-Note that comment lines are not stored.

-</para>

-</sect1>

-<sect1 id="Enumerating_Database_Entries">

-<title>Enumerating Database Entries</title>

-<!-- .XS -->

-<!-- (SN Enumerating Database Entries -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To enumerate the entries of a database, use

-<function>XrmEnumerateDatabase</function>.

-<indexterm significance="preferred"><primary>XrmEnumerateDatabase</primary></indexterm>

-<!-- .sM -->

-</para>

-

-<literallayout class="monospaced">

-#define       XrmEnumAllLevels       0

-#define       XrmEnumOneLevel        0

-</literallayout>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XrmEnumerateDatabase</function></funcdef>

-  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>

-  <paramdef>XrmNameList<parameter> name_prefix</parameter></paramdef>

-  <paramdef>XrmClassList<parameter> class_prefix</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-  <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>name_prefix</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource name prefix.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class_prefix</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource class prefix.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of levels to enumerate.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>proc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure that is to be called for each matching entry.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the user-supplied argument that will be passed to the procedure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmEnumerateDatabase</function>

-function calls the specified procedure for each resource in the database

-that would match some completion of the given name/class resource prefix.

-The order in which resources are found is implementation-dependent.

-If mode is

-<symbol>XrmEnumOneLevel</symbol>,

-a resource must match the given name/class prefix with

-just a single name and class appended.  If mode is

-<symbol>XrmEnumAllLevels</symbol>,

-the resource must match the given name/class prefix with one or more names and

-classes appended.

-If the procedure returns

-<symbol>True</symbol>,

-the enumeration terminates and the function returns

-<symbol>True</symbol>.

-If the procedure always returns

-<symbol>False</symbol>,

-all matching resources are enumerated and the function returns

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-The procedure is called with the following arguments:

-</para>

-<para>

-<!-- .LP -->

-<!-- .\" Start marker code here -->

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>database</emphasis>, <emphasis remap='I'>bindings</emphasis>, <emphasis remap='I'>quarks</emphasis>, <emphasis remap='I'>type</emphasis>, <emphasis remap='I'>value</emphasis>, <emphasis remap='I'>arg</emphasis>)

-     XrmDatabase *<emphasis remap='I'>database</emphasis>;

-     XrmBindingList <emphasis remap='I'>bindings</emphasis>;

-     XrmQuarkList <emphasis remap='I'>quarks</emphasis>;

-     XrmRepresentation *<emphasis remap='I'>type</emphasis>;

-     XrmValue *<emphasis remap='I'>value</emphasis>;

-     XPointer <emphasis remap='I'>arg</emphasis>;

-</literallayout>

-<!-- .\" End marker code here -->

-</para>

-<para>

-<!-- .LP -->

-The bindings and quarks lists are terminated by

-<symbol>NULLQUARK</symbol>.

-Note that pointers

-to the database and type are passed, but these values should not be modified.

-</para>

-<para>

-<!-- .LP -->

-The procedure must not modify the database.

-If Xlib has been initialized for threads, the procedure is called with

-the database locked and the result of a call by the procedure to any

-Xlib function using the same database is not defined.

-</para>

-</sect1>

-<sect1 id="Parsing_Command_Line_Options">

-<title>Parsing Command Line Options</title>

-<!-- .XS -->

-<!-- (SN Parsing Command Line Options  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The

-<function>XrmParseCommand</function>

-function can be used to parse the command line arguments to a program

-and modify a resource database with selected entries from the command line.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XrmOptionKind</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef enum {

-     XrmoptionNoArg,     /* Value is specified in XrmOptionDescRec.value */

-     XrmoptionIsArg,     /* Value is the option string itself */

-     XrmoptionStickyArg,     /* Value is characters immediately following option */

-     XrmoptionSepArg,     /* Value is next argument in argv */

-     XrmoptionResArg,     /* Resource and value in next argument in argv */

-     XrmoptionSkipArg,     /* Ignore this option and the next argument in argv */

-     XrmoptionSkipLine,     /* Ignore this option and the rest of argv */

-     XrmoptionSkipNArgs     /* Ignore this option and the next

-          \ \ \ XrmOptionDescRec.value arguments in argv */

-} XrmOptionKind;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Note that

-<constant>XrmoptionSkipArg</constant>

-is equivalent to 

-<constant>XrmoptionSkipNArgs</constant>

-with the

-<structname>XrmOptionDescRec</structname>.<structfield>value</structfield>

-field containing the value one.

-Note also that the value zero for

-<constant>XrmoptionSkipNArgs</constant>

-indicates that only the option itself is to be skipped.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XrmOptionDescRec</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-     char *option;     /* Option specification string in argv              */

-     char *specifier;     /* Binding and resource name (sans application name)    */

-     XrmOptionKind argKind;     /* Which style of option it is         */

-     XPointer value;     /* Value to provide if XrmoptionNoArg or 

-          \ \ \ XrmoptionSkipNArgs   */

-} XrmOptionDescRec, *XrmOptionDescList;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To load a resource database from a C command line, use

-<function>XrmParseCommand</function>.

-<indexterm significance="preferred"><primary>XrmParseCommand</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XrmParseCommand</function></funcdef>

-  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>

-  <paramdef>XrmOptionDescList<parameter> table</parameter></paramdef>

-  <paramdef>int<parameter> table_count</parameter></paramdef>

-  <paramdef>char<parameter> *name</parameter></paramdef>

-  <paramdef>int<parameter> *argc_in_out</parameter></paramdef>

-  <paramdef>char<parameter> **argv_in_out</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>database</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>table</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the table of command line arguments to be parsed.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>table_count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of entries in the table.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the application name.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argc_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of arguments and returns the number of remaining arguments.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>argv_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the command line arguments

-and returns the remaining arguments.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XrmParseCommand</function>

-function parses an (argc, argv) pair according to the specified option table,

-loads recognized options into the specified database with type ``String,''

-and modifies the (argc, argv) pair to remove all recognized options.

-If database contains NULL,

-<function>XrmParseCommand</function>

-creates a new database and returns a pointer to it.

-Otherwise, entries are added to the database specified.

-If a database is created, it is created in the current locale.

-</para>

-<para>

-<!-- .LP -->

-The specified table is used to parse the command line.

-Recognized options in the table are removed from argv,

-and entries are added to the specified resource database

-in the order they occur in argv.

-The table entries contain information on the option string,

-the option name, the style of option, 

-and a value to provide if the option kind is 

-<constant>XrmoptionNoArg</constant>.

-The option names are compared byte-for-byte to arguments in argv,

-independent of any locale.

-The resource values given in the table are stored in the resource database

-without modification.

-All resource database entries are created

-using a ``String'' representation type.

-The argc argument specifies the number of arguments in argv

-and is set on return to the remaining number of arguments that were not parsed.

-The name argument should be the name of your application

-for use in building the database entry.

-The name argument is prefixed to the resourceName in the option table

-before storing a database entry.

-The name argument is treated as a single component, even if it

-has embedded periods.

-No separating (binding) character is inserted,

-so the table must contain either a period (.) or an asterisk (*)

-as the first character in each resourceName entry.

-To specify a more completely qualified resource name,

-the resourceName entry can contain multiple components.

-If the name argument and the resourceNames are not in the

-Host Portable Character Encoding,

-the result is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-The following provides a sample option table:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-<!-- .TA 1.25i 3.25i 4.75i -->

-<!-- .ta 1.25i 3.25i 4.75i -->

-static XrmOptionDescRec opTable[] = {

-{"-background",     "*background",                 XrmoptionSepArg,    (XPointer) NULL},

-{"-bd",             "*borderColor",                XrmoptionSepArg,    (XPointer) NULL},

-{"-bg",             "*background",                 XrmoptionSepArg,    (XPointer) NULL},

-{"-borderwidth",    "*TopLevelShell.borderWidth",  XrmoptionSepArg,    (XPointer) NULL},

-{"-bordercolor",    "*borderColor",                XrmoptionSepArg,    (XPointer) NULL},

-{"-bw",             "*TopLevelShell.borderWidth",  XrmoptionSepArg,    (XPointer) NULL},

-{"-display",        ".display",                    XrmoptionSepArg,    (XPointer) NULL},

-{"-fg",             "*foreground",                 XrmoptionSepArg,    (XPointer) NULL},

-{"-fn",             "*font",                       XrmoptionSepArg,    (XPointer) NULL},

-{"-font",           "*font",                       XrmoptionSepArg,    (XPointer) NULL},

-{"-foreground",     "*foreground",                 XrmoptionSepArg,    (XPointer) NULL},

-{"-geometry",       ".TopLevelShell.geometry",     XrmoptionSepArg,    (XPointer) NULL},

-{"-iconic",         ".TopLevelShell.iconic",       XrmoptionNoArg,     (XPointer) "on"},

-{"-name",           ".name",                       XrmoptionSepArg,    (XPointer) NULL},

-{"-reverse",        "*reverseVideo",               XrmoptionNoArg,     (XPointer) "on"},

-{"-rv",             "*reverseVideo",               XrmoptionNoArg,     (XPointer) "on"},

-{"-synchronous",    "*synchronous",                XrmoptionNoArg,     (XPointer) "on"},

-{"-title",          ".TopLevelShell.title",        XrmoptionSepArg,    (XPointer) NULL},

-{"-xrm",            NULL,                          XrmoptionResArg,    (XPointer) NULL},

-};

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-In this table, if the -background (or -bg) option is used to set

-background colors, the stored resource specifier matches all

-resources of attribute background.  

-If the -borderwidth option is used, 

-the stored resource specifier applies only to border width

-attributes of class TopLevelShell (that is, outer-most windows, including

-pop-up windows).  

-If the -title option is used to set a window name,

-only the topmost application windows receive the resource.

-</para>

-<para>

-<!-- .LP -->

-When parsing the command line,

-any unique unambiguous abbreviation for an option name in the table is 

-considered a match for the option.

-Note that uppercase and lowercase matter.

-<!-- .bp -->

-

-</para>

-</sect1>

-</chapter>

+<?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="resource_manager_functions">
+<title>Resource Manager Functions</title>
+<!-- .sp 2 -->
+<!-- .nr H1 15 -->
+<!-- .nr H2 0 -->
+<!-- .nr H3 0 -->
+<!-- .nr H4 0 -->
+<!-- .nr H5 0 -->
+<!-- .na -->
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Chapter 15: Resource Manager Functions -->
+<!-- .XE -->
+A program often needs a variety of options in the X environment
+(for example, fonts, colors, icons, and cursors).
+Specifying all of these options on the command line is awkward
+because users may want to customize many aspects of the program
+and need a convenient way to establish these customizations as
+the default settings.
+The resource manager is provided for this purpose.
+Resource specifications are usually stored in human-readable files
+and in server properties.
+</para>
+<para>
+<!-- .LP -->
+The resource manager is a database manager with a twist.
+In most database systems, 
+you perform a query using an imprecise specification,
+and you get back a set of records.
+The resource manager, however, allows you to specify a large
+set of values with an imprecise specification, to query the database 
+with a precise specification, and to get back only a single value.
+This should be used by applications that need to know what the
+user prefers for colors, fonts, and other resources.
+It is this use as a database for dealing with X resources that
+inspired the name "Resource Manager,"
+although the resource manager can be and is used in other ways.
+</para>
+<para>
+<!-- .LP -->
+For example, 
+a user of your application may want to specify 
+that all windows should have a blue background 
+but that all mail-reading windows should have a red background.
+With well-engineered and coordinated applications,
+a user can define this information using only two lines of specifications.
+</para>
+<para>
+<!-- .LP -->
+As an example of how the resource manager works,
+consider a mail-reading application called xmh.
+Assume that it is designed so that it uses a
+complex window hierarchy all the way down to individual command buttons,
+which may be actual small subwindows in some toolkits.
+These are often called objects or widgets.
+In such toolkit systems,
+each user interface object can be composed of other objects
+and can be assigned a name and a class.
+Fully qualified names or classes can have arbitrary numbers of component names,
+but a fully qualified name always has the same number of component names as a
+fully qualified class.
+This generally reflects the structure of the application as composed
+of these objects, starting with the application itself.
+</para>
+<para>
+<!-- .LP -->
+For example, the xmh mail program has a name "xmh" and is one
+of a class of "Mail" programs.
+By convention, the first character of class components is capitalized,
+and the first letter of name components is in lowercase.
+Each name and class finally has an attribute
+(for example, "foreground" or "font").
+If each window is properly assigned a name and class,
+it is easy for the user to specify attributes of any portion 
+of the application.
+</para>
+<para>
+<!-- .LP -->
+At the top level, 
+the application might consist of a paned window (that is, a window divided
+into several sections) named "toc".
+One pane of the paned window is a button box window named "buttons"
+and is filled with command buttons. 
+One of these command buttons is used to incorporate
+new mail and has the name "incorporate".
+This window has a fully qualified name, "xmh.toc.buttons.incorporate",
+and a fully qualified class, "Xmh.Paned.Box.Command".
+Its fully qualified name is the name of its parent, "xmh.toc.buttons", 
+followed by its name, "incorporate".
+Its class is the class of its parent, "Xmh.Paned.Box", 
+followed by its particular class, "Command".  
+The fully qualified name of a resource is
+the attribute's name appended to the object's fully qualified
+name, and the fully qualified class is its class appended to the object's
+class.
+</para>
+<para>
+<!-- .LP -->
+The incorporate button might need the following resources: 
+Title string,
+Font,
+Foreground color for its inactive state,
+Background color for its inactive state,
+Foreground color for its active state, and
+Background color for its active state.
+Each resource is considered
+to be an attribute of the button and, as such, has a name and a class.
+For example, the foreground color for the button in
+its active state might be named "activeForeground",
+and its class might be "Foreground".
+</para>
+<para>
+<!-- .LP -->
+When an application looks up a resource (for example, a color),
+it passes the complete name and complete class of the resource
+to a look-up routine.
+The resource manager compares this complete specification
+against the incomplete specifications of entries in the resource
+database, finds the best match, and returns the corresponding
+value for that entry.
+</para>
+<para>
+<!-- .LP -->
+The definitions for the resource manager are contained in
+<filename class="headerfile">&lt;X11/Xresource.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xresource.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xresource.h&gt;</filename></secondary></indexterm>
+</para>
+<sect1 id="Resource_File_Syntax">
+<title>Resource File Syntax</title>
+<!-- .XS -->
+<!-- (SN Resource File Syntax -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The syntax of a resource file is a sequence of resource lines
+terminated by newline characters or the end of the file.
+The syntax of an individual resource line is:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+<!-- .TA 1.5i 1.75i -->
+<!-- .ta 1.5i 1.75i -->
+ResourceLine     =     Comment | IncludeFile | ResourceSpec | &lt;empty line&gt;
+Comment     =     "!" {&lt;any character except null or newline&gt;}
+IncludeFile     =     "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
+FileName     =     &lt;valid filename for operating system&gt;
+ResourceSpec     =     WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
+ResourceName     =     [Binding] {Component Binding} ComponentName
+Binding     =     "." | "*"
+WhiteSpace     =     {&lt;space&gt; | &lt;horizontal tab&gt;}
+Component     =     "?" | ComponentName
+ComponentName     =     NameChar {NameChar}
+NameChar     =     "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
+Value     =     {&lt;any character except null or unescaped newline&gt;}
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+Elements separated by vertical bar (|) are alternatives.
+Curly braces ({......}) indicate zero or more repetitions
+of the enclosed elements.
+Square brackets ([......]) indicate that the enclosed element is optional.
+Quotes ("......") are used around literal characters.
+</para>
+<para>
+<!-- .LP -->
+IncludeFile lines are interpreted by replacing the line with the
+contents of the specified file.
+The word "include" must be in lowercase.
+The file name is interpreted relative to the directory of the file in
+which the line occurs (for example, if the file name contains no
+directory or contains a relative directory specification).
+</para>
+<para>
+<!-- .LP -->
+If a ResourceName contains a contiguous sequence of two or more Binding
+characters, the sequence will be replaced with a single ".." character
+if the sequence contains only ".." characters;
+otherwise, the sequence will be replaced with a single "*" character.
+</para>
+<para>
+<!-- .LP -->
+A resource database never contains more than one entry for a given
+ResourceName.  If a resource file contains multiple lines with the
+same ResourceName, the last line in the file is used.
+</para>
+<para>
+<!-- .LP -->
+Any white space characters before or after the name or colon in a ResourceSpec
+are ignored.
+To allow a Value to begin with white space,
+the two-character sequence "\\<emphasis remap='I'>space</emphasis>" (backslash followed by space)
+is recognized and replaced by a space character,
+and the two-character sequence "\\<emphasis remap='I'>tab</emphasis>"
+(backslash followed by horizontal tab)
+is recognized and replaced by a horizontal tab character.
+To allow a Value to contain embedded newline characters,
+the two-character sequence "\\n" is recognized and replaced by a
+newline character.
+To allow a Value to be broken across multiple lines in a text file,
+the two-character sequence "\\<emphasis remap='I'>newline</emphasis>"
+(backslash followed by newline) is
+recognized and removed from the value.
+To allow a Value to contain arbitrary character codes,
+the four-character sequence "\\<emphasis remap='I'>nnn</emphasis>",
+where each <emphasis remap='I'>n</emphasis> is a digit character in the range of "0"-"7",
+is recognized and replaced with a single byte that contains
+the octal value specified by the sequence.
+Finally, the two-character sequence "\newline" is recognized
+and replaced with a single backslash.
+</para>
+<para>
+<!-- .LP -->
+As an example of these sequences,
+the following resource line contains a value consisting of four
+characters: a backslash, a null, a "z", and a newline:
+<literallayout class="monospaced">
+magic.values: \\000\
+z\n
+</literallayout>
+</para>
+</sect1>
+<sect1 id="Resource_Manager_Matching_Rules">
+<title>Resource Manager Matching Rules</title>
+<!-- .XS -->
+<!-- (SN Resource Manager Matching Rules -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The algorithm for determining which resource database entry
+matches a given query is the heart of the resource manager.
+All queries must fully specify the name and class of the desired resource
+(use of the characters "*" and "?" is not permitted).
+The library supports up to 100 components in a full name or class.
+Resources are stored in the database with only partially specified
+names and classes, using pattern matching constructs.
+An asterisk (*) is a loose binding and is used to represent any number
+of intervening components, including none.
+A period (.) is a tight binding and is used to separate immediately
+adjacent components.
+A question mark (?) is used to match any single component name or class.
+A database entry cannot end in a loose binding;
+the final component (which cannot be the character "?") must be specified.
+The lookup algorithm searches the database for the entry that most
+closely matches (is most specific for) the full name and class being queried.
+When more than one database entry matches the full name and class,
+precedence rules are used to select just one.
+</para>
+<para>
+<!-- .LP -->
+The full name and class are scanned from left to right (from highest
+level in the hierarchy to lowest), one component at a time.
+At each level, the corresponding component and/or binding of each
+matching entry is determined, and these matching components and
+bindings are compared according to precedence rules.
+Each of the rules is applied at each level before moving to the next level,
+until a rule selects a single entry over all others.
+The rules, in order of precedence, are:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+An entry that contains a matching component (whether name, class,
+or the character "?")
+takes precedence over entries that elide the level (that is, entries
+that match the level in a loose binding).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+An entry with a matching name takes precedence over both
+entries with a matching class and entries that match using the character "?".
+An entry with a matching class takes precedence over
+entries that match using the character "?".
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+An entry preceded by a tight binding takes precedence over entries
+preceded by a loose binding.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To illustrate these rules,
+consider the following resource database entries:
+<literallayout class="monospaced">
+<!-- .TA 2.5i 3.5i -->
+<!-- .ta 2.5i 3.5i -->
+xmh*Paned*activeForeground:     red     <emphasis remap='I'>(entry A)</emphasis>
+*incorporate.Foreground:     blue     <emphasis remap='I'>(entry B)</emphasis>
+xmh.toc*Command*activeForeground:     green     <emphasis remap='I'>(entry C)</emphasis>
+xmh.toc*?.Foreground:     white     <emphasis remap='I'>(entry D)</emphasis>
+xmh.toc*Command.activeForeground:     black     <emphasis remap='I'>(entry E)</emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Consider a query for the resource:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 3.5i -->
+<!-- .ta 3.5i -->
+xmh.toc.messagefunctions.incorporate.activeForeground     <emphasis remap='I'>(name)</emphasis>
+Xmh.Paned.Box.Command.Foreground     <emphasis remap='I'>(class)</emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+At the first level (xmh, Xmh), rule 1 eliminates entry B.
+At the second level (toc, Paned), rule 2 eliminates entry A.
+At the third level (messagefunctions, Box), no entries are eliminated.
+At the fourth level (incorporate, Command), rule 2 eliminates entry D.
+At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.
+</para>
+</sect1>
+<sect1 id="Quarks">
+<title>Quarks</title>
+<!-- .XS -->
+<!-- (SN Quarks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Most uses of the resource manager involve defining names,
+classes, and representation types as string constants.
+However, always referring to strings in the resource manager can be slow,
+because it is so heavily used in some toolkits.
+To solve this problem, 
+a shorthand for a string is used in place of the string
+in many of the resource manager functions.
+Simple comparisons can be performed rather than string comparisons.
+The shorthand name for a string is called a quark and is the
+type 
+<type>XrmQuark</type>.
+On some occasions,
+you may want to allocate a quark that has no string equivalent.
+</para>
+<para>
+<!-- .LP -->
+A quark is to a string what an atom is to a string in the server,
+but its use is entirely local to your application.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a new quark, use
+<function>XrmUniqueQuark</function>.
+</para>
+<indexterm significance="preferred"><primary>XrmUniqueQuark</primary></indexterm>
+<!-- .sM -->
+<para>XrmQuark XrmUniqueQuark()</para>
+<!-- .FN -->
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmUniqueQuark</function>
+function allocates a quark that is guaranteed not to represent any string that
+is known to the resource manager.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Each name, class, and representation type is typedef'd as an
+<type>XrmQuark</type>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+typedef int XrmQuark, *XrmQuarkList;
+typedef XrmQuark XrmName;
+typedef XrmQuark XrmClass;
+typedef XrmQuark XrmRepresentation;
+#define NULLQUARK ((XrmQuark) 0)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Lists are represented as null-terminated arrays of quarks.
+The size of the array must be large enough for the number of components used.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+typedef XrmQuarkList XrmNameList;
+typedef XrmQuarkList XrmClassList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To convert a string to a quark, use
+<function>XrmStringToQuark</function>
+or
+<function>XrmPermStringToQuark</function>.
+</para>
+<literallayout class="monospaced">
+#define XrmStringToName(string) XrmStringToQuark(string)
+#define XrmStringToClass(string) XrmStringToQuark(string)
+#define XrmStringToRepresentation(string) XrmStringToQuark(string)
+</literallayout>
+
+<indexterm significance="preferred"><primary>XrmStringToQuark</primary></indexterm>
+<indexterm significance="preferred"><primary>XrmPermStringToQuark</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmstringtoquark'>
+<funcprototype>
+  <funcdef>XrmQuark <function>XrmStringToQuark</function></funcdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the string for which a quark(Ql is to be allocated.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+These functions can be used to convert from string to quark representation.
+If the string is not in the Host Portable Character Encoding,
+the conversion is implementation-dependent.
+The string argument to
+<function>XrmStringToQuark</function>
+need not be permanently allocated storage.
+<function>XrmPermStringToQuark</function>
+is just like
+<function>XrmStringToQuark</function>,
+except that Xlib is permitted to assume the string argument is permanently
+allocated,
+and, hence, that it can be used as the value to be returned by
+<function>XrmQuarkToString</function>.
+</para>
+<para>
+<!-- .LP -->
+For any given quark, if
+<function>XrmStringToQuark</function>
+returns a non-NULL value,
+all future calls will return the same value (identical address).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a quark to a string, use 
+<function>XrmQuarkToString</function>.
+</para>
+
+<literallayout class="monospaced">
+#define XrmNameToString(name)  XrmQuarkToString(name)
+#define XrmClassToString(class)  XrmQuarkToString(name)
+#define XrmRepresentationToString(type)  XrmQuarkToString(type)
+</literallayout>
+<indexterm significance="preferred"><primary>XrmQuarkToString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmquarktostring'>
+<funcprototype>
+  <funcdef>char *<function>XrmQuarkToString</function></funcdef>
+  <paramdef>XrmQuark<parameter> quark</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>quark</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the quark for which the equivalent string is desired.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+<!-- AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -->
+<para>
+These functions can be used to convert from quark representation to string.
+The string pointed to by the return value must not be modified or freed.
+The returned string is byte-for-byte equal to the original
+string passed to one of the string-to-quark routines.
+If no string exists for that quark,
+<function>XrmQuarkToString</function>
+returns NULL.
+For any given quark, if
+<function>XrmQuarkToString</function>
+returns a non-NULL value,
+all future calls will return the same value (identical address).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a string with one or more components to a quark list, use
+<function>XrmStringToQuarkList</function>.
+</para>
+
+<literallayout class="monospaced">
+#define XrmStringToNameList(str,name)  XrmStringToQuarkList((str), (name))
+#define XrmStringToClassList(str,class)  XrmStringToQuarkList((str), (class))
+</literallayout>
+
+<indexterm significance="preferred"><primary>XrmStringToQuarkList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmstringtoquarklist'>
+<funcprototype>
+  <funcdef>void <function>XrmStringToQuarkList</function></funcdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql \ list -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the string for which a quark(Ql is to be allocated.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>quarks_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the list of quarks.
+The caller must allocate sufficient space for the quarks list before calling 
+<function>XrmStringToQuarkList</function>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmStringToQuarkList</function>
+function converts the null-terminated string (generally a fully qualified name)
+to a list of quarks.
+Note that the string must be in the valid ResourceName format 
+(see section 15.1).
+If the string is not in the Host Portable Character Encoding,
+the conversion is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+A binding list is a list of type
+<type>XrmBindingList</type>
+and indicates if components of name or class lists are bound tightly or loosely
+(that is, if wildcarding of intermediate components is specified).
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<constant>XrmBindTightly</constant>
+indicates that a period separates the components, and
+<constant>XrmBindLoosely</constant>
+indicates that an asterisk separates the components.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a string with one or more components to a binding list
+and a quark list, use
+<function>XrmStringToBindingQuarkList</function>.
+<indexterm significance="preferred"><primary>XrmStringToBindingQuarkList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmstringtobindingquarklist'>
+<funcprototype>
+  <funcdef><function>XrmStringToBindingQuarkList</function></funcdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+  <paramdef>XrmBindingList<parameter> bindings_return</parameter></paramdef>
+  <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql \ list -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the string for which a quark(Ql is to be allocated.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bindings_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the binding list.
+The caller must allocate sufficient space for the binding list before calling 
+<function>XrmStringToBindingQuarkList</function>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>quarks_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the list of quarks.
+The caller must allocate sufficient space for the quarks list before calling 
+<function>XrmStringToBindingQuarkList</function>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Component names in the list are separated by a period or 
+an asterisk character.
+The string must be in the format of a valid ResourceName (see section 15.1).
+If the string does not start with a period or an asterisk, 
+a tight binding is assumed.
+For example, the string ``*a.b*c'' becomes:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .75i 1.5i 2.25i -->
+<!-- .ta .75i 1.5i 2.25i -->
+quarks:       a         b         c
+bindings:     loose     tight     loose
+</literallayout>
+</para>
+</sect1>
+<sect1 id="Creating_and_Storing_Databases">
+<title>Creating and Storing Databases</title>
+<!-- .XS -->
+<!-- (SN Creating and Storing Databases -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmDatabase</primary></indexterm>
+A resource database is an opaque type,
+<type>XrmDatabase</type>.
+Each database value is stored in an
+<type>XrmValue</type>
+structure.
+This structure consists of a size, an address, and a representation type.
+The size is specified in bytes.
+The representation type is a way for you to store data tagged by some 
+application-defined type (for example, the strings ``font'' or ``color'').
+It has nothing to do with the C data type or with its class. 
+The
+<type>XrmValue</type>
+structure is defined as:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmValue</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     unsigned int size;
+     XPointer addr;
+} XrmValue, *XrmValuePtr;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To initialize the resource manager, use
+<function>XrmInitialize</function>.
+<indexterm significance="preferred"><primary>XrmInitialize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrminitialize'>
+<funcprototype>
+  <funcdef>void <function>XrmInitialize</function></funcdef>
+  <paramdef>void<parameter> XrmInitialize(\|)</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To retrieve a database from disk, use
+<function>XrmGetFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmgetfiledatabase'>
+<funcprototype>
+  <funcdef>XrmDatabase <function>XrmGetFileDatabase</function></funcdef>
+  <paramdef>char<parameter> *filename</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>filename</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database file name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetFileDatabase</function>
+function opens the specified file,
+creates a new resource database, and loads it with the specifications
+read in from the specified file.
+The specified file should contain a sequence of entries in valid ResourceLine
+format (see section 15.1); the database that results from reading a file
+with incorrect syntax is implementation-dependent.
+The file is parsed in the current locale, 
+and the database is created in the current locale.
+If it cannot open the specified file,
+<function>XrmGetFileDatabase</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store a copy of a database to disk, use
+<function>XrmPutFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmPutFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmputfiledatabase'>
+<funcprototype>
+  <funcdef>void <function>XrmPutFileDatabase</function></funcdef>
+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+  <paramdef>char<parameter> *stored_db</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the database that is to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>stored_db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the file name for the stored database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmPutFileDatabase</function>
+function stores a copy of the specified database in the specified file.
+Text is written to the file as a sequence of entries in valid
+ResourceLine format (see section 15.1).
+The file is written in the locale of the database.
+Entries containing resource names that are not in the Host Portable Character
+Encoding or containing values that are not in the encoding of the database
+locale, are written in an implementation-dependent manner.
+The order in which entries are written is implementation-dependent.
+Entries with representation types other than ``String'' are ignored.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a pointer to the screen-independent resources of a display, use
+<function>XResourceManagerString</function>.
+<indexterm significance="preferred"><primary>XResourceManagerString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xresourcemanagerstring'>
+<funcprototype>
+  <funcdef>char *<function>XResourceManagerString</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XResourceManagerString</function>
+function returns the RESOURCE_MANAGER property from the server's root
+window of screen zero, which was returned when the connection was opened using
+<function>XOpenDisplay</function>.
+The property is converted from type STRING to the current locale.
+The conversion is identical to that produced by 
+<function>XmbTextPropertyToTextList</function>
+for a single element STRING property.
+The returned string is owned by Xlib and should not be freed by the client.
+The property value must be in a format that is acceptable to
+<function>XrmGetStringDatabase</function>.
+If no property exists, NULL is returned.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a pointer to the screen-specific resources of a screen, use
+<function>XScreenResourceString</function>.
+<indexterm significance="preferred"><primary>XScreenResourceString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xscreenresourcestring'>
+<funcprototype>
+  <funcdef>char *<function>XScreenResourceString</function></funcdef>
+  <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the screen.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XScreenResourceString</function>
+function returns the SCREEN_RESOURCES property from the root window of the
+specified screen.
+The property is converted from type STRING to the current locale.
+The conversion is identical to that produced by 
+<function>XmbTextPropertyToTextList</function>
+for a single element STRING property.
+The property value must be in a format that is acceptable to
+<function>XrmGetStringDatabase</function>.
+If no property exists, NULL is returned.
+The caller is responsible for freeing the returned string by using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a database from a string, use
+<function>XrmGetStringDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetStringDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmgetstringdatabase'>
+<funcprototype>
+  <funcdef>XrmDatabase <function>XrmGetStringDatabase</function></funcdef>
+  <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the database contents using a string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetStringDatabase</function>
+function creates a new database and stores the resources specified
+in the specified null-terminated string.
+<function>XrmGetStringDatabase</function>
+is similar to
+<function>XrmGetFileDatabase</function>
+except that it reads the information out of a string instead of out of a file.
+The string should contain a sequence of entries in valid ResourceLine
+format (see section 15.1) terminated by a null character;
+the database that results from using a string
+with incorrect syntax is implementation-dependent.
+The string is parsed in the current locale, 
+and the database is created in the current locale.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the locale name of a database, use
+<function>XrmLocaleOfDatabase</function>.
+<indexterm significance="preferred"><primary>XrmLocaleOfDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmlocaleofdatabase'>
+<funcprototype>
+  <funcdef>char *<function>XrmLocaleOfDatabase</function></funcdef>
+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmLocaleOfDatabase</function>
+function returns the name of the locale bound to the specified
+database, as a null-terminated string.
+The returned locale name string is owned by Xlib and should not be
+modified or freed by the client.
+Xlib is not permitted to free the string until the database is destroyed.
+Until the string is freed,
+it will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy a resource database and free its allocated memory, use
+<function>XrmDestroyDatabase</function>.
+<indexterm significance="preferred"><primary>XrmDestroyDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmdestroydatabase'>
+<funcprototype>
+  <funcdef>void <function>XrmDestroyDatabase</function></funcdef>
+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database is NULL,
+<function>XrmDestroyDatabase</function>
+returns immediately.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To associate a resource database with a display, use
+<function>XrmSetDatabase</function>.
+<indexterm significance="preferred"><primary>XrmSetDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmsetdatabase'>
+<funcprototype>
+  <funcdef>void <function>XrmSetDatabase</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmSetDatabase</function>
+function associates the specified resource database (or NULL)
+with the specified display.
+The database previously associated with the display (if any) is not destroyed.
+A client or toolkit may find this function convenient for retaining a database
+once it is constructed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the resource database associated with a display, use
+<function>XrmGetDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmgetdatabase'>
+<funcprototype>
+  <funcdef>XrmDatabase <function>XrmGetDatabase</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetDatabase</function>
+function returns the database associated with the specified display.
+It returns NULL if a database has not yet been set.
+</para>
+</sect1>
+<sect1 id="Merging_Resource_Databases">
+<title>Merging Resource Databases</title>
+<!-- .XS -->
+<!-- (SN Merging Resource Databases -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To merge the contents of a resource file into a database, use
+<function>XrmCombineFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmCombineFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmcombinefiledatabase'>
+<funcprototype>
+  <funcdef>Status <function>XrmCombineFileDatabase</function></funcdef>
+  <paramdef>char<parameter> *filename</parameter></paramdef>
+  <paramdef>XrmDatabase<parameter> *target_db</parameter></paramdef>
+  <paramdef>Bool<parameter> override</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>filename</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database file name.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database into which the source 
+database is to be merged.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>override</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies whether source entries override target ones.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XrmCombineFileDatabase</function>
+function merges the contents of a resource file into a database.
+If the same specifier is used for an entry in both the file and
+the database,
+the entry in the file will replace the entry in the database
+if override is
+<symbol>True</symbol>;
+otherwise, the entry in the file is discarded.
+The file is parsed in the current locale.
+If the file cannot be read,
+a zero status is returned;
+otherwise, a nonzero status is returned.
+If target_db contains NULL,
+<function>XrmCombineFileDatabase</function>
+creates and returns a new database to it.
+Otherwise, the database pointed to by target_db is not destroyed by the merge.
+The database entries are merged without changing values or types,
+regardless of the locale of the database.
+The locale of the target database is not modified.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To merge the contents of one database into another database, use
+<function>XrmCombineDatabase</function>.
+<indexterm significance="preferred"><primary>XrmCombineDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmcombinedatabase'>
+<funcprototype>
+  <funcdef>void <function>XrmCombineDatabase</function></funcdef>
+  <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
+  <paramdef>Bool<parameter> override</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>source_db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database that is to be merged into the target database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database into which the source 
+database is to be merged.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>override</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies whether source entries override target ones.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XrmCombineDatabase</function>
+function merges the contents of one database into another.
+If the same specifier is used for an entry in both databases,
+the entry in the source_db will replace the entry in the target_db
+if override is
+<symbol>True</symbol>;
+otherwise, the entry in source_db is discarded.
+If target_db contains NULL,
+<function>XrmCombineDatabase</function>
+simply stores source_db in it.
+Otherwise, source_db is destroyed by the merge, but the database pointed
+to by target_db is not destroyed.
+The database entries are merged without changing values or types,
+regardless of the locales of the databases.
+The locale of the target database is not modified.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To merge the contents of one database into another database with override
+semantics, use
+<function>XrmMergeDatabases</function>.
+<indexterm significance="preferred"><primary>XrmMergeDatabases</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmmergedatabases'>
+<funcprototype>
+  <funcdef>void <function>XrmMergeDatabases</function></funcdef>
+  <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>source_db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database that is to be merged into the target database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target_db</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database into which the source 
+database is to be merged.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+Calling the
+<function>XrmMergeDatabases</function>
+function is equivalent to calling the
+<function>XrmCombineDatabase</function>
+function with an override argument of
+<symbol>True</symbol>.
+</para>
+</sect1>
+<sect1 id="Looking_Up_Resources">
+<title>Looking Up Resources</title>
+<!-- .XS -->
+<!-- (SN Looking Up Resources -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To retrieve a resource from a resource database, use
+<function>XrmGetResource</function>,
+<function>XrmQGetResource</function>,
+or
+<function>XrmQGetSearchResource</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmGetResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmgetresource'>
+<funcprototype>
+  <funcdef>Bool <function>XrmGetResource</function></funcdef>
+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+  <paramdef>char<parameter> *str_name</parameter></paramdef>
+  <paramdef>char<parameter> *str_class</parameter></paramdef>
+  <paramdef>char<parameter> **str_type_return</parameter></paramdef>
+  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the database that is to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>str_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the fully qualified name of the value being retrieved (as a string).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>str_class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the fully qualified class of the value being retrieved (as a string).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>str_type_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the representation type of the destination (as a string).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the value in the database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmQGetResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqgetresource'>
+<funcprototype>
+  <funcdef>Bool <function>XrmQGetResource</function></funcdef>
+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+  <paramdef>XrmNameList<parameter> quark_name</parameter></paramdef>
+  <paramdef>XrmClassList<parameter> quark_class</parameter></paramdef>
+  <paramdef>XrmRepresentation<parameter> *quark_type_return</parameter></paramdef>
+  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the database that is to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>quark_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the fully qualified name of the value being retrieved (as a quark).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>quark_class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the fully qualified class of the value being retrieved (as a quark).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>quark_type_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the representation type of the destination (as a quark).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the value in the database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XrmGetResource</function>
+and 
+<function>XrmQGetResource</function>
+functions retrieve a resource from the specified database.
+Both take a fully qualified name/class pair, a destination
+resource representation, and the address of a value
+(size/address pair).  
+The value and returned type point into database memory;
+therefore, you must not modify the data.
+</para>
+<para>
+<!-- .LP -->
+The database only frees or overwrites entries on
+<function>XrmPutResource</function>,
+<function>XrmQPutResource</function>,
+or 
+<function>XrmMergeDatabases</function>.
+A client that is not storing new values into the database or
+is not merging the database should be safe using the address passed 
+back at any time until it exits.
+If a resource was found, both
+<function>XrmGetResource</function>
+and
+<function>XrmQGetResource</function>
+return 
+<symbol>True</symbol>;
+otherwise, they return 
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Most applications and toolkits do not make random probes
+into a resource database to fetch resources.
+The X toolkit access pattern for a resource database is quite stylized.
+A series of from 1 to 20 probes is made with only the 
+last name/class differing in each probe.
+The 
+<function>XrmGetResource</function>
+function is at worst a
+2<superscript><emphasis remap='I'>n</emphasis></superscript> algorithm,
+where <emphasis remap='I'>n</emphasis> is the length of the name/class list.
+This can be improved upon by the application programmer by prefetching a list
+of database levels that might match the first part of a name/class list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a list of database levels, use
+<function>XrmQGetSearchList</function>.
+<indexterm significance="preferred"><primary>XrmQGetSearchList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqgetsearchlist'>
+<funcprototype>
+  <funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>
+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+  <paramdef>XrmNameList<parameter> names</parameter></paramdef>
+  <paramdef>XrmClassList<parameter> classes</parameter></paramdef>
+  <paramdef>XrmSearchList<parameter> list_return</parameter></paramdef>
+  <paramdef>int<parameter> list_length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the database that is to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>names</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a list of resource names.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>classes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a list of resource classes.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a search list for further use.
+The caller must allocate sufficient space for the list before calling 
+<function>XrmQGetSearchList</function>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list_length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of entries (not the byte size) allocated for list_return.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmQGetSearchList</function>
+function takes a list of names and classes
+and returns a list of database levels where a match might occur.
+The returned list is in best-to-worst order and
+uses the same algorithm as 
+<function>XrmGetResource</function>
+for determining precedence.
+If list_return was large enough for the search list,
+<function>XrmQGetSearchList</function>
+returns 
+<symbol>True</symbol>;
+otherwise, it returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The size of the search list that the caller must allocate is
+dependent upon the number of levels and wildcards in the resource specifiers 
+that are stored in the database.
+The worst case length is
+3<superscript><emphasis remap='I'>n</emphasis></superscript>,
+where <emphasis remap='I'>n</emphasis> is the number of name or class
+components in names or classes.
+</para>
+<para>
+<!-- .LP -->
+When using 
+<function>XrmQGetSearchList</function>
+followed by multiple probes for resources with a common name and class prefix,
+only the common prefix should be specified in the name and class list to 
+<function>XrmQGetSearchList</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To search resource database levels for a given resource, use
+<function>XrmQGetSearchResource</function>.
+<indexterm significance="preferred"><primary>XrmQGetSearchResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqgetsearchresource'>
+<funcprototype>
+  <funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>
+  <paramdef>XrmSearchList<parameter> list</parameter></paramdef>
+  <paramdef>XrmName<parameter> name</parameter></paramdef>
+  <paramdef>XrmClass<parameter> class</parameter></paramdef>
+  <paramdef>XrmRepresentation<parameter> *type_return</parameter></paramdef>
+  <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the search list returned by
+<function>XrmQGetSearchList</function>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource name.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource class.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>type_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns data representation type.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the value in the database.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmQGetSearchResource</function>
+function searches the specified database levels for the resource 
+that is fully identified by the specified name and class.
+The search stops with the first match.
+<function>XrmQGetSearchResource</function>
+returns 
+<symbol>True</symbol>
+if the resource was found;
+otherwise, it returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+A call to 
+<function>XrmQGetSearchList</function>
+with a name and class list containing all but the last component 
+of a resource name followed by a call to 
+<function>XrmQGetSearchResource</function>
+with the last component name and class returns the same database entry as 
+<function>XrmGetResource</function>
+and 
+<function>XrmQGetResource</function>
+with the fully qualified name and class.
+</para>
+</sect1>
+<sect1 id="Storing_into_a_Resource_Database">
+<title>Storing into a Resource Database</title>
+<!-- .XS -->
+<!-- (SN Storing into a Resource Database -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To store resources into the database, use
+<function>XrmPutResource</function>
+or
+<function>XrmQPutResource</function>.
+Both functions take a partial resource specification, a
+representation type, and a value.
+This value is copied into the specified database.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmPutResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmputresource'>
+<funcprototype>
+  <funcdef>void <function>XrmPutResource</function></funcdef>
+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+  <paramdef>char<parameter> *specifier</parameter></paramdef>
+  <paramdef>char<parameter> *type</parameter></paramdef>
+  <paramdef>XrmValue<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>specifier</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a complete or partial specification of the resource.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>type</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the type of the resource.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the value of the resource, which is specified as a string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutResource</function>
+is a convenience function that calls
+<function>XrmStringToBindingQuarkList</function>
+followed by:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
+</literallayout>
+If the specifier and type are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmQPutResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqputresource'>
+<funcprototype>
+  <funcdef>void <function>XrmQPutResource</function></funcdef>
+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+  <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
+  <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
+  <paramdef>XrmRepresentation<parameter> type</parameter></paramdef>
+  <paramdef>XrmValue<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bindings</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a list of bindings.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>quarks</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the complete or partial name or the class list of the resource.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>type</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the type of the resource.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the value of the resource, which is specified as a string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmQPutResource</function>
+creates a new database and returns a pointer to it.
+If a resource entry with the identical bindings and quarks already
+exists in the database, the previous type and value are replaced by the new
+specified type and value.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a resource that is specified as a string, use
+<function>XrmPutStringResource</function>.
+<indexterm significance="preferred"><primary>XrmPutStringResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmputstringresource'>
+<funcprototype>
+  <funcdef>void <function>XrmPutStringResource</function></funcdef>
+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+  <paramdef>char<parameter> *specifier</parameter></paramdef>
+  <paramdef>char<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>specifier</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a complete or partial specification of the resource.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the value of the resource, which is specified as a string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutStringResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutStringResource</function>
+adds a resource with the specified value to the specified database.
+<function>XrmPutStringResource</function>
+is a convenience function that first calls
+<function>XrmStringToBindingQuarkList</function>
+on the specifier and then calls
+<function>XrmQPutResource</function>,
+using a ``String'' representation type.
+If the specifier is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a string resource using quarks as a specification, use
+<function>XrmQPutStringResource</function>.
+<indexterm significance="preferred"><primary>XrmQPutStringResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqputstringresource'>
+<funcprototype>
+  <funcdef>void <function>XrmQPutStringResource</function></funcdef>
+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+  <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
+  <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
+  <paramdef>char<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bindings</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a list of bindings.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>quarks</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the complete or partial name or the class list of the resource.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the value of the resource, which is specified as a string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmQPutStringResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmQPutStringResource</function>
+is a convenience routine that constructs an
+<type>XrmValue</type>
+for the value string (by calling
+<function>strlen</function>
+to compute the size) and
+then calls
+<function>XrmQPutResource</function>,
+using a ``String'' representation type.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a single resource entry that is specified as a string that contains
+both a name and a value, use
+<function>XrmPutLineResource</function>.
+<indexterm significance="preferred"><primary>XrmPutLineResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmputlineresource'>
+<funcprototype>
+  <funcdef>void <function>XrmPutLineResource</function></funcdef>
+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+  <paramdef>char<parameter> *line</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>line</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource name and value pair as a single string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutLineResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutLineResource</function>
+adds a single resource entry to the specified database.
+The line should be in valid ResourceLine format (see section 15.1)
+terminated by a newline or null character;
+the database that results from using a string
+with incorrect syntax is implementation-dependent.
+The string is parsed in the locale of the database.
+If the
+<replaceable>ResourceName</replaceable>
+is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Note that comment lines are not stored.
+</para>
+</sect1>
+<sect1 id="Enumerating_Database_Entries">
+<title>Enumerating Database Entries</title>
+<!-- .XS -->
+<!-- (SN Enumerating Database Entries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To enumerate the entries of a database, use
+<function>XrmEnumerateDatabase</function>.
+<indexterm significance="preferred"><primary>XrmEnumerateDatabase</primary></indexterm>
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+#define       XrmEnumAllLevels       0
+#define       XrmEnumOneLevel        0
+</literallayout>
+
+<funcsynopsis id='xrmenumeratedatabase'>
+<funcprototype>
+  <funcdef>Bool <function>XrmEnumerateDatabase</function></funcdef>
+  <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+  <paramdef>XrmNameList<parameter> name_prefix</parameter></paramdef>
+  <paramdef>XrmClassList<parameter> class_prefix</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+  <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>name_prefix</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource name prefix.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class_prefix</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource class prefix.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of levels to enumerate.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>proc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure that is to be called for each matching entry.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the user-supplied argument that will be passed to the procedure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmEnumerateDatabase</function>
+function calls the specified procedure for each resource in the database
+that would match some completion of the given name/class resource prefix.
+The order in which resources are found is implementation-dependent.
+If mode is
+<symbol>XrmEnumOneLevel</symbol>,
+a resource must match the given name/class prefix with
+just a single name and class appended.  If mode is
+<symbol>XrmEnumAllLevels</symbol>,
+the resource must match the given name/class prefix with one or more names and
+classes appended.
+If the procedure returns
+<symbol>True</symbol>,
+the enumeration terminates and the function returns
+<symbol>True</symbol>.
+If the procedure always returns
+<symbol>False</symbol>,
+all matching resources are enumerated and the function returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The procedure is called with the following arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>database</emphasis>, <emphasis remap='I'>bindings</emphasis>, <emphasis remap='I'>quarks</emphasis>, <emphasis remap='I'>type</emphasis>, <emphasis remap='I'>value</emphasis>, <emphasis remap='I'>arg</emphasis>)
+     XrmDatabase *<emphasis remap='I'>database</emphasis>;
+     XrmBindingList <emphasis remap='I'>bindings</emphasis>;
+     XrmQuarkList <emphasis remap='I'>quarks</emphasis>;
+     XrmRepresentation *<emphasis remap='I'>type</emphasis>;
+     XrmValue *<emphasis remap='I'>value</emphasis>;
+     XPointer <emphasis remap='I'>arg</emphasis>;
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+The bindings and quarks lists are terminated by
+<symbol>NULLQUARK</symbol>.
+Note that pointers
+to the database and type are passed, but these values should not be modified.
+</para>
+<para>
+<!-- .LP -->
+The procedure must not modify the database.
+If Xlib has been initialized for threads, the procedure is called with
+the database locked and the result of a call by the procedure to any
+Xlib function using the same database is not defined.
+</para>
+</sect1>
+<sect1 id="Parsing_Command_Line_Options">
+<title>Parsing Command Line Options</title>
+<!-- .XS -->
+<!-- (SN Parsing Command Line Options  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XrmParseCommand</function>
+function can be used to parse the command line arguments to a program
+and modify a resource database with selected entries from the command line.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmOptionKind</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef enum {
+     XrmoptionNoArg,     /* Value is specified in XrmOptionDescRec.value */
+     XrmoptionIsArg,     /* Value is the option string itself */
+     XrmoptionStickyArg,     /* Value is characters immediately following option */
+     XrmoptionSepArg,     /* Value is next argument in argv */
+     XrmoptionResArg,     /* Resource and value in next argument in argv */
+     XrmoptionSkipArg,     /* Ignore this option and the next argument in argv */
+     XrmoptionSkipLine,     /* Ignore this option and the rest of argv */
+     XrmoptionSkipNArgs     /* Ignore this option and the next
+          \ \ \ XrmOptionDescRec.value arguments in argv */
+} XrmOptionKind;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Note that
+<constant>XrmoptionSkipArg</constant>
+is equivalent to 
+<constant>XrmoptionSkipNArgs</constant>
+with the
+<structname>XrmOptionDescRec</structname>.<structfield>value</structfield>
+field containing the value one.
+Note also that the value zero for
+<constant>XrmoptionSkipNArgs</constant>
+indicates that only the option itself is to be skipped.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmOptionDescRec</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+     char *option;     /* Option specification string in argv              */
+     char *specifier;     /* Binding and resource name (sans application name)    */
+     XrmOptionKind argKind;     /* Which style of option it is         */
+     XPointer value;     /* Value to provide if XrmoptionNoArg or 
+          \ \ \ XrmoptionSkipNArgs   */
+} XrmOptionDescRec, *XrmOptionDescList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To load a resource database from a C command line, use
+<function>XrmParseCommand</function>.
+<indexterm significance="preferred"><primary>XrmParseCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmparsecommand'>
+<funcprototype>
+  <funcdef>void <function>XrmParseCommand</function></funcdef>
+  <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+  <paramdef>XrmOptionDescList<parameter> table</parameter></paramdef>
+  <paramdef>int<parameter> table_count</parameter></paramdef>
+  <paramdef>char<parameter> *name</parameter></paramdef>
+  <paramdef>int<parameter> *argc_in_out</parameter></paramdef>
+  <paramdef>char<parameter> **argv_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>database</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>table</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the table of command line arguments to be parsed.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>table_count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of entries in the table.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the application name.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argc_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of arguments and returns the number of remaining arguments.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>argv_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the command line arguments
+and returns the remaining arguments.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmParseCommand</function>
+function parses an (argc, argv) pair according to the specified option table,
+loads recognized options into the specified database with type ``String,''
+and modifies the (argc, argv) pair to remove all recognized options.
+If database contains NULL,
+<function>XrmParseCommand</function>
+creates a new database and returns a pointer to it.
+Otherwise, entries are added to the database specified.
+If a database is created, it is created in the current locale.
+</para>
+<para>
+<!-- .LP -->
+The specified table is used to parse the command line.
+Recognized options in the table are removed from argv,
+and entries are added to the specified resource database
+in the order they occur in argv.
+The table entries contain information on the option string,
+the option name, the style of option, 
+and a value to provide if the option kind is 
+<constant>XrmoptionNoArg</constant>.
+The option names are compared byte-for-byte to arguments in argv,
+independent of any locale.
+The resource values given in the table are stored in the resource database
+without modification.
+All resource database entries are created
+using a ``String'' representation type.
+The argc argument specifies the number of arguments in argv
+and is set on return to the remaining number of arguments that were not parsed.
+The name argument should be the name of your application
+for use in building the database entry.
+The name argument is prefixed to the resourceName in the option table
+before storing a database entry.
+The name argument is treated as a single component, even if it
+has embedded periods.
+No separating (binding) character is inserted,
+so the table must contain either a period (.) or an asterisk (*)
+as the first character in each resourceName entry.
+To specify a more completely qualified resource name,
+the resourceName entry can contain multiple components.
+If the name argument and the resourceNames are not in the
+Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+The following provides a sample option table:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 1.25i 3.25i 4.75i -->
+<!-- .ta 1.25i 3.25i 4.75i -->
+static XrmOptionDescRec opTable[] = {
+{"-background",     "*background",                 XrmoptionSepArg,    (XPointer) NULL},
+{"-bd",             "*borderColor",                XrmoptionSepArg,    (XPointer) NULL},
+{"-bg",             "*background",                 XrmoptionSepArg,    (XPointer) NULL},
+{"-borderwidth",    "*TopLevelShell.borderWidth",  XrmoptionSepArg,    (XPointer) NULL},
+{"-bordercolor",    "*borderColor",                XrmoptionSepArg,    (XPointer) NULL},
+{"-bw",             "*TopLevelShell.borderWidth",  XrmoptionSepArg,    (XPointer) NULL},
+{"-display",        ".display",                    XrmoptionSepArg,    (XPointer) NULL},
+{"-fg",             "*foreground",                 XrmoptionSepArg,    (XPointer) NULL},
+{"-fn",             "*font",                       XrmoptionSepArg,    (XPointer) NULL},
+{"-font",           "*font",                       XrmoptionSepArg,    (XPointer) NULL},
+{"-foreground",     "*foreground",                 XrmoptionSepArg,    (XPointer) NULL},
+{"-geometry",       ".TopLevelShell.geometry",     XrmoptionSepArg,    (XPointer) NULL},
+{"-iconic",         ".TopLevelShell.iconic",       XrmoptionNoArg,     (XPointer) "on"},
+{"-name",           ".name",                       XrmoptionSepArg,    (XPointer) NULL},
+{"-reverse",        "*reverseVideo",               XrmoptionNoArg,     (XPointer) "on"},
+{"-rv",             "*reverseVideo",               XrmoptionNoArg,     (XPointer) "on"},
+{"-synchronous",    "*synchronous",                XrmoptionNoArg,     (XPointer) "on"},
+{"-title",          ".TopLevelShell.title",        XrmoptionSepArg,    (XPointer) NULL},
+{"-xrm",            NULL,                          XrmoptionResArg,    (XPointer) NULL},
+};
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+In this table, if the -background (or -bg) option is used to set
+background colors, the stored resource specifier matches all
+resources of attribute background.  
+If the -borderwidth option is used, 
+the stored resource specifier applies only to border width
+attributes of class TopLevelShell (that is, outer-most windows, including
+pop-up windows).  
+If the -title option is used to set a window name,
+only the topmost application windows receive the resource.
+</para>
+<para>
+<!-- .LP -->
+When parsing the command line,
+any unique unambiguous abbreviation for an option name in the table is 
+considered a match for the option.
+Note that uppercase and lowercase matter.
+<!-- .bp -->
+
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/CH16.xml b/libX11/specs/libX11/CH16.xml
index 9c7bf8c01..db42bb170 100644
--- a/libX11/specs/libX11/CH16.xml
+++ b/libX11/specs/libX11/CH16.xml
@@ -1,4160 +1,4160 @@
-<?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="application_utility_functions">

-<title>Application Utility Functions</title>

-<!-- .sp 2 -->

-<!-- .nr H1 16 -->

-<!-- .nr H2 0 -->

-<!-- .nr H3 0 -->

-<!-- .nr H4 0 -->

-<!-- .nr H5 0 -->

-<!-- .na -->

-<para>

-<!-- .LP -->

-<!-- .XS -->

-<!-- Chapter 16: Application Utility Functions  -->

-<!-- .XE -->

-Once you have initialized the X system,

-you can use the Xlib utility functions to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Use keyboard utility functions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Use Latin-1 keyboard event functions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Allocate permanent storage

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Parse the window geometry

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Manipulate regions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Use cut buffers

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Determine the appropriate visual type

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Manipulate images

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Manipulate bitmaps

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Use the context manager

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-As a group,

-the functions discussed in this chapter provide the functionality that 

-is frequently needed and that spans toolkits.

-Many of these functions do not generate actual protocol requests to the server.

-</para>

-<sect1 id="Using_Keyboard_Utility_Functions">

-<title>Using Keyboard Utility Functions</title>

-<!-- .XS -->

-<!-- (SN Using Keyboard Utility Functions  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-This section discusses mapping between KeyCodes and KeySyms,

-classifying KeySyms, and mapping between KeySyms and string names.

-The first three functions in this section operate on a cached copy of the

-server keyboard mapping.

-The first four KeySyms for each KeyCode

-are modified according to the rules given in section 12.7.

-To obtain the untransformed KeySyms defined for a key,

-use the functions described in section 12.7.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a KeySym for the KeyCode of an event, use

-<function>XLookupKeysym</function>.

-<indexterm significance="preferred"><primary>XLookupKeysym</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>KeySym <function>XLookupKeysym</function></funcdef>

-  <paramdef>XKeyEvent<parameter> *key_event</parameter></paramdef>

-  <paramdef>int<parameter> index</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>key_event</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the 

-<symbol>KeyPress</symbol>

-or

-<symbol>KeyRelease</symbol>

-event.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>index</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the index into the KeySyms list for the event's KeyCode.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLookupKeysym</function>

-function uses a given keyboard event and the index you specified to return

-the KeySym from the list that corresponds to the KeyCode member in the

-<type>XKeyPressedEvent</type>

-or

-<type>XKeyReleasedEvent</type>

-structure.

-If no KeySym is defined for the KeyCode of the event,

-<function>XLookupKeysym</function>

-returns

-<symbol>NoSymbol</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a KeySym for a specific KeyCode, use

-<function>XKeycodeToKeysym</function>.

-<indexterm significance="preferred"><primary>XKeycodeToKeysym</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>KeySym <function>XKeycodeToKeysym</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>KeyCode<parameter> keycode</parameter></paramdef>

-  <paramdef>int<parameter> index</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keycode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeyCode.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>index</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the element of KeyCode vector.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XKeycodeToKeysym</function>

-function uses internal Xlib tables

-and returns the KeySym defined for the specified KeyCode and

-the element of the KeyCode vector.

-If no symbol is defined,

-<function>XKeycodeToKeysym</function>

-returns

-<symbol>NoSymbol</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a KeyCode for a key having a specific KeySym, use

-<function>XKeysymToKeycode</function>.

-<indexterm significance="preferred"><primary>XKeysymToKeycode</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>KeyCode <function>XKeysymToKeycode</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>KeySym<parameter> keysym</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be searched for.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If the specified KeySym is not defined for any KeyCode,

-<function>XKeysymToKeycode</function>

-returns zero.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-The mapping between KeyCodes and KeySyms is cached internal to Xlib.

-When this information is changed at the server, an Xlib function must

-be called to refresh the cache.

-To refresh the stored modifier and keymap information, use

-<function>XRefreshKeyboardMapping</function>.

-<indexterm significance="preferred"><primary>XRefreshKeyboardMapping</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRefreshKeyboardMapping</function></funcdef>

-  <paramdef>XMappingEvent<parameter> *event_map</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_map</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the mapping event that is to be used.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRefreshKeyboardMapping</function>

-function refreshes the stored modifier and keymap information.

-You usually call this function when a

-<symbol>MappingNotify</symbol>

-event with a request member of

-<symbol>MappingKeyboard</symbol>

-or

-<symbol>MappingModifier</symbol>

-occurs.

-The result is to update Xlib's knowledge of the keyboard.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the uppercase and lowercase forms of a KeySym, use

-<function>XConvertCase</function>.

-<indexterm significance="preferred"><primary>XConvertCase</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void <function>XConvertCase</function></funcdef>

-  <paramdef>KeySym<parameter> keysym</parameter></paramdef>

-  <paramdef>KeySym<parameter> *lower_return</parameter></paramdef>

-  <paramdef>KeySym<parameter> *upper_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<!-- .ds Fn converted -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be (Fn.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>lower_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the lowercase form of keysym, or keysym.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>upper_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the uppercase form of keysym, or keysym.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XConvertCase</function>

-function returns the uppercase and lowercase forms of the specified Keysym,

-if the KeySym is subject to case conversion;

-otherwise, the specified KeySym is returned to both lower_return and

-upper_return.

-Support for conversion of other than Latin and Cyrillic KeySyms is

-implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-KeySyms have string names as well as numeric codes.

-To convert the name of the KeySym to the KeySym code, use

-<function>XStringToKeysym</function>.

-<indexterm significance="preferred"><primary>XStringToKeysym</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>KeySym <function>XStringToKeysym</function></funcdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the name of the KeySym that is to be converted.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Standard KeySym names are obtained from

-<filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename>

-<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename></secondary></indexterm>

-by removing the XK_ prefix from each name.

-KeySyms that are not part of the Xlib standard also may be obtained

-with this function.

-The set of KeySyms that are available in this manner 

-and the mechanisms by which Xlib obtains them is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-If the KeySym name is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-If the specified string does not match a valid KeySym,

-<function>XStringToKeysym</function>

-returns

-<symbol>NoSymbol</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To convert a KeySym code to the name of the KeySym, use

-<function>XKeysymToString</function>.

-<indexterm significance="preferred"><primary>XKeysymToString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XKeysymToString</function></funcdef>

-  <paramdef>KeySym<parameter> keysym</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<!-- .ds Fn converted -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be (Fn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The returned string is in a static area and must not be modified.

-The returned string is in the Host Portable Character Encoding.

-If the specified KeySym is not defined,

-<function>XKeysymToString</function>

-returns a NULL.

-</para>

-<sect2 id="KeySym_Classification_Macros">

-<title>KeySym Classification Macros</title>

-<!-- .XS -->

-<!-- (SN KeySym Classification Macros -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-You may want to test if a KeySym is, for example, 

-on the keypad or on one of the function keys.

-You can use KeySym macros to perform the following tests.

-</para>

-<para>IsCursorKey(<emphasis remap='I'>keysym</emphasis>)</para>

-<!-- .FN -->

-<!-- .ds Fn tested -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be tested.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>IsCursorKey</primary></indexterm>

-Returns

-<symbol>True</symbol>

-if the specified KeySym is a cursor key.

-</para>

-<!-- .LP -->

-<!-- .sp -->

-<!-- .sM -->

-<para>IsFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>

-<!-- .FN -->

-<!-- .ds Fn tested -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be tested.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>IsFunctionKey</primary></indexterm>

-Returns 

-<symbol>True</symbol>

-if the specified KeySym is a function key.

-</para>

-<!-- .LP -->

-<!-- .sp -->

-<!-- .sM -->

-<para>IsKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>

-<!-- .FN -->

-<!-- .ds Fn tested -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be (Fn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>IsKeypadKey</primary></indexterm>

-Returns

-<symbol>True</symbol>

-if the specified KeySym is a standard keypad key.

-</para>

-<!-- .LP -->

-<!-- .sp -->

-<!-- .sM -->

-<para>IsPrivateKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be (Fn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>IsPrivateKeypadKey</primary></indexterm>

-Returns

-<symbol>True</symbol>

-if the specified KeySym is a vendor-private keypad key.

-</para>

-

-<!-- .LP -->

-<!-- .sp -->

-<!-- .sM -->

-<para>IsMiscFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>

-<!-- .FN -->

-<!-- .ds Fn tested -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be (Fn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>IsMiscFunctionKey</primary></indexterm>

-Returns 

-<symbol>True</symbol>

-if the specified KeySym is a miscellaneous function key.

-</para>

-<!-- .LP -->

-<!-- .sp -->

-<!-- .sM -->

-<para>IsModifierKey(<emphasis remap='I'>keysym</emphasis>)</para>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be tested.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>IsModifierKey</primary></indexterm>

-Returns 

-<symbol>True</symbol>

-if the specified KeySym is a modifier key.

-</para>

-

-<para>IsPFKey(<emphasis remap='I'>keysym</emphasis>)</para>

-

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be tested.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<indexterm significance="preferred"><primary>IsPFKey</primary></indexterm>

-Returns 

-<symbol>True</symbol>

-if the specified KeySym is a PF key.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Using_Latin_Keyboard_Event_Functions">

-<title>Using Latin-1 Keyboard Event Functions</title>

-<!-- .XS -->

-<!-- (SN Using Latin-1 Keyboard Event Functions  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Chapter 13 describes internationalized text input facilities,

-but sometimes it is expedient to write an application that

-only deals with Latin-1 characters and ASCII controls,

-so Xlib provides a simple function for that purpose.

-<function>XLookupString</function>

-handles the standard modifier semantics described in section 12.7.

-This function does not use any of the input method facilities

-described in chapter 13 and does not depend on the current locale.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To map a key event to an ISO Latin-1 string, use

-<function>XLookupString</function>.

-<indexterm significance="preferred"><primary>XLookupString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XLookupString</function></funcdef>

-  <paramdef>XKeyEvent<parameter> *event_struct</parameter></paramdef>

-  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

-  <paramdef>int<parameter> bytes_buffer</parameter></paramdef>

-  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>

-  <paramdef>XComposeStatus<parameter> *status_in_out</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_struct</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the key event structure to be used.

-You can pass

-<type>XKeyPressedEvent</type>

-or

-<type>XKeyReleasedEvent</type>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buffer_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the translated characters.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bytes_buffer</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the length of the buffer.

-No more than bytes_buffer of translation are returned.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the KeySym computed from the event if this argument is not NULL.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>status_in_out</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies or returns the 

-<structname>XComposeStatus</structname>

-structure or NULL.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XLookupString</function>

-function translates a key event to a KeySym and a string.

-The KeySym is obtained by using the standard interpretation of the

-<symbol>Shift</symbol>,

-<symbol>Lock</symbol>,

-group, and numlock modifiers as defined in the X Protocol specification.

-If the KeySym has been rebound (see

-<function>XRebindKeysym</function>),

-the bound string will be stored in the buffer.

-Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character

-or (if the Control modifier is on) to an ASCII control character,

-and that character is stored in the buffer.

-<function>XLookupString</function>

-returns the number of characters that are stored in the buffer.

-</para>

-<para>

-<!-- .LP -->

-If present (non-NULL),

-the

-<structname>XComposeStatus</structname>

-structure records the state,

-which is private to Xlib,

-that needs preservation across calls to

-<function>XLookupString</function>

-to implement compose processing.

-The creation of

-<structname>XComposeStatus</structname>

-structures is implementation-dependent;

-a portable program must pass NULL for this argument.

-</para>

-<para>

-<!-- .LP -->

-<function>XLookupString</function>

-depends on the cached keyboard information mentioned in the

-previous section, so it is necessary to use

-<function>XRefreshKeyboardMapping</function>

-to keep this information up-to-date.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To rebind the meaning of a KeySym for

-<function>XLookupString</function>,

-use

-<function>XRebindKeysym</function>.

-<indexterm significance="preferred"><primary>XRebindKeysym</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRebindKeysym</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>KeySym<parameter> keysym</parameter></paramdef>

-  <paramdef>KeySym<parameter> list[&hairsp;]</parameter></paramdef>

-  <paramdef>int<parameter> mod_count</parameter></paramdef>

-  <paramdef>unsignedchar<parameter> *string</parameter></paramdef>

-  <paramdef>int<parameter> num_bytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Fn rebound -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>keysym</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySym that is to be (Fn.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>list</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the KeySyms to be used as modifiers.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mod_count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of modifiers in the modifier list.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the string that is copied and will be returned by 

-<function>XLookupString</function>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_bytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes in the string argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRebindKeysym</function>

-function can be used to rebind the meaning of a KeySym for the client.

-It does not redefine any key in the X server but merely

-provides an easy way for long strings to be attached to keys.

-<function>XLookupString</function>

-returns this string when the appropriate set of

-modifier keys are pressed and when the KeySym would have been used for

-the translation.

-No text conversions are performed;

-the client is responsible for supplying appropriately encoded strings.

-Note that you can rebind a KeySym that may not exist.

-</para>

-</sect1>

-<sect1 id="Allocating_Permanent_Storage">

-<title>Allocating Permanent Storage</title>

-<!-- .XS -->

-<!-- (SN Allocating Permanent Storage -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To allocate some memory you will never give back, use

-<function>Xpermalloc</function>.

-<indexterm significance="preferred"><primary>Xpermalloc</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>Xpermalloc</function></funcdef>

-  <paramdef>unsignedint<parameter> size</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>Xpermalloc</function>

-function allocates storage that can never be freed for the life of the

-program.  The memory is allocated with alignment for the C type double.

-This function may provide some performance and space savings over

-the standard operating system memory allocator.

-</para>

-</sect1>

-<sect1 id="Parsing_the_Window_Geometry">

-<title>Parsing the Window Geometry</title>

-<!-- .XS -->

-<!-- (SN Parsing the Window Geometry  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To parse standard window geometry strings, use

-<function>XParseGeometry</function>.

-<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>

-<indexterm significance="preferred"><primary>XParseGeometry</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XParseGeometry</function></funcdef>

-  <paramdef>char<parameter> *parsestring</parameter></paramdef>

-  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>

-  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>parsestring</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the string you want to parse.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the x and y offsets.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the width and height determined.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-By convention,

-X applications use a standard string to indicate window size and placement.

-<function>XParseGeometry</function>

-makes it easier to conform to this standard because it allows you

-to parse the standard window geometry.

-Specifically, this function lets you parse strings of the form:

-</para>

-<para>

-<!-- .LP -->

-<!-- .\" Start marker code here -->

-<literallayout class="monospaced">

-[=][&lt;<emphasis remap='I'>width</emphasis>&gt;{xX}&lt;<emphasis remap='I'>height</emphasis>&gt;][{+-}&lt;<emphasis remap='I'>xoffset</emphasis>&gt;{+-}&lt;<emphasis remap='I'>yoffset</emphasis>&gt;] 

-</literallayout>

-<!-- .\" End marker code here -->

-</para>

-<para>

-<!-- .LP -->

-The fields map into the arguments associated with this function.

-(Items enclosed in &lt;&hairsp;&gt; are integers, items in [&hairsp;] are optional, and

-items enclosed in {&hairsp;} indicate ``choose one of.''

-Note that the brackets should not appear in the actual string.)

-If the string is not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-</para>

-<para>

-<!-- .LP -->

-The

-<function>XParseGeometry</function>

-function returns a bitmask that indicates which of the four values (width,

-height, xoffset, and yoffset) were actually found in the string 

-and whether the x and y values are negative. 

-By convention, &minus;0 is not equal to +0, because the user needs to

-be able to say ``position the window relative to the right or bottom edge.''

-For each value found, the corresponding argument is updated.

-For each value not found, the argument is left unchanged.

-The bits are represented by

-<symbol>XValue</symbol>,

-<symbol>YValue</symbol>,

-<symbol>WidthValue</symbol>,

-<symbol>HeightValue</symbol>,

-<symbol>XNegative</symbol>,

-or

-<symbol>YNegative</symbol>

-and are defined in 

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-They will be set whenever one of the values is defined 

-or one of the signs is set.

-</para>

-<para>

-<!-- .LP -->

-If the function returns either the 

-<symbol>XValue</symbol>

-or 

-<symbol>YValue</symbol>

-flag,

-you should place the window at the requested position.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To construct a window's geometry information, use

-<function>XWMGeometry</function>.

-<indexterm significance="preferred"><primary>XWMGeometry</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XWMGeometry</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> screen</parameter></paramdef>

-  <paramdef>char<parameter> *user_geom</parameter></paramdef>

-  <paramdef>char<parameter> *def_geom</parameter></paramdef>

-  <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>

-  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>

-  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>

-  <paramdef>int<parameter> *width_return</parameter></paramdef>

-  <paramdef>int<parameter> *height_return</parameter></paramdef>

-  <paramdef>int<parameter> *gravity_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>user_geom</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the user-specified geometry or NULL.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>def_geom</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the application's default geometry or NULL.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bwidth</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the border width.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>hints</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size hints for the window in its normal state.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the x and y offsets.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the width and height determined.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gravity_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the window gravity.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The 

-<function>XWMGeometry</function>

-function combines any geometry information (given in the format used by 

-<function>XParseGeometry</function>)

-specified by the user and by the calling program with size hints 

-(usually the ones to be stored in <property>WM_NORMAL_HINTS</property>) and returns the position, 

-size, and gravity

-(<symbol>NorthWestGravity</symbol>,

-<symbol>NorthEastGravity</symbol>,

-<symbol>SouthEastGravity</symbol>,

-or

-<symbol>SouthWestGravity</symbol>)

-that describe the window.

-If the base size is not set in the 

-<structname>XSizeHints</structname>

-structure, 

-the minimum size is used if set.

-Otherwise, a base size of zero is assumed.

-If no minimum size is set in the hints structure, 

-the base size is used.

-A mask (in the form returned by 

-<function>XParseGeometry</function>)

-that describes which values came from the user specification 

-and whether or not the position coordinates are relative

-to the right and bottom edges is returned.

-Note that these coordinates will have already been accounted for 

-in the x_return and y_return values.

-</para>

-<para>

-<!-- .LP -->

-Note that invalid geometry specifications can cause a width or height 

-of zero to be returned.

-The caller may pass the address of the hints win_gravity field 

-as gravity_return to update the hints directly.

-</para>

-</sect1>

-

-<sect1 id="Manipulating_Regions">

-<title>Manipulating Regions</title>

-<!-- .XS -->

-<!-- (SN Manipulating Regions  -->

-<!-- .XE -->

-<para>

-Regions are arbitrary sets of pixel locations.

-Xlib provides functions for manipulating regions.

-The opaque type 

-<structname>Region</structname>

-is defined in 

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-Xlib provides functions that you can use to manipulate regions.

-This section discusses how to:

-</para>

-

-<itemizedlist>

-  <listitem>

-    <para>

-Create, copy, or destroy regions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Move or shrink regions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Compute with regions

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Determine if regions are empty or equal

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Locate a point or rectangle in a region

-    </para>

-  </listitem>

-</itemizedlist>

-

-<sect2 id="Creating_Copying_or_Destroying_Regions">

-<title>Creating, Copying, or Destroying Regions</title>

-<!-- .XS -->

-<!-- (SN Creating, Copying, or Destroying Regions  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To create a new empty region, use

-<function>XCreateRegion</function>.

-</para>

-<para>Region XCreateRegion()</para>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To generate a region from a polygon, use

-<function>XPolygonRegion</function>.

-</para>

-<indexterm significance="preferred"><primary>XPolygonRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Region <function>XPolygonRegion</function></funcdef>

-  <paramdef>XPoint<parameter> points[]</parameter></paramdef>

-  <paramdef>int<parameter> n</parameter></paramdef>

-  <paramdef>int<parameter> fill_rule</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>points</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies an array of points.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>n</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of points in the polygon. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>fill_rule</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the fill-rule you want to set for the specified GC.

-You can pass 

-<symbol>EvenOddRule</symbol>

-or

-<symbol>WindingRule</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XPolygonRegion</function>

-function returns a region for the polygon defined by the points array.

-For an explanation of fill_rule,

-see

-<function>XCreateGC</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the clip-mask of a GC to a region, use

-<function>XSetRegion</function>.

-<indexterm significance="preferred"><primary>XSetRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetRegion</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>GC<parameter> gc</parameter></paramdef>

-  <paramdef>Region<parameter> r</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>gc</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the GC.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the region.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetRegion</function>

-function sets the clip-mask in the GC to the specified region.

-The region is specified relative to the drawable's origin.

-The resulting GC clip origin is implementation-dependent.

-Once it is set in the GC,

-the region can be destroyed.

-</para>

-<para>

-<!-- .LP  -->

-<!-- .sp -->

-To deallocate the storage associated with a specified region, use

-<function>XDestroyRegion</function>.

-<indexterm significance="preferred"><primary>XDestroyRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDestroyRegion</function></funcdef>

-  <paramdef>Region<parameter> r</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the region.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-</sect2>

-<sect2 id="Moving_or_Shrinking_Regions">

-<title>Moving or Shrinking Regions</title>

-<!-- .XS -->

-<!-- (SN Moving or Shrinking Regions  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To move a region by a specified amount, use 

-<function>XOffsetRegion</function>.

-<indexterm significance="preferred"><primary>XOffsetRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XOffsetRegion</function></funcdef>

-  <paramdef>Region<parameter> r</parameter></paramdef>

-  <paramdef>intdx,<parameter> dy</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the region.

-<!-- .ds Dy move -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dx</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dy</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates,

-which define the amount you want to (Dy the specified region.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-<!-- .sp -->

-To reduce a region by a specified amount, use

-<function>XShrinkRegion</function>.

-<indexterm significance="preferred"><primary>XShrinkRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XShrinkRegion</function></funcdef>

-  <paramdef>Region<parameter> r</parameter></paramdef>

-  <paramdef>intdx,<parameter> dy</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the region.

-<!-- .ds Dy shrink -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dx</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dy</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates,

-which define the amount you want to (Dy the specified region.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Positive values shrink the size of the region, 

-and negative values expand the region.

-</para>

-</sect2>

-<sect2 id="Computing_with_Regions">

-<title>Computing with Regions</title>

-<!-- .XS -->

-<!-- (SN Computing with Regions  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To generate the smallest rectangle enclosing a region, use

-<function>XClipBox</function>.

-<indexterm significance="preferred"><primary>XClipBox</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XClipBox</function></funcdef>

-  <paramdef>Region<parameter> r</parameter></paramdef>

-  <paramdef>XRectangle<parameter> *rect_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the region.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rect_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the smallest enclosing rectangle.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XClipBox</function>

-function returns the smallest rectangle enclosing the specified region.

-<!-- .sp -->

-</para>

-<para>

-<!-- .LP -->

-To compute the intersection of two regions, use

-<function>XIntersectRegion</function>.

-<indexterm significance="preferred"><primary>XIntersectRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XIntersectRegion</function></funcdef>

-  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>sra</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>srb</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the two regions with which you want to perform the computation.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dr_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the result of the computation.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To compute the union of two regions, use

-<function>XUnionRegion</function>.

-<indexterm significance="preferred"><primary>XUnionRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUnionRegion</function></funcdef>

-  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>sra</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>srb</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the two regions with which you want to perform the computation.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dr_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the result of the computation.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<!-- .sp -->

-To create a union of a source region and a rectangle, use

-<function>XUnionRectWithRegion</function>.

-<indexterm significance="preferred"><primary>XUnionRectWithRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XUnionRectWithRegion</function></funcdef>

-  <paramdef>XRectangle<parameter> *rectangle</parameter></paramdef>

-  <paramdef>Region<parameter> src_region</parameter></paramdef>

-  <paramdef>Region<parameter> dest_region_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rectangle</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the rectangle.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_region</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the source region to be used.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_region_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the destination region.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XUnionRectWithRegion</function>

-function updates the destination region from a union of the specified rectangle

-and the specified source region.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To subtract two regions, use

-<function>XSubtractRegion</function>.

-<indexterm significance="preferred"><primary>XSubtractRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSubtractRegion</function></funcdef>

-  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>sra</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>srb</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the two regions with which you want to perform the computation.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dr_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the result of the computation.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSubtractRegion</function>

-function subtracts srb from sra and stores the results in dr_return.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To calculate the difference between the union and intersection 

-of two regions, use

-<function>XXorRegion</function>.

-<indexterm significance="preferred"><primary>XXorRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XXorRegion</function></funcdef>

-  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>sra</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>srb</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the two regions with which you want to perform the computation.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dr_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the result of the computation.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-</para>

-</sect2>

-<sect2 id="Determining_if_Regions_Are_Empty_or_Equal">

-<title>Determining if Regions Are Empty or Equal</title>

-<!-- .XS -->

-<!-- (SN Determining if Regions Are Empty or Equal  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To determine if the specified region is empty, use

-<function>XEmptyRegion</function>.

-<indexterm significance="preferred"><primary>XEmptyRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XEmptyRegion</function></funcdef>

-  <paramdef>Region<parameter> r</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the region.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XEmptyRegion</function>

-function returns

-<symbol>True</symbol>

-if the region is empty.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To determine if two regions have the same offset, size, and shape, use

-<function>XEqualRegion</function>.

-<indexterm significance="preferred"><primary>XEqualRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XEqualRegion</function></funcdef>

-  <paramdef>Regionr1,<parameter> r2</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r1</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r2</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the two regions.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XEqualRegion</function>

-function returns

-<symbol>True</symbol>

-if the two regions have the same offset, size, and shape.

-</para>

-</sect2>

-<sect2 id="Locating_a_Point_or_a_Rectangle_in_a_Region">

-<title>Locating a Point or a Rectangle in a Region</title>

-<!-- .XS -->

-<!-- (SN Locating a Point or a Rectangle in a Region  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To determine if a specified point resides in a specified region, use

-<function>XPointInRegion</function>.

-<indexterm significance="preferred"><primary>XPointInRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XPointInRegion</function></funcdef>

-  <paramdef>Region<parameter> r</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the region.

-<!-- .ds Xy , which define the point -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPointInRegion</function>

-function returns 

-<symbol>True</symbol>

-if the point (x, y) is contained in the region r.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To determine if a specified rectangle is inside a region, use

-<function>XRectInRegion</function>.

-<indexterm significance="preferred"><primary>XRectInRegion</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XRectInRegion</function></funcdef>

-  <paramdef>Region<parameter> r</parameter></paramdef>

-  <paramdef>intx,<parameter> y</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>r</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the region.

-<!-- .ds Xy , which define the coordinates of the upper-left corner of the rectangle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates(Xy.

-<!-- .ds Wh , which define the rectangle -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height(Wh.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XRectInRegion</function>

-function returns

-<symbol>RectangleIn</symbol>

-if the rectangle is entirely in the specified region,

-<symbol>RectangleOut</symbol>

-if the rectangle is entirely out of the specified region,

-and

-<symbol>RectanglePart</symbol>

-if the rectangle is partially in the specified region.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Using_Cut_Buffers">

-<title>Using Cut Buffers</title>

-<!-- .XS -->

-<!-- (SN Using Cut Buffers  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Cut Buffers</primary></indexterm>

-Xlib provides functions to manipulate cut buffers,

-a very simple form of cut-and-paste inter-client communication.

-Selections are a much more powerful and useful mechanism for

-interchanging data between clients (see section 4.5)

-and generally should be used instead of cut buffers.

-</para>

-<para>

-<!-- .LP -->

-Cut buffers are implemented as properties on the first root window

-of the display.

-The buffers can only contain text, in the STRING encoding.

-The text encoding is not changed by Xlib when fetching or storing.

-Eight buffers are provided

-and can be accessed as a ring or as explicit buffers (numbered 0 through 7).

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To store data in cut buffer 0, use 

-<function>XStoreBytes</function>.

-<indexterm significance="preferred"><primary>XStoreBytes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XStoreBytes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *bytes</parameter></paramdef>

-  <paramdef>int<parameter> nbytes</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN  -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the bytes, which are not necessarily ASCII or null-terminated.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes to be stored.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The data can have embedded null characters

-and need not be null-terminated.

-The cut buffer's contents can be retrieved later by

-any client calling

-<function>XFetchBytes</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XStoreBytes</function>

-can generate a

-<errorname>BadAlloc</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To store data in a specified cut buffer, use

-<function>XStoreBuffer</function>.

-<indexterm significance="preferred"><primary>XStoreBuffer</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XStoreBuffer</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *bytes</parameter></paramdef>

-  <paramdef>int<parameter> nbytes</parameter></paramdef>

-  <paramdef>int<parameter> buffer</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the bytes, which are not necessarily ASCII or null-terminated.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes to be stored.

-<!-- .ds Fn in which you want to store the bytes -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buffer</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the buffer (Fn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If an invalid buffer is specified, the call has no effect.

-The data can have embedded null characters

-and need not be null-terminated.

-</para>

-<para>

-<!-- .LP -->

-<function>XStoreBuffer</function>

-can generate a

-<errorname>BadAlloc</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return data from cut buffer 0, use 

-<function>XFetchBytes</function>.

-<indexterm significance="preferred"><primary>XFetchBytes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XFetchBytes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> *nbytes_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of bytes in the buffer.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFetchBytes</function>

-function

-returns the number of bytes in the nbytes_return argument,

-if the buffer contains data.

-Otherwise, the function

-returns NULL and sets nbytes to 0.

-The appropriate amount of storage is allocated and the pointer returned.

-The client must free this storage when finished with it by calling

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return data from a specified cut buffer, use 

-<function>XFetchBuffer</function>.

-<indexterm significance="preferred"><primary>XFetchBuffer</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XFetchBuffer</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> *nbytes_return</parameter></paramdef>

-  <paramdef>int<parameter> buffer</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nbytes_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of bytes in the buffer.

-<!-- .ds Fn from which you want the stored data returned -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buffer</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the buffer (Fn.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFetchBuffer</function>

-function returns zero to the nbytes_return argument 

-if there is no data in the buffer or if an invalid

-buffer is specified.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To rotate the cut buffers, use 

-<function>XRotateBuffers</function>.

-<indexterm significance="preferred"><primary>XRotateBuffers</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRotateBuffers</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> rotate</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rotate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies how much to rotate the cut buffers.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XRotateBuffers</function>

-function rotates the cut

-buffers, such that buffer 0 becomes buffer n, 

-buffer 1 becomes n + 1 mod 8, and so on.

-This cut buffer numbering is global to the display.

-Note that

-<function>XRotateBuffers</function>

-generates

-<errorname>BadMatch</errorname>

-errors if any of the eight buffers have not been created.

-</para>

-</sect1>

-<sect1 id="Determining_the_Appropriate_Visual_Type">

-<title>Determining the Appropriate Visual Type</title>

-<!-- .XS -->

-<!-- (SN Determining the Appropriate Visual Type -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A single display can support multiple screens.

-Each screen can have several different visual types supported 

-at different depths.

-You can use the functions described in this section to determine

-which visual to use for your application.

-</para>

-<para>

-<!-- .LP -->

-The functions in this section use the visual information masks and the

-<structname>XVisualInfo</structname>

-structure,

-which is defined in

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-and contains:

-<!-- .sM -->

-</para>

-<!-- .LP -->

-<literallayout class="monospaced">

-

-/* Visual information mask bits */

-

-

-#define   VisualNoMask                 0x0

-#define   VisualIDMask                 0x1

-#define   VisualScreenMask             0x2

-#define   VisualDepthMask              0x4

-#define   VisualClassMask              0x8

-#define   VisualRedMaskMask            0x10

-#define   VisualGreenMaskMask          0x20

-#define   VisualBlueMaskMask           0x40

-#define   VisualColormapSizeMask       0x80

-#define   VisualBitsPerRGBMask         0x100

-#define   VisualAllMask                0x1FF

-

-</literallayout>

-

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-/* Values */

-

-typedef struct {

-     Visual *visual;

-     VisualID visualid;

-     int screen;

-     unsigned int depth;

-     int class;

-     unsigned long red_mask;

-     unsigned long green_mask;

-     unsigned long blue_mask;

-     int colormap_size;

-     int bits_per_rgb;

-} XVisualInfo;

-</literallayout>

-

-<para>

-<!-- .LP -->

-<!-- .eM -->

-To obtain a list of visual information structures that match a specified

-template, use

-<function>XGetVisualInfo</function>.

-<indexterm significance="preferred"><primary>XGetVisualInfo</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XVisualInfo *<function>XGetVisualInfo</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>long<parameter> vinfo_mask</parameter></paramdef>

-  <paramdef>XVisualInfo<parameter> *vinfo_template</parameter></paramdef>

-  <paramdef>int<parameter> *nitems_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>vinfo_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the visual mask value.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>vinfo_template</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the visual attributes that are to be used in matching the visual

-structures.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nitems_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of matching visual structures.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetVisualInfo</function>

-function returns a list of visual structures that have attributes 

-equal to the attributes specified by vinfo_template.

-If no visual structures match the template using the specified vinfo_mask,

-<function>XGetVisualInfo</function>

-returns a NULL.

-To free the data returned by this function, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the visual information that matches the specified depth and

-class of the screen, use

-<function>XMatchVisualInfo</function>.

-<indexterm significance="preferred"><primary>XMatchVisualInfo</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XMatchVisualInfo</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> screen</parameter></paramdef>

-  <paramdef>int<parameter> depth</parameter></paramdef>

-  <paramdef>int<parameter> class</parameter></paramdef>

-  <paramdef>XVisualInfo<parameter> *vinfo_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>screen</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>depth</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the depth of the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>class</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the class of the screen.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>vinfo_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched visual information.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMatchVisualInfo</function>

-function returns the visual information for a visual that matches the specified

-depth and class for a screen.

-Because multiple visuals that match the specified depth and class can exist,

-the exact visual chosen is undefined.

-If a visual is found,

-<function>XMatchVisualInfo</function>

-returns nonzero and the information on the visual to vinfo_return.

-Otherwise, when a visual is not found,

-<function>XMatchVisualInfo</function>

-returns zero.

-</para>

-</sect1>

-<sect1 id="Manipulating_Images">

-<title>Manipulating Images</title>

-<!-- .XS -->

-<!-- (SN Manipulating Images  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides several functions that perform basic operations on images.

-All operations on images are defined using an 

-<structname>XImage</structname>

-structure, 

-as defined in

-<filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>

-Because the number of different types of image formats can be very large,

-this hides details of image storage properly from applications.

-</para>

-<para>

-<!-- .LP -->

-This section describes the functions for generic operations on images.

-Manufacturers can provide very fast implementations of these for the

-formats frequently encountered on their hardware.

-These functions are neither sufficient nor desirable to use for general image

-processing.

-Rather, they are here to provide minimal functions on screen format

-images.

-The basic operations for getting and putting images are

-<function>XGetImage</function>

-and 

-<function>XPutImage</function>.

-</para>

-<para>

-<!-- .LP -->

-Note that no functions have been defined, as yet, to read and write images 

-to and from disk files.

-</para>

-<para>

-<!-- .LP -->

-The

-<structname>XImage</structname>

-structure describes an image as it exists in the client's memory.  

-The user can request that some of the members such as height, width, 

-and xoffset be changed when the image is sent to the server.

-Note that bytes_per_line in concert with offset can be used to

-extract a subset of the image.

-Other members (for example, byte order, bitmap_unit, and so forth)

-are characteristics of both the image and the server.  

-If these members

-differ between the image and the server, 

-<function>XPutImage</function>

-makes the appropriate conversions.

-The first byte of the first line of

-plane n must be located at the address (data + (n * height * bytes_per_line)).

-For a description of the 

-<structname>XImage</structname>

-structure,

-see section 8.7.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To allocate an 

-<structname>XImage</structname>

-structure and initialize it with image format values from a display, use

-<function>XCreateImage</function>.

-<indexterm significance="preferred"><primary>XCreateImage</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XImage *<function>XCreateImage</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Visual<parameter> *visual</parameter></paramdef>

-  <paramdef>unsignedint<parameter> depth</parameter></paramdef>

-  <paramdef>int<parameter> format</parameter></paramdef>

-  <paramdef>int<parameter> offset</parameter></paramdef>

-  <paramdef>char<parameter> *data</parameter></paramdef>

-  <paramdef>unsignedint<parameter> width</parameter></paramdef>

-  <paramdef>unsignedint<parameter> height</parameter></paramdef>

-  <paramdef>int<parameter> bitmap_pad</parameter></paramdef>

-  <paramdef>int<parameter> bytes_per_line</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>visual</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>Visual</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>depth</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the depth of the image.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the format for the image.

-You can pass

-<symbol>XYBitmap</symbol>,

-<symbol>XYPixmap</symbol>,

-or 

-<symbol>ZPixmap</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>offset</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of pixels to ignore at the beginning of the scanline.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the image data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the width of the image, in pixels.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the height of the image, in pixels.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bitmap_pad</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the quantum of a scanline (8, 16, or 32).

-In other words, the start of one scanline is separated in client memory from 

-the start of the next scanline by an integer multiple of this many bits.  

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bytes_per_line</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of bytes in the client image between

-the start of one scanline and the start of the next.  

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateImage</function>

-function allocates the memory needed for an

-<structname>XImage</structname>

-structure for the

-specified display but does not allocate space for the image itself.

-Rather, it initializes the structure byte-order, bit-order, and bitmap-unit

-values from the display and returns a pointer to the 

-<structname>XImage</structname>

-structure.

-The red, green, and blue mask values are defined for Z format images only

-and are derived from the 

-<structname>Visual</structname>

-structure passed in.

-Other values also are passed in.

-The offset permits the rapid displaying of the image without requiring each 

-scanline to be shifted into position.

-If you pass a zero value in bytes_per_line,

-Xlib assumes that the scanlines are contiguous

-in memory and calculates the value of bytes_per_line itself.

-</para>

-<para>

-<!-- .LP -->

-Note that when the image is created using

-<function>XCreateImage</function>,

-<function>XGetImage</function>,

-or

-<function>XSubImage</function>,

-the destroy procedure that the 

-<function>XDestroyImage</function>

-function calls frees both the image structure 

-and the data pointed to by the image structure.

-</para>

-<para>

-<!-- .LP -->

-The basic functions used to get a pixel, set a pixel, create a subimage,

-and add a constant value to an image are defined in the image object.

-The functions in this section are really macro invocations of the functions

-in the image object and are defined in

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a pixel value in an image, use

-<function>XGetPixel</function>.

-<indexterm significance="preferred"><primary>XGetPixel</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>unsigned long <function>XGetPixel</function></funcdef>

-  <paramdef>XImage<parameter> *ximage</parameter></paramdef>

-  <paramdef>int<parameter> x</parameter></paramdef>

-  <paramdef>int<parameter> y</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ximage</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the image.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetPixel</function>

-function returns the specified pixel from the named image.

-The pixel value is returned in normalized format (that is,

-the least significant byte of the long is the least significant byte

-of the pixel).

-The image must contain the x and y coordinates.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set a pixel value in an image, use

-<function>XPutPixel</function>.

-<indexterm significance="preferred"><primary>XPutPixel</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XPutPixel</function></funcdef>

-  <paramdef>XImage<parameter> *ximage</parameter></paramdef>

-  <paramdef>int<parameter> x</parameter></paramdef>

-  <paramdef>int<parameter> y</parameter></paramdef>

-  <paramdef>unsignedlong<parameter> pixel</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ximage</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the image.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>pixel</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the new pixel value.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPutPixel</function>

-function overwrites the pixel in the named image with the specified pixel value.

-The input pixel value must be in normalized format

-(that is, the least significant byte of the long is the least significant

-byte of the pixel).

-The image must contain the x and y coordinates.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a subimage, use

-<function>XSubImage</function>.

-<indexterm significance="preferred"><primary>XSubImage</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XImage *<function>XSubImage</function></funcdef>

-  <paramdef>XImage<parameter> *ximage</parameter></paramdef>

-  <paramdef>int<parameter> x</parameter></paramdef>

-  <paramdef>int<parameter> y</parameter></paramdef>

-  <paramdef>unsignedint<parameter> subimage_width</parameter></paramdef>

-  <paramdef>unsignedint<parameter> subimage_height</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ximage</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the image.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>subimage_width</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the width of the new subimage, in pixels.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>subimage_height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the height of the new subimage, in pixels.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSubImage</function>

-function creates a new image that is a subsection of an existing one.

-It allocates the memory necessary for the new

-<structname>XImage</structname>

-structure

-and returns a pointer to the new image.

-The data is copied from the source image,

-and the image must contain the rectangle defined by x, y, subimage_width,

-and subimage_height.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To increment each pixel in an image by a constant value, use

-<function>XAddPixel</function>.

-<indexterm significance="preferred"><primary>XAddPixel</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XAddPixel</function></funcdef>

-  <paramdef>XImage<parameter> *ximage</parameter></paramdef>

-  <paramdef>long<parameter> value</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ximage</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the image.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>value</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the constant value that is to be added.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XAddPixel</function>

-function adds a constant value to every pixel in an image.

-It is useful when you have a base pixel value from allocating

-color resources and need to manipulate the image to that form.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To deallocate the memory allocated in a previous call to

-<function>XCreateImage</function>,

-use

-<function>XDestroyImage</function>.

-<indexterm significance="preferred"><primary>XDestroyImage</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDestroyImage</function></funcdef>

-  <paramdef>XImage *<parameter>ximage</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>ximage</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the image.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDestroyImage</function>

-function deallocates the memory associated with the

-<structname>XImage</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-Note that when the image is created using

-<function>XCreateImage</function>,

-<function>XGetImage</function>,

-or 

-<function>XSubImage</function>,

-the destroy procedure that this macro calls

-frees both the image structure and the data pointed to by the image structure. 

-</para>

-</sect1>

-<sect1 id="Manipulating_Bitmaps">

-<title>Manipulating Bitmaps</title>

-<!-- .XS -->

-<!-- (SN Manipulating Bitmaps  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to read a bitmap from a file,

-save a bitmap to a file, or create a bitmap. 

-This section describes those functions that transfer bitmaps to and

-from the client's file system, thus allowing their reuse in a later

-connection (for example, from an entirely different client or to a

-different display or server).

-</para>

-<para>

-<!-- .LP -->

-The X version 11 bitmap file format is:

-</para>

-<para>

-<!-- .LP -->

-<!-- .sM -->

-<literallayout class="monospaced">

-#define <emphasis remap='I'>name</emphasis>_width <emphasis remap='I'>width</emphasis>

-#define <emphasis remap='I'>name</emphasis>_height <emphasis remap='I'>height</emphasis>

-#define <emphasis remap='I'>name</emphasis>_x_hot <emphasis remap='I'>x</emphasis>

-#define <emphasis remap='I'>name</emphasis>_y_hot <emphasis remap='I'>y</emphasis>

-static unsigned char <emphasis remap='I'>name</emphasis>_bits[] = { 0x<emphasis remap='I'>NN</emphasis>,... }

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The lines for the variables ending with _x_hot and _y_hot suffixes are optional

-because they are present only if a hotspot has been defined for this bitmap.

-The lines for the other variables are required.

-The word ``unsigned'' is optional;

-that is, the type of the _bits array can be ``char'' or ``unsigned char''.

-The _bits array must be large enough to contain the size bitmap.

-The bitmap unit is 8.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To read a bitmap from a file and store it in a pixmap, use

-<function>XReadBitmapFile</function>.

-<indexterm significance="preferred"><primary>XReadBitmapFile</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XReadBitmapFile</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>char<parameter> *filename</parameter></paramdef>

-  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

-  <paramdef>Pixmap<parameter> *bitmap_return</parameter></paramdef>

-  <paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Dr \ that indicates the screen -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable(Dr. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>filename</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the file name to use.

-The format of the file name is operating-system dependent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the width and height values of the read in bitmap file.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bitmap_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the bitmap that is created.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_hot_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y_hot_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the hotspot coordinates.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XReadBitmapFile</function>

-function reads in a file containing a bitmap.

-The file is parsed in the encoding of the current locale.

-The ability to read other than the standard format 

-is implementation-dependent.

-If the file cannot be opened, 

-<function>XReadBitmapFile</function>

-returns 

-<returnvalue>BitmapOpenFailed</returnvalue>.

-If the file can be opened but does not contain valid bitmap data, 

-it returns 

-<returnvalue>BitmapFileInvalid</returnvalue>.

-If insufficient working storage is allocated,

-it returns

-<returnvalue>BitmapNoMemory</returnvalue>.

-If the file is readable and valid,

-it returns 

-<returnvalue>BitmapSuccess</returnvalue>.

-</para>

-<para>

-<!-- .LP -->

-<function>XReadBitmapFile</function>

-returns the bitmap's height and width, as read

-from the file, to width_return and height_return.

-It then creates a pixmap of the appropriate size, 

-reads the bitmap data from the file into the pixmap,

-and assigns the pixmap to the caller's variable bitmap.  

-The caller must free the bitmap using 

-<function>XFreePixmap</function>

-when finished.

-If <emphasis remap='I'>name</emphasis>_x_hot and <emphasis remap='I'>name</emphasis>_y_hot exist,

-<function>XReadBitmapFile</function>

-returns them to x_hot_return and y_hot_return;

-otherwise, it returns &minus;1,&minus;1.

-</para>

-<para>

-<!-- .LP -->

-<function>XReadBitmapFile</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadDrawable</errorname>,

-and

-<errorname>BadGC</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To read a bitmap from a file and return it as data, use

-<function>XReadBitmapFileData</function>.

-<indexterm significance="preferred"><primary>XReadBitmapFileData</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XReadBitmapFileData</function></funcdef>

-  <paramdef>char<parameter> *filename</parameter></paramdef>

-  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

-  <paramdef>unsignedchar<parameter> *data_return</parameter></paramdef>

-  <paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>filename</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the file name to use.

-The format of the file name is operating-system dependent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the width and height values of the read in bitmap file.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the bitmap data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_hot_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y_hot_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the hotspot coordinates.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XReadBitmapFileData</function>

-function reads in a file containing a bitmap, in the same manner as

-<function>XReadBitmapFile</function>,

-but returns the data directly rather than creating a pixmap in the server.

-The bitmap data is returned in data_return; the client must free this

-storage when finished with it by calling

-<function>XFree</function>.

-The status and other return values are the same as for

-<function>XReadBitmapFile</function>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To write out a bitmap from a pixmap to a file, use

-<function>XWriteBitmapFile</function>.

-<indexterm significance="preferred"><primary>XWriteBitmapFile</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XWriteBitmapFile</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char<parameter> *filename</parameter></paramdef>

-  <paramdef>Pixmap<parameter> bitmap</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>intx_hot,<parameter> y_hot</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>filename</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the file name to use.

-The format of the file name is operating-system dependent.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bitmap</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the bitmap.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_hot</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y_hot</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify where to place the hotspot coordinates (or &minus;1,&minus;1 if none are present)

-in the file.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XWriteBitmapFile</function>

-function writes a bitmap out to a file in the X Version 11 format.

-The name used in the output file is derived from the file name

-by deleting the directory prefix.

-The file is written in the encoding of the current locale.

-If the file cannot be opened for writing, 

-it returns 

-<returnvalue>BitmapOpenFailed</returnvalue>.

-If insufficient memory is allocated,

-<function>XWriteBitmapFile</function>

-returns

-<returnvalue>BitmapNoMemory</returnvalue>;

-otherwise, on no error,

-it returns

-<returnvalue>BitmapSuccess</returnvalue>.

-If x_hot and y_hot are not &minus;1, &minus;1,

-<function>XWriteBitmapFile</function>

-writes them out as the hotspot coordinates for the bitmap.

-</para>

-<para>

-<!-- .LP -->

-<function>XWriteBitmapFile</function>

-can generate

-<errorname>BadDrawable</errorname>

-and

-<errorname>BadMatch</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a pixmap and then store bitmap-format data into it, use

-<function>XCreatePixmapFromBitmapData</function>.

-<indexterm significance="preferred"><primary>XCreatePixmapFromBitmapData</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Pixmap <function>XCreatePixmapFromBitmapData</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>char<parameter> *data</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-  <paramdef>unsignedlongfg,<parameter> bg</parameter></paramdef>

-  <paramdef>unsignedint<parameter> depth</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Dr \ that indicates the screen -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable(Dr. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the data in bitmap format.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>fg</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the foreground and background pixel values to use.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>depth</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the depth of the pixmap.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreatePixmapFromBitmapData</function>

-function creates a pixmap of the given depth and then does a bitmap-format

-<function>XPutImage</function>

-of the data into it.

-The depth must be supported by the screen of the specified drawable,

-or a

-<errorname>BadMatch</errorname>

-error results.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreatePixmapFromBitmapData</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadDrawable</errorname>,

-<errorname>BadGC</errorname>,

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To include a bitmap written out by 

-<function>XWriteBitmapFile</function>

-<indexterm><primary>XWriteBitmapFile</primary></indexterm>

-in a program directly, as opposed to reading it in every time at run time, use

-<function>XCreateBitmapFromData</function>.

-<indexterm significance="preferred"><primary>XCreateBitmapFromData</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Pixmap <function>XCreateBitmapFromData</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>char<parameter> *data</parameter></paramdef>

-  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Dr \ that indicates the screen -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable(Dr. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the location of the bitmap data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the width and height.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCreateBitmapFromData</function>

-function allows you to include in your C program (using

-<code>#include</code>)

-a bitmap file that was written out by

-<function>XWriteBitmapFile</function>

-(X version 11 format only) without reading in the bitmap file.

-The following example creates a gray bitmap:

-</para>

-<para>

-<!-- .LP -->

-<literallayout class="monospaced">

-#include "gray.bitmap"

-<!-- .sp 6p -->

-Pixmap bitmap;

-bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-If insufficient working storage was allocated,

-<function>XCreateBitmapFromData</function>

-returns

-<symbol>None</symbol>.

-It is your responsibility to free the

-bitmap using

-<function>XFreePixmap</function>

-when finished.

-</para>

-<para>

-<!-- .LP -->

-<function>XCreateBitmapFromData</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadGC</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Using_the_Context_Manager">

-<title>Using the Context Manager</title>

-<!-- .XS -->

-<!-- (SN Using the Context Manager  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The context manager provides a way of associating data with an X resource ID

-(mostly typically a window) in your program.  

-Note that this is local to your program;

-the data is not stored in the server on a property list.

-Any amount of data in any number of pieces can be associated with a

-resource ID,

-and each piece of data has a type associated with it.  

-The context manager requires knowledge of the resource ID

-and type to store or retrieve data.

-</para>

-<para>

-<!-- .LP -->

-Essentially, the context manager can be viewed as a two-dimensional, 

-sparse array:  one dimension is subscripted by the X resource ID

-and the other by a context type field.

-Each entry in the array contains a pointer to the data.

-Xlib provides context management functions with which you can

-save data values, get data values, delete entries, and create a unique

-context type.

-The symbols used are in

-<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To save a data value that corresponds to a resource ID and context type, use

-<function>XSaveContext</function>.

-<indexterm significance="preferred"><primary>XSaveContext</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XSaveContext</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XID<parameter> rid</parameter></paramdef>

-  <paramdef>XContext<parameter> context</parameter></paramdef>

-  <paramdef>XPointer<parameter> data</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rid</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource ID with which the data is associated.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>context</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the context type to which the data belongs.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the data to be associated with the window and type.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If an entry with the specified resource ID and type already exists,

-<function>XSaveContext</function>

-overrides it with the specified context.

-The

-<function>XSaveContext</function>

-function returns a nonzero error code if an error has occurred

-and zero otherwise.

-Possible errors are

-<symbol>XCNOMEM</symbol>

-(out of memory).

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the data associated with a resource ID and type, use

-<function>XFindContext</function>.

-<indexterm significance="preferred"><primary>XFindContext</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XFindContext</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XID<parameter> rid</parameter></paramdef>

-  <paramdef>XContext<parameter> context</parameter></paramdef>

-  <paramdef>XPointer<parameter> *data_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rid</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource ID with which the data is associated.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>context</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the context type to which the data belongs.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the data.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-Because it is a return value,

-the data is a pointer.

-The

-<function>XFindContext</function>

-function returns a nonzero error code if an error has occurred

-and zero otherwise.

-Possible errors are

-<symbol>XCNOENT</symbol>

-(context-not-found).

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To delete an entry for a given resource ID and type, use

-<function>XDeleteContext</function>.

-<indexterm significance="preferred"><primary>XDeleteContext</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XDeleteContext</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XID<parameter> rid</parameter></paramdef>

-  <paramdef>XContext<parameter> context</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>rid</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the resource ID with which the data is associated.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>context</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the context type to which the data belongs.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDeleteContext</function>

-function deletes the entry for the given resource ID 

-and type from the data structure.

-This function returns the same error codes that

-<function>XFindContext</function>

-returns if called with the same arguments.

-<function>XDeleteContext</function>

-does not free the data whose address was saved.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To create a unique context type that may be used in subsequent calls to

-<function>XSaveContext</function>

-and

-<function>XFindContext</function>,

-use

-<function>XUniqueContext</function>.

-</para>

-<para>XContext XuniqueContext()</para>

-

-</sect1>

-</chapter>

+<?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="application_utility_functions">
+<title>Application Utility Functions</title>
+<!-- .sp 2 -->
+<!-- .nr H1 16 -->
+<!-- .nr H2 0 -->
+<!-- .nr H3 0 -->
+<!-- .nr H4 0 -->
+<!-- .nr H5 0 -->
+<!-- .na -->
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Chapter 16: Application Utility Functions  -->
+<!-- .XE -->
+Once you have initialized the X system,
+you can use the Xlib utility functions to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Use keyboard utility functions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Use Latin-1 keyboard event functions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Allocate permanent storage
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Parse the window geometry
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Manipulate regions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Use cut buffers
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Determine the appropriate visual type
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Manipulate images
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Manipulate bitmaps
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Use the context manager
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+As a group,
+the functions discussed in this chapter provide the functionality that 
+is frequently needed and that spans toolkits.
+Many of these functions do not generate actual protocol requests to the server.
+</para>
+<sect1 id="Using_Keyboard_Utility_Functions">
+<title>Using Keyboard Utility Functions</title>
+<!-- .XS -->
+<!-- (SN Using Keyboard Utility Functions  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses mapping between KeyCodes and KeySyms,
+classifying KeySyms, and mapping between KeySyms and string names.
+The first three functions in this section operate on a cached copy of the
+server keyboard mapping.
+The first four KeySyms for each KeyCode
+are modified according to the rules given in section 12.7.
+To obtain the untransformed KeySyms defined for a key,
+use the functions described in section 12.7.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a KeySym for the KeyCode of an event, use
+<function>XLookupKeysym</function>.
+<indexterm significance="preferred"><primary>XLookupKeysym</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlookupkeysym'>
+<funcprototype>
+  <funcdef>KeySym <function>XLookupKeysym</function></funcdef>
+  <paramdef>XKeyEvent<parameter> *key_event</parameter></paramdef>
+  <paramdef>int<parameter> index</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>key_event</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the 
+<symbol>KeyPress</symbol>
+or
+<symbol>KeyRelease</symbol>
+event.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>index</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the index into the KeySyms list for the event's KeyCode.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLookupKeysym</function>
+function uses a given keyboard event and the index you specified to return
+the KeySym from the list that corresponds to the KeyCode member in the
+<type>XKeyPressedEvent</type>
+or
+<type>XKeyReleasedEvent</type>
+structure.
+If no KeySym is defined for the KeyCode of the event,
+<function>XLookupKeysym</function>
+returns
+<symbol>NoSymbol</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a KeySym for a specific KeyCode, use
+<function>XKeycodeToKeysym</function>.
+<indexterm significance="preferred"><primary>XKeycodeToKeysym</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xkeycodetokeysym'>
+<funcprototype>
+  <funcdef>KeySym <function>XKeycodeToKeysym</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>KeyCode<parameter> keycode</parameter></paramdef>
+  <paramdef>int<parameter> index</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keycode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeyCode.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>index</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the element of KeyCode vector.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XKeycodeToKeysym</function>
+function uses internal Xlib tables
+and returns the KeySym defined for the specified KeyCode and
+the element of the KeyCode vector.
+If no symbol is defined,
+<function>XKeycodeToKeysym</function>
+returns
+<symbol>NoSymbol</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a KeyCode for a key having a specific KeySym, use
+<function>XKeysymToKeycode</function>.
+<indexterm significance="preferred"><primary>XKeysymToKeycode</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xkeysymtokeycode'>
+<funcprototype>
+  <funcdef>KeyCode <function>XKeysymToKeycode</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>KeySym<parameter> keysym</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be searched for.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the specified KeySym is not defined for any KeyCode,
+<function>XKeysymToKeycode</function>
+returns zero.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The mapping between KeyCodes and KeySyms is cached internal to Xlib.
+When this information is changed at the server, an Xlib function must
+be called to refresh the cache.
+To refresh the stored modifier and keymap information, use
+<function>XRefreshKeyboardMapping</function>.
+<indexterm significance="preferred"><primary>XRefreshKeyboardMapping</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrefreshkeyboardmapping'>
+<funcprototype>
+  <funcdef><function>XRefreshKeyboardMapping</function></funcdef>
+  <paramdef>XMappingEvent<parameter> *event_map</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_map</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the mapping event that is to be used.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRefreshKeyboardMapping</function>
+function refreshes the stored modifier and keymap information.
+You usually call this function when a
+<symbol>MappingNotify</symbol>
+event with a request member of
+<symbol>MappingKeyboard</symbol>
+or
+<symbol>MappingModifier</symbol>
+occurs.
+The result is to update Xlib's knowledge of the keyboard.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the uppercase and lowercase forms of a KeySym, use
+<function>XConvertCase</function>.
+<indexterm significance="preferred"><primary>XConvertCase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xconvertcase'>
+<funcprototype>
+  <funcdef>void <function>XConvertCase</function></funcdef>
+  <paramdef>KeySym<parameter> keysym</parameter></paramdef>
+  <paramdef>KeySym<parameter> *lower_return</parameter></paramdef>
+  <paramdef>KeySym<parameter> *upper_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Fn converted -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be (Fn.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>lower_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the lowercase form of keysym, or keysym.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>upper_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the uppercase form of keysym, or keysym.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XConvertCase</function>
+function returns the uppercase and lowercase forms of the specified Keysym,
+if the KeySym is subject to case conversion;
+otherwise, the specified KeySym is returned to both lower_return and
+upper_return.
+Support for conversion of other than Latin and Cyrillic KeySyms is
+implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+KeySyms have string names as well as numeric codes.
+To convert the name of the KeySym to the KeySym code, use
+<function>XStringToKeysym</function>.
+<indexterm significance="preferred"><primary>XStringToKeysym</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xstringtokeysym'>
+<funcprototype>
+  <funcdef>KeySym <function>XStringToKeysym</function></funcdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the name of the KeySym that is to be converted.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Standard KeySym names are obtained from
+<filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/keysymdef.h&gt;</filename></secondary></indexterm>
+by removing the XK_ prefix from each name.
+KeySyms that are not part of the Xlib standard also may be obtained
+with this function.
+The set of KeySyms that are available in this manner 
+and the mechanisms by which Xlib obtains them is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+If the KeySym name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+If the specified string does not match a valid KeySym,
+<function>XStringToKeysym</function>
+returns
+<symbol>NoSymbol</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a KeySym code to the name of the KeySym, use
+<function>XKeysymToString</function>.
+<indexterm significance="preferred"><primary>XKeysymToString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xkeysymtostring'>
+<funcprototype>
+  <funcdef>char *<function>XKeysymToString</function></funcdef>
+  <paramdef>KeySym<parameter> keysym</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Fn converted -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be (Fn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The returned string is in a static area and must not be modified.
+The returned string is in the Host Portable Character Encoding.
+If the specified KeySym is not defined,
+<function>XKeysymToString</function>
+returns a NULL.
+</para>
+<sect2 id="KeySym_Classification_Macros">
+<title>KeySym Classification Macros</title>
+<!-- .XS -->
+<!-- (SN KeySym Classification Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You may want to test if a KeySym is, for example, 
+on the keypad or on one of the function keys.
+You can use KeySym macros to perform the following tests.
+</para>
+<para>IsCursorKey(<emphasis remap='I'>keysym</emphasis>)</para>
+<!-- .FN -->
+<!-- .ds Fn tested -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be tested.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsCursorKey</primary></indexterm>
+Returns
+<symbol>True</symbol>
+if the specified KeySym is a cursor key.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>
+<!-- .FN -->
+<!-- .ds Fn tested -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be tested.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsFunctionKey</primary></indexterm>
+Returns 
+<symbol>True</symbol>
+if the specified KeySym is a function key.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>
+<!-- .FN -->
+<!-- .ds Fn tested -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be (Fn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsKeypadKey</primary></indexterm>
+Returns
+<symbol>True</symbol>
+if the specified KeySym is a standard keypad key.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsPrivateKeypadKey(<emphasis remap='I'>keysym</emphasis>)</para>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be (Fn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsPrivateKeypadKey</primary></indexterm>
+Returns
+<symbol>True</symbol>
+if the specified KeySym is a vendor-private keypad key.
+</para>
+
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsMiscFunctionKey(<emphasis remap='I'>keysym</emphasis>)</para>
+<!-- .FN -->
+<!-- .ds Fn tested -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be (Fn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsMiscFunctionKey</primary></indexterm>
+Returns 
+<symbol>True</symbol>
+if the specified KeySym is a miscellaneous function key.
+</para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<para>IsModifierKey(<emphasis remap='I'>keysym</emphasis>)</para>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be tested.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsModifierKey</primary></indexterm>
+Returns 
+<symbol>True</symbol>
+if the specified KeySym is a modifier key.
+</para>
+
+<para>IsPFKey(<emphasis remap='I'>keysym</emphasis>)</para>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be tested.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>IsPFKey</primary></indexterm>
+Returns 
+<symbol>True</symbol>
+if the specified KeySym is a PF key.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Using_Latin_Keyboard_Event_Functions">
+<title>Using Latin-1 Keyboard Event Functions</title>
+<!-- .XS -->
+<!-- (SN Using Latin-1 Keyboard Event Functions  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Chapter 13 describes internationalized text input facilities,
+but sometimes it is expedient to write an application that
+only deals with Latin-1 characters and ASCII controls,
+so Xlib provides a simple function for that purpose.
+<function>XLookupString</function>
+handles the standard modifier semantics described in section 12.7.
+This function does not use any of the input method facilities
+described in chapter 13 and does not depend on the current locale.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a key event to an ISO Latin-1 string, use
+<function>XLookupString</function>.
+<indexterm significance="preferred"><primary>XLookupString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlookupstring'>
+<funcprototype>
+  <funcdef>int <function>XLookupString</function></funcdef>
+  <paramdef>XKeyEvent<parameter> *event_struct</parameter></paramdef>
+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+  <paramdef>int<parameter> bytes_buffer</parameter></paramdef>
+  <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
+  <paramdef>XComposeStatus<parameter> *status_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_struct</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the key event structure to be used.
+You can pass
+<type>XKeyPressedEvent</type>
+or
+<type>XKeyReleasedEvent</type>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buffer_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the translated characters.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bytes_buffer</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the length of the buffer.
+No more than bytes_buffer of translation are returned.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the KeySym computed from the event if this argument is not NULL.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>status_in_out</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies or returns the 
+<structname>XComposeStatus</structname>
+structure or NULL.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLookupString</function>
+function translates a key event to a KeySym and a string.
+The KeySym is obtained by using the standard interpretation of the
+<symbol>Shift</symbol>,
+<symbol>Lock</symbol>,
+group, and numlock modifiers as defined in the X Protocol specification.
+If the KeySym has been rebound (see
+<function>XRebindKeysym</function>),
+the bound string will be stored in the buffer.
+Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
+or (if the Control modifier is on) to an ASCII control character,
+and that character is stored in the buffer.
+<function>XLookupString</function>
+returns the number of characters that are stored in the buffer.
+</para>
+<para>
+<!-- .LP -->
+If present (non-NULL),
+the
+<structname>XComposeStatus</structname>
+structure records the state,
+which is private to Xlib,
+that needs preservation across calls to
+<function>XLookupString</function>
+to implement compose processing.
+The creation of
+<structname>XComposeStatus</structname>
+structures is implementation-dependent;
+a portable program must pass NULL for this argument.
+</para>
+<para>
+<!-- .LP -->
+<function>XLookupString</function>
+depends on the cached keyboard information mentioned in the
+previous section, so it is necessary to use
+<function>XRefreshKeyboardMapping</function>
+to keep this information up-to-date.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To rebind the meaning of a KeySym for
+<function>XLookupString</function>,
+use
+<function>XRebindKeysym</function>.
+<indexterm significance="preferred"><primary>XRebindKeysym</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrebindkeysym'>
+<funcprototype>
+  <funcdef><function>XRebindKeysym</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>KeySym<parameter> keysym</parameter></paramdef>
+  <paramdef>KeySym<parameter> list[&hairsp;]</parameter></paramdef>
+  <paramdef>int<parameter> mod_count</parameter></paramdef>
+  <paramdef>unsignedchar<parameter> *string</parameter></paramdef>
+  <paramdef>int<parameter> num_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Fn rebound -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>keysym</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySym that is to be (Fn.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>list</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the KeySyms to be used as modifiers.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mod_count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of modifiers in the modifier list.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the string that is copied and will be returned by 
+<function>XLookupString</function>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_bytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes in the string argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRebindKeysym</function>
+function can be used to rebind the meaning of a KeySym for the client.
+It does not redefine any key in the X server but merely
+provides an easy way for long strings to be attached to keys.
+<function>XLookupString</function>
+returns this string when the appropriate set of
+modifier keys are pressed and when the KeySym would have been used for
+the translation.
+No text conversions are performed;
+the client is responsible for supplying appropriately encoded strings.
+Note that you can rebind a KeySym that may not exist.
+</para>
+</sect1>
+<sect1 id="Allocating_Permanent_Storage">
+<title>Allocating Permanent Storage</title>
+<!-- .XS -->
+<!-- (SN Allocating Permanent Storage -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To allocate some memory you will never give back, use
+<function>Xpermalloc</function>.
+<indexterm significance="preferred"><primary>Xpermalloc</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpermalloc'>
+<funcprototype>
+  <funcdef>char *<function>Xpermalloc</function></funcdef>
+  <paramdef>unsignedint<parameter> size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>Xpermalloc</function>
+function allocates storage that can never be freed for the life of the
+program.  The memory is allocated with alignment for the C type double.
+This function may provide some performance and space savings over
+the standard operating system memory allocator.
+</para>
+</sect1>
+<sect1 id="Parsing_the_Window_Geometry">
+<title>Parsing the Window Geometry</title>
+<!-- .XS -->
+<!-- (SN Parsing the Window Geometry  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To parse standard window geometry strings, use
+<function>XParseGeometry</function>.
+<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>
+<indexterm significance="preferred"><primary>XParseGeometry</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<funcsynopsis id='xparsegeometry'>
+<funcprototype>
+  <funcdef>int <function>XParseGeometry</function></funcdef>
+  <paramdef>char<parameter> *parsestring</parameter></paramdef>
+  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>parsestring</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the string you want to parse.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the x and y offsets.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the width and height determined.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+By convention,
+X applications use a standard string to indicate window size and placement.
+<function>XParseGeometry</function>
+makes it easier to conform to this standard because it allows you
+to parse the standard window geometry.
+Specifically, this function lets you parse strings of the form:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+[=][&lt;<emphasis remap='I'>width</emphasis>&gt;{xX}&lt;<emphasis remap='I'>height</emphasis>&gt;][{+-}&lt;<emphasis remap='I'>xoffset</emphasis>&gt;{+-}&lt;<emphasis remap='I'>yoffset</emphasis>&gt;] 
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+The fields map into the arguments associated with this function.
+(Items enclosed in &lt;&hairsp;&gt; are integers, items in [&hairsp;] are optional, and
+items enclosed in {&hairsp;} indicate ``choose one of.''
+Note that the brackets should not appear in the actual string.)
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XParseGeometry</function>
+function returns a bitmask that indicates which of the four values (width,
+height, xoffset, and yoffset) were actually found in the string 
+and whether the x and y values are negative. 
+By convention, &minus;0 is not equal to +0, because the user needs to
+be able to say ``position the window relative to the right or bottom edge.''
+For each value found, the corresponding argument is updated.
+For each value not found, the argument is left unchanged.
+The bits are represented by
+<symbol>XValue</symbol>,
+<symbol>YValue</symbol>,
+<symbol>WidthValue</symbol>,
+<symbol>HeightValue</symbol>,
+<symbol>XNegative</symbol>,
+or
+<symbol>YNegative</symbol>
+and are defined in 
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+They will be set whenever one of the values is defined 
+or one of the signs is set.
+</para>
+<para>
+<!-- .LP -->
+If the function returns either the 
+<symbol>XValue</symbol>
+or 
+<symbol>YValue</symbol>
+flag,
+you should place the window at the requested position.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To construct a window's geometry information, use
+<function>XWMGeometry</function>.
+<indexterm significance="preferred"><primary>XWMGeometry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xwmgeometry'>
+<funcprototype>
+  <funcdef>int <function>XWMGeometry</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> screen</parameter></paramdef>
+  <paramdef>char<parameter> *user_geom</parameter></paramdef>
+  <paramdef>char<parameter> *def_geom</parameter></paramdef>
+  <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>
+  <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
+  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
+  <paramdef>int<parameter> *width_return</parameter></paramdef>
+  <paramdef>int<parameter> *height_return</parameter></paramdef>
+  <paramdef>int<parameter> *gravity_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>user_geom</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the user-specified geometry or NULL.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>def_geom</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the application's default geometry or NULL.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bwidth</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the border width.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>hints</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size hints for the window in its normal state.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the x and y offsets.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the width and height determined.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gravity_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the window gravity.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The 
+<function>XWMGeometry</function>
+function combines any geometry information (given in the format used by 
+<function>XParseGeometry</function>)
+specified by the user and by the calling program with size hints 
+(usually the ones to be stored in <property>WM_NORMAL_HINTS</property>) and returns the position, 
+size, and gravity
+(<symbol>NorthWestGravity</symbol>,
+<symbol>NorthEastGravity</symbol>,
+<symbol>SouthEastGravity</symbol>,
+or
+<symbol>SouthWestGravity</symbol>)
+that describe the window.
+If the base size is not set in the 
+<structname>XSizeHints</structname>
+structure, 
+the minimum size is used if set.
+Otherwise, a base size of zero is assumed.
+If no minimum size is set in the hints structure, 
+the base size is used.
+A mask (in the form returned by 
+<function>XParseGeometry</function>)
+that describes which values came from the user specification 
+and whether or not the position coordinates are relative
+to the right and bottom edges is returned.
+Note that these coordinates will have already been accounted for 
+in the x_return and y_return values.
+</para>
+<para>
+<!-- .LP -->
+Note that invalid geometry specifications can cause a width or height 
+of zero to be returned.
+The caller may pass the address of the hints win_gravity field 
+as gravity_return to update the hints directly.
+</para>
+</sect1>
+
+<sect1 id="Manipulating_Regions">
+<title>Manipulating Regions</title>
+<!-- .XS -->
+<!-- (SN Manipulating Regions  -->
+<!-- .XE -->
+<para>
+Regions are arbitrary sets of pixel locations.
+Xlib provides functions for manipulating regions.
+The opaque type 
+<structname>Region</structname>
+is defined in 
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+Xlib provides functions that you can use to manipulate regions.
+This section discusses how to:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+Create, copy, or destroy regions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Move or shrink regions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Compute with regions
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Determine if regions are empty or equal
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Locate a point or rectangle in a region
+    </para>
+  </listitem>
+</itemizedlist>
+
+<sect2 id="Creating_Copying_or_Destroying_Regions">
+<title>Creating, Copying, or Destroying Regions</title>
+<!-- .XS -->
+<!-- (SN Creating, Copying, or Destroying Regions  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To create a new empty region, use
+<function>XCreateRegion</function>.
+</para>
+<para>Region XCreateRegion()</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To generate a region from a polygon, use
+<function>XPolygonRegion</function>.
+</para>
+<indexterm significance="preferred"><primary>XPolygonRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpolygonregion'>
+<funcprototype>
+  <funcdef>Region <function>XPolygonRegion</function></funcdef>
+  <paramdef>XPoint<parameter> points[]</parameter></paramdef>
+  <paramdef>int<parameter> n</parameter></paramdef>
+  <paramdef>int<parameter> fill_rule</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>points</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies an array of points.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>n</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of points in the polygon. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>fill_rule</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the fill-rule you want to set for the specified GC.
+You can pass 
+<symbol>EvenOddRule</symbol>
+or
+<symbol>WindingRule</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XPolygonRegion</function>
+function returns a region for the polygon defined by the points array.
+For an explanation of fill_rule,
+see
+<function>XCreateGC</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the clip-mask of a GC to a region, use
+<function>XSetRegion</function>.
+<indexterm significance="preferred"><primary>XSetRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetregion'>
+<funcprototype>
+  <funcdef><function>XSetRegion</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>GC<parameter> gc</parameter></paramdef>
+  <paramdef>Region<parameter> r</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>gc</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the GC.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the region.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetRegion</function>
+function sets the clip-mask in the GC to the specified region.
+The region is specified relative to the drawable's origin.
+The resulting GC clip origin is implementation-dependent.
+Once it is set in the GC,
+the region can be destroyed.
+</para>
+<para>
+<!-- .LP  -->
+<!-- .sp -->
+To deallocate the storage associated with a specified region, use
+<function>XDestroyRegion</function>.
+<indexterm significance="preferred"><primary>XDestroyRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroyregion'>
+<funcprototype>
+  <funcdef><function>XDestroyRegion</function></funcdef>
+  <paramdef>Region<parameter> r</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the region.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Moving_or_Shrinking_Regions">
+<title>Moving or Shrinking Regions</title>
+<!-- .XS -->
+<!-- (SN Moving or Shrinking Regions  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To move a region by a specified amount, use 
+<function>XOffsetRegion</function>.
+<indexterm significance="preferred"><primary>XOffsetRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xoffsetregion'>
+<funcprototype>
+  <funcdef><function>XOffsetRegion</function></funcdef>
+  <paramdef>Region<parameter> r</parameter></paramdef>
+  <paramdef>intdx,<parameter> dy</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the region.
+<!-- .ds Dy move -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dx</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dy</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates,
+which define the amount you want to (Dy the specified region.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+<!-- .sp -->
+To reduce a region by a specified amount, use
+<function>XShrinkRegion</function>.
+<indexterm significance="preferred"><primary>XShrinkRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xshrinkregion'>
+<funcprototype>
+  <funcdef><function>XShrinkRegion</function></funcdef>
+  <paramdef>Region<parameter> r</parameter></paramdef>
+  <paramdef>intdx,<parameter> dy</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the region.
+<!-- .ds Dy shrink -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dx</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dy</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates,
+which define the amount you want to (Dy the specified region.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Positive values shrink the size of the region, 
+and negative values expand the region.
+</para>
+</sect2>
+<sect2 id="Computing_with_Regions">
+<title>Computing with Regions</title>
+<!-- .XS -->
+<!-- (SN Computing with Regions  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To generate the smallest rectangle enclosing a region, use
+<function>XClipBox</function>.
+<indexterm significance="preferred"><primary>XClipBox</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xclipbox'>
+<funcprototype>
+  <funcdef><function>XClipBox</function></funcdef>
+  <paramdef>Region<parameter> r</parameter></paramdef>
+  <paramdef>XRectangle<parameter> *rect_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the region.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rect_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the smallest enclosing rectangle.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XClipBox</function>
+function returns the smallest rectangle enclosing the specified region.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To compute the intersection of two regions, use
+<function>XIntersectRegion</function>.
+<indexterm significance="preferred"><primary>XIntersectRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xintersectregion'>
+<funcprototype>
+  <funcdef><function>XIntersectRegion</function></funcdef>
+  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>sra</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>srb</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the two regions with which you want to perform the computation.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dr_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the result of the computation.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To compute the union of two regions, use
+<function>XUnionRegion</function>.
+<indexterm significance="preferred"><primary>XUnionRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunionregion'>
+<funcprototype>
+  <funcdef><function>XUnionRegion</function></funcdef>
+  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>sra</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>srb</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the two regions with which you want to perform the computation.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dr_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the result of the computation.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To create a union of a source region and a rectangle, use
+<function>XUnionRectWithRegion</function>.
+<indexterm significance="preferred"><primary>XUnionRectWithRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunionrectwithregion'>
+<funcprototype>
+  <funcdef><function>XUnionRectWithRegion</function></funcdef>
+  <paramdef>XRectangle<parameter> *rectangle</parameter></paramdef>
+  <paramdef>Region<parameter> src_region</parameter></paramdef>
+  <paramdef>Region<parameter> dest_region_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rectangle</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the rectangle.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_region</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the source region to be used.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_region_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the destination region.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnionRectWithRegion</function>
+function updates the destination region from a union of the specified rectangle
+and the specified source region.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To subtract two regions, use
+<function>XSubtractRegion</function>.
+<indexterm significance="preferred"><primary>XSubtractRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsubtractregion'>
+<funcprototype>
+  <funcdef><function>XSubtractRegion</function></funcdef>
+  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>sra</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>srb</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the two regions with which you want to perform the computation.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dr_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the result of the computation.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSubtractRegion</function>
+function subtracts srb from sra and stores the results in dr_return.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To calculate the difference between the union and intersection 
+of two regions, use
+<function>XXorRegion</function>.
+<indexterm significance="preferred"><primary>XXorRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xxorregion'>
+<funcprototype>
+  <funcdef><function>XXorRegion</function></funcdef>
+  <paramdef>Regionsra,srb,<parameter> dr_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>sra</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>srb</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the two regions with which you want to perform the computation.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dr_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the result of the computation.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+</para>
+</sect2>
+<sect2 id="Determining_if_Regions_Are_Empty_or_Equal">
+<title>Determining if Regions Are Empty or Equal</title>
+<!-- .XS -->
+<!-- (SN Determining if Regions Are Empty or Equal  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To determine if the specified region is empty, use
+<function>XEmptyRegion</function>.
+<indexterm significance="preferred"><primary>XEmptyRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xemptyregion'>
+<funcprototype>
+  <funcdef>Bool <function>XEmptyRegion</function></funcdef>
+  <paramdef>Region<parameter> r</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the region.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XEmptyRegion</function>
+function returns
+<symbol>True</symbol>
+if the region is empty.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine if two regions have the same offset, size, and shape, use
+<function>XEqualRegion</function>.
+<indexterm significance="preferred"><primary>XEqualRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xequalregion'>
+<funcprototype>
+  <funcdef>Bool <function>XEqualRegion</function></funcdef>
+  <paramdef>Regionr1,<parameter> r2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r1</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r2</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the two regions.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XEqualRegion</function>
+function returns
+<symbol>True</symbol>
+if the two regions have the same offset, size, and shape.
+</para>
+</sect2>
+<sect2 id="Locating_a_Point_or_a_Rectangle_in_a_Region">
+<title>Locating a Point or a Rectangle in a Region</title>
+<!-- .XS -->
+<!-- (SN Locating a Point or a Rectangle in a Region  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To determine if a specified point resides in a specified region, use
+<function>XPointInRegion</function>.
+<indexterm significance="preferred"><primary>XPointInRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpointinregion'>
+<funcprototype>
+  <funcdef>Bool <function>XPointInRegion</function></funcdef>
+  <paramdef>Region<parameter> r</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the region.
+<!-- .ds Xy , which define the point -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPointInRegion</function>
+function returns 
+<symbol>True</symbol>
+if the point (x, y) is contained in the region r.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine if a specified rectangle is inside a region, use
+<function>XRectInRegion</function>.
+<indexterm significance="preferred"><primary>XRectInRegion</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrectinregion'>
+<funcprototype>
+  <funcdef>int <function>XRectInRegion</function></funcdef>
+  <paramdef>Region<parameter> r</parameter></paramdef>
+  <paramdef>intx,<parameter> y</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>r</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the region.
+<!-- .ds Xy , which define the coordinates of the upper-left corner of the rectangle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates(Xy.
+<!-- .ds Wh , which define the rectangle -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height(Wh.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XRectInRegion</function>
+function returns
+<symbol>RectangleIn</symbol>
+if the rectangle is entirely in the specified region,
+<symbol>RectangleOut</symbol>
+if the rectangle is entirely out of the specified region,
+and
+<symbol>RectanglePart</symbol>
+if the rectangle is partially in the specified region.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Using_Cut_Buffers">
+<title>Using Cut Buffers</title>
+<!-- .XS -->
+<!-- (SN Using Cut Buffers  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Cut Buffers</primary></indexterm>
+Xlib provides functions to manipulate cut buffers,
+a very simple form of cut-and-paste inter-client communication.
+Selections are a much more powerful and useful mechanism for
+interchanging data between clients (see section 4.5)
+and generally should be used instead of cut buffers.
+</para>
+<para>
+<!-- .LP -->
+Cut buffers are implemented as properties on the first root window
+of the display.
+The buffers can only contain text, in the STRING encoding.
+The text encoding is not changed by Xlib when fetching or storing.
+Eight buffers are provided
+and can be accessed as a ring or as explicit buffers (numbered 0 through 7).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store data in cut buffer 0, use 
+<function>XStoreBytes</function>.
+<indexterm significance="preferred"><primary>XStoreBytes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xstorebytes'>
+<funcprototype>
+  <funcdef><function>XStoreBytes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *bytes</parameter></paramdef>
+  <paramdef>int<parameter> nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN  -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the bytes, which are not necessarily ASCII or null-terminated.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes to be stored.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The data can have embedded null characters
+and need not be null-terminated.
+The cut buffer's contents can be retrieved later by
+any client calling
+<function>XFetchBytes</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreBytes</function>
+can generate a
+<errorname>BadAlloc</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store data in a specified cut buffer, use
+<function>XStoreBuffer</function>.
+<indexterm significance="preferred"><primary>XStoreBuffer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xstorebuffer'>
+<funcprototype>
+  <funcdef><function>XStoreBuffer</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *bytes</parameter></paramdef>
+  <paramdef>int<parameter> nbytes</parameter></paramdef>
+  <paramdef>int<parameter> buffer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the bytes, which are not necessarily ASCII or null-terminated.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes to be stored.
+<!-- .ds Fn in which you want to store the bytes -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buffer</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the buffer (Fn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If an invalid buffer is specified, the call has no effect.
+The data can have embedded null characters
+and need not be null-terminated.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreBuffer</function>
+can generate a
+<errorname>BadAlloc</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return data from cut buffer 0, use 
+<function>XFetchBytes</function>.
+<indexterm significance="preferred"><primary>XFetchBytes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfetchbytes'>
+<funcprototype>
+  <funcdef>char *<function>XFetchBytes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> *nbytes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of bytes in the buffer.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFetchBytes</function>
+function
+returns the number of bytes in the nbytes_return argument,
+if the buffer contains data.
+Otherwise, the function
+returns NULL and sets nbytes to 0.
+The appropriate amount of storage is allocated and the pointer returned.
+The client must free this storage when finished with it by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return data from a specified cut buffer, use 
+<function>XFetchBuffer</function>.
+<indexterm significance="preferred"><primary>XFetchBuffer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfetchbuffer'>
+<funcprototype>
+  <funcdef>char *<function>XFetchBuffer</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> *nbytes_return</parameter></paramdef>
+  <paramdef>int<parameter> buffer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nbytes_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of bytes in the buffer.
+<!-- .ds Fn from which you want the stored data returned -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buffer</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the buffer (Fn.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFetchBuffer</function>
+function returns zero to the nbytes_return argument 
+if there is no data in the buffer or if an invalid
+buffer is specified.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To rotate the cut buffers, use 
+<function>XRotateBuffers</function>.
+<indexterm significance="preferred"><primary>XRotateBuffers</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrotatebuffers'>
+<funcprototype>
+  <funcdef><function>XRotateBuffers</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> rotate</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rotate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies how much to rotate the cut buffers.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XRotateBuffers</function>
+function rotates the cut
+buffers, such that buffer 0 becomes buffer n, 
+buffer 1 becomes n + 1 mod 8, and so on.
+This cut buffer numbering is global to the display.
+Note that
+<function>XRotateBuffers</function>
+generates
+<errorname>BadMatch</errorname>
+errors if any of the eight buffers have not been created.
+</para>
+</sect1>
+<sect1 id="Determining_the_Appropriate_Visual_Type">
+<title>Determining the Appropriate Visual Type</title>
+<!-- .XS -->
+<!-- (SN Determining the Appropriate Visual Type -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A single display can support multiple screens.
+Each screen can have several different visual types supported 
+at different depths.
+You can use the functions described in this section to determine
+which visual to use for your application.
+</para>
+<para>
+<!-- .LP -->
+The functions in this section use the visual information masks and the
+<structname>XVisualInfo</structname>
+structure,
+which is defined in
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+and contains:
+<!-- .sM -->
+</para>
+<!-- .LP -->
+<literallayout class="monospaced">
+
+/* Visual information mask bits */
+
+
+#define   VisualNoMask                 0x0
+#define   VisualIDMask                 0x1
+#define   VisualScreenMask             0x2
+#define   VisualDepthMask              0x4
+#define   VisualClassMask              0x8
+#define   VisualRedMaskMask            0x10
+#define   VisualGreenMaskMask          0x20
+#define   VisualBlueMaskMask           0x40
+#define   VisualColormapSizeMask       0x80
+#define   VisualBitsPerRGBMask         0x100
+#define   VisualAllMask                0x1FF
+
+</literallayout>
+
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+/* Values */
+
+typedef struct {
+     Visual *visual;
+     VisualID visualid;
+     int screen;
+     unsigned int depth;
+     int class;
+     unsigned long red_mask;
+     unsigned long green_mask;
+     unsigned long blue_mask;
+     int colormap_size;
+     int bits_per_rgb;
+} XVisualInfo;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To obtain a list of visual information structures that match a specified
+template, use
+<function>XGetVisualInfo</function>.
+<indexterm significance="preferred"><primary>XGetVisualInfo</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetvisualinfo'>
+<funcprototype>
+  <funcdef>XVisualInfo *<function>XGetVisualInfo</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>long<parameter> vinfo_mask</parameter></paramdef>
+  <paramdef>XVisualInfo<parameter> *vinfo_template</parameter></paramdef>
+  <paramdef>int<parameter> *nitems_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>vinfo_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the visual mask value.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>vinfo_template</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the visual attributes that are to be used in matching the visual
+structures.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nitems_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of matching visual structures.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetVisualInfo</function>
+function returns a list of visual structures that have attributes 
+equal to the attributes specified by vinfo_template.
+If no visual structures match the template using the specified vinfo_mask,
+<function>XGetVisualInfo</function>
+returns a NULL.
+To free the data returned by this function, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the visual information that matches the specified depth and
+class of the screen, use
+<function>XMatchVisualInfo</function>.
+<indexterm significance="preferred"><primary>XMatchVisualInfo</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmatchvisualinfo'>
+<funcprototype>
+  <funcdef>Status <function>XMatchVisualInfo</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> screen</parameter></paramdef>
+  <paramdef>int<parameter> depth</parameter></paramdef>
+  <paramdef>int<parameter> class</parameter></paramdef>
+  <paramdef>XVisualInfo<parameter> *vinfo_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>screen</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>depth</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the depth of the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>class</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the class of the screen.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>vinfo_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched visual information.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMatchVisualInfo</function>
+function returns the visual information for a visual that matches the specified
+depth and class for a screen.
+Because multiple visuals that match the specified depth and class can exist,
+the exact visual chosen is undefined.
+If a visual is found,
+<function>XMatchVisualInfo</function>
+returns nonzero and the information on the visual to vinfo_return.
+Otherwise, when a visual is not found,
+<function>XMatchVisualInfo</function>
+returns zero.
+</para>
+</sect1>
+<sect1 id="Manipulating_Images">
+<title>Manipulating Images</title>
+<!-- .XS -->
+<!-- (SN Manipulating Images  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides several functions that perform basic operations on images.
+All operations on images are defined using an 
+<structname>XImage</structname>
+structure, 
+as defined in
+<filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
+Because the number of different types of image formats can be very large,
+this hides details of image storage properly from applications.
+</para>
+<para>
+<!-- .LP -->
+This section describes the functions for generic operations on images.
+Manufacturers can provide very fast implementations of these for the
+formats frequently encountered on their hardware.
+These functions are neither sufficient nor desirable to use for general image
+processing.
+Rather, they are here to provide minimal functions on screen format
+images.
+The basic operations for getting and putting images are
+<function>XGetImage</function>
+and 
+<function>XPutImage</function>.
+</para>
+<para>
+<!-- .LP -->
+Note that no functions have been defined, as yet, to read and write images 
+to and from disk files.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XImage</structname>
+structure describes an image as it exists in the client's memory.  
+The user can request that some of the members such as height, width, 
+and xoffset be changed when the image is sent to the server.
+Note that bytes_per_line in concert with offset can be used to
+extract a subset of the image.
+Other members (for example, byte order, bitmap_unit, and so forth)
+are characteristics of both the image and the server.  
+If these members
+differ between the image and the server, 
+<function>XPutImage</function>
+makes the appropriate conversions.
+The first byte of the first line of
+plane n must be located at the address (data + (n * height * bytes_per_line)).
+For a description of the 
+<structname>XImage</structname>
+structure,
+see section 8.7.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate an 
+<structname>XImage</structname>
+structure and initialize it with image format values from a display, use
+<function>XCreateImage</function>.
+<indexterm significance="preferred"><primary>XCreateImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreateimage'>
+<funcprototype>
+  <funcdef>XImage *<function>XCreateImage</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Visual<parameter> *visual</parameter></paramdef>
+  <paramdef>unsignedint<parameter> depth</parameter></paramdef>
+  <paramdef>int<parameter> format</parameter></paramdef>
+  <paramdef>int<parameter> offset</parameter></paramdef>
+  <paramdef>char<parameter> *data</parameter></paramdef>
+  <paramdef>unsignedint<parameter> width</parameter></paramdef>
+  <paramdef>unsignedint<parameter> height</parameter></paramdef>
+  <paramdef>int<parameter> bitmap_pad</parameter></paramdef>
+  <paramdef>int<parameter> bytes_per_line</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>visual</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>Visual</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>depth</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the depth of the image.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the format for the image.
+You can pass
+<symbol>XYBitmap</symbol>,
+<symbol>XYPixmap</symbol>,
+or 
+<symbol>ZPixmap</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>offset</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of pixels to ignore at the beginning of the scanline.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the image data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the width of the image, in pixels.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the height of the image, in pixels.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bitmap_pad</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the quantum of a scanline (8, 16, or 32).
+In other words, the start of one scanline is separated in client memory from 
+the start of the next scanline by an integer multiple of this many bits.  
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bytes_per_line</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of bytes in the client image between
+the start of one scanline and the start of the next.  
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateImage</function>
+function allocates the memory needed for an
+<structname>XImage</structname>
+structure for the
+specified display but does not allocate space for the image itself.
+Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
+values from the display and returns a pointer to the 
+<structname>XImage</structname>
+structure.
+The red, green, and blue mask values are defined for Z format images only
+and are derived from the 
+<structname>Visual</structname>
+structure passed in.
+Other values also are passed in.
+The offset permits the rapid displaying of the image without requiring each 
+scanline to be shifted into position.
+If you pass a zero value in bytes_per_line,
+Xlib assumes that the scanlines are contiguous
+in memory and calculates the value of bytes_per_line itself.
+</para>
+<para>
+<!-- .LP -->
+Note that when the image is created using
+<function>XCreateImage</function>,
+<function>XGetImage</function>,
+or
+<function>XSubImage</function>,
+the destroy procedure that the 
+<function>XDestroyImage</function>
+function calls frees both the image structure 
+and the data pointed to by the image structure.
+</para>
+<para>
+<!-- .LP -->
+The basic functions used to get a pixel, set a pixel, create a subimage,
+and add a constant value to an image are defined in the image object.
+The functions in this section are really macro invocations of the functions
+in the image object and are defined in
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a pixel value in an image, use
+<function>XGetPixel</function>.
+<indexterm significance="preferred"><primary>XGetPixel</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetpixel'>
+<funcprototype>
+  <funcdef>unsigned long <function>XGetPixel</function></funcdef>
+  <paramdef>XImage<parameter> *ximage</parameter></paramdef>
+  <paramdef>int<parameter> x</parameter></paramdef>
+  <paramdef>int<parameter> y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ximage</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the image.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetPixel</function>
+function returns the specified pixel from the named image.
+The pixel value is returned in normalized format (that is,
+the least significant byte of the long is the least significant byte
+of the pixel).
+The image must contain the x and y coordinates.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a pixel value in an image, use
+<function>XPutPixel</function>.
+<indexterm significance="preferred"><primary>XPutPixel</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xputpixel'>
+<funcprototype>
+  <funcdef><function>XPutPixel</function></funcdef>
+  <paramdef>XImage<parameter> *ximage</parameter></paramdef>
+  <paramdef>int<parameter> x</parameter></paramdef>
+  <paramdef>int<parameter> y</parameter></paramdef>
+  <paramdef>unsignedlong<parameter> pixel</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ximage</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the image.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>pixel</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the new pixel value.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPutPixel</function>
+function overwrites the pixel in the named image with the specified pixel value.
+The input pixel value must be in normalized format
+(that is, the least significant byte of the long is the least significant
+byte of the pixel).
+The image must contain the x and y coordinates.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a subimage, use
+<function>XSubImage</function>.
+<indexterm significance="preferred"><primary>XSubImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsubimage'>
+<funcprototype>
+  <funcdef>XImage *<function>XSubImage</function></funcdef>
+  <paramdef>XImage<parameter> *ximage</parameter></paramdef>
+  <paramdef>int<parameter> x</parameter></paramdef>
+  <paramdef>int<parameter> y</parameter></paramdef>
+  <paramdef>unsignedint<parameter> subimage_width</parameter></paramdef>
+  <paramdef>unsignedint<parameter> subimage_height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ximage</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the image.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>subimage_width</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the width of the new subimage, in pixels.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>subimage_height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the height of the new subimage, in pixels.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSubImage</function>
+function creates a new image that is a subsection of an existing one.
+It allocates the memory necessary for the new
+<structname>XImage</structname>
+structure
+and returns a pointer to the new image.
+The data is copied from the source image,
+and the image must contain the rectangle defined by x, y, subimage_width,
+and subimage_height.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To increment each pixel in an image by a constant value, use
+<function>XAddPixel</function>.
+<indexterm significance="preferred"><primary>XAddPixel</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xaddpixel'>
+<funcprototype>
+  <funcdef><function>XAddPixel</function></funcdef>
+  <paramdef>XImage<parameter> *ximage</parameter></paramdef>
+  <paramdef>long<parameter> value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ximage</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the image.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>value</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the constant value that is to be added.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddPixel</function>
+function adds a constant value to every pixel in an image.
+It is useful when you have a base pixel value from allocating
+color resources and need to manipulate the image to that form.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To deallocate the memory allocated in a previous call to
+<function>XCreateImage</function>,
+use
+<function>XDestroyImage</function>.
+<indexterm significance="preferred"><primary>XDestroyImage</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroyimage'>
+<funcprototype>
+  <funcdef><function>XDestroyImage</function></funcdef>
+  <paramdef>XImage *<parameter>ximage</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>ximage</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the image.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDestroyImage</function>
+function deallocates the memory associated with the
+<structname>XImage</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+Note that when the image is created using
+<function>XCreateImage</function>,
+<function>XGetImage</function>,
+or 
+<function>XSubImage</function>,
+the destroy procedure that this macro calls
+frees both the image structure and the data pointed to by the image structure. 
+</para>
+</sect1>
+<sect1 id="Manipulating_Bitmaps">
+<title>Manipulating Bitmaps</title>
+<!-- .XS -->
+<!-- (SN Manipulating Bitmaps  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to read a bitmap from a file,
+save a bitmap to a file, or create a bitmap. 
+This section describes those functions that transfer bitmaps to and
+from the client's file system, thus allowing their reuse in a later
+connection (for example, from an entirely different client or to a
+different display or server).
+</para>
+<para>
+<!-- .LP -->
+The X version 11 bitmap file format is:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+#define <emphasis remap='I'>name</emphasis>_width <emphasis remap='I'>width</emphasis>
+#define <emphasis remap='I'>name</emphasis>_height <emphasis remap='I'>height</emphasis>
+#define <emphasis remap='I'>name</emphasis>_x_hot <emphasis remap='I'>x</emphasis>
+#define <emphasis remap='I'>name</emphasis>_y_hot <emphasis remap='I'>y</emphasis>
+static unsigned char <emphasis remap='I'>name</emphasis>_bits[] = { 0x<emphasis remap='I'>NN</emphasis>,... }
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The lines for the variables ending with _x_hot and _y_hot suffixes are optional
+because they are present only if a hotspot has been defined for this bitmap.
+The lines for the other variables are required.
+The word ``unsigned'' is optional;
+that is, the type of the _bits array can be ``char'' or ``unsigned char''.
+The _bits array must be large enough to contain the size bitmap.
+The bitmap unit is 8.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a bitmap from a file and store it in a pixmap, use
+<function>XReadBitmapFile</function>.
+<indexterm significance="preferred"><primary>XReadBitmapFile</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xreadbitmapfile'>
+<funcprototype>
+  <funcdef>int <function>XReadBitmapFile</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>char<parameter> *filename</parameter></paramdef>
+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+  <paramdef>Pixmap<parameter> *bitmap_return</parameter></paramdef>
+  <paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Dr \ that indicates the screen -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable(Dr. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>filename</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the width and height values of the read in bitmap file.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bitmap_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the bitmap that is created.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_hot_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y_hot_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the hotspot coordinates.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XReadBitmapFile</function>
+function reads in a file containing a bitmap.
+The file is parsed in the encoding of the current locale.
+The ability to read other than the standard format 
+is implementation-dependent.
+If the file cannot be opened, 
+<function>XReadBitmapFile</function>
+returns 
+<returnvalue>BitmapOpenFailed</returnvalue>.
+If the file can be opened but does not contain valid bitmap data, 
+it returns 
+<returnvalue>BitmapFileInvalid</returnvalue>.
+If insufficient working storage is allocated,
+it returns
+<returnvalue>BitmapNoMemory</returnvalue>.
+If the file is readable and valid,
+it returns 
+<returnvalue>BitmapSuccess</returnvalue>.
+</para>
+<para>
+<!-- .LP -->
+<function>XReadBitmapFile</function>
+returns the bitmap's height and width, as read
+from the file, to width_return and height_return.
+It then creates a pixmap of the appropriate size, 
+reads the bitmap data from the file into the pixmap,
+and assigns the pixmap to the caller's variable bitmap.  
+The caller must free the bitmap using 
+<function>XFreePixmap</function>
+when finished.
+If <emphasis remap='I'>name</emphasis>_x_hot and <emphasis remap='I'>name</emphasis>_y_hot exist,
+<function>XReadBitmapFile</function>
+returns them to x_hot_return and y_hot_return;
+otherwise, it returns &minus;1,&minus;1.
+</para>
+<para>
+<!-- .LP -->
+<function>XReadBitmapFile</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadDrawable</errorname>,
+and
+<errorname>BadGC</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a bitmap from a file and return it as data, use
+<function>XReadBitmapFileData</function>.
+<indexterm significance="preferred"><primary>XReadBitmapFileData</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xreadbitmapfiledata'>
+<funcprototype>
+  <funcdef>int <function>XReadBitmapFileData</function></funcdef>
+  <paramdef>char<parameter> *filename</parameter></paramdef>
+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+  <paramdef>unsignedchar<parameter> *data_return</parameter></paramdef>
+  <paramdef>int*x_hot_return,<parameter> *y_hot_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>filename</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the width and height values of the read in bitmap file.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the bitmap data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_hot_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y_hot_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the hotspot coordinates.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XReadBitmapFileData</function>
+function reads in a file containing a bitmap, in the same manner as
+<function>XReadBitmapFile</function>,
+but returns the data directly rather than creating a pixmap in the server.
+The bitmap data is returned in data_return; the client must free this
+storage when finished with it by calling
+<function>XFree</function>.
+The status and other return values are the same as for
+<function>XReadBitmapFile</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To write out a bitmap from a pixmap to a file, use
+<function>XWriteBitmapFile</function>.
+<indexterm significance="preferred"><primary>XWriteBitmapFile</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xwritebitmapfile'>
+<funcprototype>
+  <funcdef>int <function>XWriteBitmapFile</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *filename</parameter></paramdef>
+  <paramdef>Pixmap<parameter> bitmap</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>intx_hot,<parameter> y_hot</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>filename</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bitmap</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the bitmap.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_hot</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y_hot</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify where to place the hotspot coordinates (or &minus;1,&minus;1 if none are present)
+in the file.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWriteBitmapFile</function>
+function writes a bitmap out to a file in the X Version 11 format.
+The name used in the output file is derived from the file name
+by deleting the directory prefix.
+The file is written in the encoding of the current locale.
+If the file cannot be opened for writing, 
+it returns 
+<returnvalue>BitmapOpenFailed</returnvalue>.
+If insufficient memory is allocated,
+<function>XWriteBitmapFile</function>
+returns
+<returnvalue>BitmapNoMemory</returnvalue>;
+otherwise, on no error,
+it returns
+<returnvalue>BitmapSuccess</returnvalue>.
+If x_hot and y_hot are not &minus;1, &minus;1,
+<function>XWriteBitmapFile</function>
+writes them out as the hotspot coordinates for the bitmap.
+</para>
+<para>
+<!-- .LP -->
+<function>XWriteBitmapFile</function>
+can generate
+<errorname>BadDrawable</errorname>
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a pixmap and then store bitmap-format data into it, use
+<function>XCreatePixmapFromBitmapData</function>.
+<indexterm significance="preferred"><primary>XCreatePixmapFromBitmapData</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatepixmapfrombitmapdata'>
+<funcprototype>
+  <funcdef>Pixmap <function>XCreatePixmapFromBitmapData</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>char<parameter> *data</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+  <paramdef>unsignedlongfg,<parameter> bg</parameter></paramdef>
+  <paramdef>unsignedint<parameter> depth</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Dr \ that indicates the screen -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable(Dr. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the data in bitmap format.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>fg</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the foreground and background pixel values to use.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>depth</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the depth of the pixmap.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreatePixmapFromBitmapData</function>
+function creates a pixmap of the given depth and then does a bitmap-format
+<function>XPutImage</function>
+of the data into it.
+The depth must be supported by the screen of the specified drawable,
+or a
+<errorname>BadMatch</errorname>
+error results.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreatePixmapFromBitmapData</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To include a bitmap written out by 
+<function>XWriteBitmapFile</function>
+<indexterm><primary>XWriteBitmapFile</primary></indexterm>
+in a program directly, as opposed to reading it in every time at run time, use
+<function>XCreateBitmapFromData</function>.
+<indexterm significance="preferred"><primary>XCreateBitmapFromData</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatebitmapfromdata'>
+<funcprototype>
+  <funcdef>Pixmap <function>XCreateBitmapFromData</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>char<parameter> *data</parameter></paramdef>
+  <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Dr \ that indicates the screen -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable(Dr. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the location of the bitmap data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the width and height.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCreateBitmapFromData</function>
+function allows you to include in your C program (using
+<code>#include</code>)
+a bitmap file that was written out by
+<function>XWriteBitmapFile</function>
+(X version 11 format only) without reading in the bitmap file.
+The following example creates a gray bitmap:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+#include "gray.bitmap"
+<!-- .sp 6p -->
+Pixmap bitmap;
+bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If insufficient working storage was allocated,
+<function>XCreateBitmapFromData</function>
+returns
+<symbol>None</symbol>.
+It is your responsibility to free the
+bitmap using
+<function>XFreePixmap</function>
+when finished.
+</para>
+<para>
+<!-- .LP -->
+<function>XCreateBitmapFromData</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadGC</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Using_the_Context_Manager">
+<title>Using the Context Manager</title>
+<!-- .XS -->
+<!-- (SN Using the Context Manager  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The context manager provides a way of associating data with an X resource ID
+(mostly typically a window) in your program.  
+Note that this is local to your program;
+the data is not stored in the server on a property list.
+Any amount of data in any number of pieces can be associated with a
+resource ID,
+and each piece of data has a type associated with it.  
+The context manager requires knowledge of the resource ID
+and type to store or retrieve data.
+</para>
+<para>
+<!-- .LP -->
+Essentially, the context manager can be viewed as a two-dimensional, 
+sparse array:  one dimension is subscripted by the X resource ID
+and the other by a context type field.
+Each entry in the array contains a pointer to the data.
+Xlib provides context management functions with which you can
+save data values, get data values, delete entries, and create a unique
+context type.
+The symbols used are in
+<filename class="headerfile">&lt;X11/Xutil.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xutil.h&gt;</filename></secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To save a data value that corresponds to a resource ID and context type, use
+<function>XSaveContext</function>.
+<indexterm significance="preferred"><primary>XSaveContext</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsavecontext'>
+<funcprototype>
+  <funcdef>int <function>XSaveContext</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XID<parameter> rid</parameter></paramdef>
+  <paramdef>XContext<parameter> context</parameter></paramdef>
+  <paramdef>XPointer<parameter> data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rid</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource ID with which the data is associated.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>context</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the context type to which the data belongs.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the data to be associated with the window and type.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If an entry with the specified resource ID and type already exists,
+<function>XSaveContext</function>
+overrides it with the specified context.
+The
+<function>XSaveContext</function>
+function returns a nonzero error code if an error has occurred
+and zero otherwise.
+Possible errors are
+<symbol>XCNOMEM</symbol>
+(out of memory).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the data associated with a resource ID and type, use
+<function>XFindContext</function>.
+<indexterm significance="preferred"><primary>XFindContext</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfindcontext'>
+<funcprototype>
+  <funcdef>int <function>XFindContext</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XID<parameter> rid</parameter></paramdef>
+  <paramdef>XContext<parameter> context</parameter></paramdef>
+  <paramdef>XPointer<parameter> *data_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rid</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource ID with which the data is associated.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>context</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the context type to which the data belongs.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the data.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Because it is a return value,
+the data is a pointer.
+The
+<function>XFindContext</function>
+function returns a nonzero error code if an error has occurred
+and zero otherwise.
+Possible errors are
+<symbol>XCNOENT</symbol>
+(context-not-found).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete an entry for a given resource ID and type, use
+<function>XDeleteContext</function>.
+<indexterm significance="preferred"><primary>XDeleteContext</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdeletecontext'>
+<funcprototype>
+  <funcdef>int <function>XDeleteContext</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XID<parameter> rid</parameter></paramdef>
+  <paramdef>XContext<parameter> context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rid</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the resource ID with which the data is associated.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>context</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the context type to which the data belongs.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteContext</function>
+function deletes the entry for the given resource ID 
+and type from the data structure.
+This function returns the same error codes that
+<function>XFindContext</function>
+returns if called with the same arguments.
+<function>XDeleteContext</function>
+does not free the data whose address was saved.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a unique context type that may be used in subsequent calls to
+<function>XSaveContext</function>
+and
+<function>XFindContext</function>,
+use
+<function>XUniqueContext</function>.
+</para>
+<para>XContext XuniqueContext()</para>
+
+</sect1>
+</chapter>